[Previous]
[Contents]
[Next]

creat()

create and open a file at the operating system level

Synopsis:

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int creat( const char *path, mode_t mode );

Description:

The creat() function creates (and opens) a file at the operating system level. It's equivalent to:

  open( path, O_WRONLY | O_CREAT | O_TRUNC, mode );

The name of the file to be created is given by path. When the file exists (it must be writable), it is truncated to contain no data, and the existing mode setting is not changed.

When the file doesn't exist, it is created with access permissions given by the mode argument. The access permissions for the file or directory are specified as a combination of bits. These are defined in the <sys/stat.h> header file, and are described in the section on this file in the Header Files chapter.

Returns:

If successful, creat() returns a descriptor for the file. When an error occurs while opening the file, -1 is returned, and errno is set to indicate the error.

Errors:

EACCES
Indicates one of the following problems with permissions:
EBADFSYS
While attempting to open the named file, either the file itself or a component of the path prefix was found to be corrupted. A system failure - from which no automatic recovery is possible - occurred while the file was being written to or while the directory was being updated. It will be necessary to invoke appropriate systems administrative procedures to correct this situation before proceeding.
EBUSY
The file named by path is a block special device that is already open for writing, or path names a file that is on a file system mounted on a block special device that is already open for writing.
EINTR
The creat() operation was interrupted by a signal.
EISDIR
The named file is a directory, and the file creation flags specify write-only or read/write access.
EMFILE
Too many file descriptors are currently in use by this process.
ENAMETOOLONG
The length of the path string exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.
ENFILE
Too many files are currently open in the system.
ENOENT
Either the path prefix does not exist, or the path argument points to an empty string.
ENOSPC
The directory or file system that would contain the new file cannot be extended.
ENOTDIR
A component of the path prefix is not a directory.
EROFS
The named file resides on a read-only file system.

Examples:

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

void main()
  {
    int filedes;

    filedes = creat( "file",
                 S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP );
    if( filedes != -1 ) {

      /* process file */

      close( filedes );
    }
  }

Classification:

POSIX 1003.1

Safety:
Interrupt handler No
Signal handler Yes, but modifies errno
Thread Yes

See also:

chsize(), close(), dup(), dup2(), eof(), errno, exec... functions, fcntl(), filelength(), fileno(), fstat(), isatty(), lseek(), open(), read(), setmode(), sopen(), stat(), tell(), write(), umask()


[Previous]
[Contents]
[Next]