creat(S)                       6 January 1993                       creat(S)


 Name

    creat - create a new file or rewrite an existing one

 Syntax


    cc  . . .  -lc


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

    int creat (path, mode)
    char *path;
    int mode;


 Description

    The creat system call creates a new ordinary file or prepares to rewrite
    an existing file named by the path name pointed to by path.

    If the file exists, the length is truncated to 0 and the mode and owner
    are unchanged.  Otherwise, the file's owner ID is set to the effective
    user ID of the process; the group ID of the process is set to the effec-
    tive group ID of the process; and the low-order 12 bits of the file mode
    are set to the value of mode modified as follows:

    +  All bits set in the process's file mode creation mask are cleared (see
       umask(S)).

    +  The ``save text image after execution bit'' of the mode is cleared
       (see chmod(S)).

    Upon successful completion, a write-only file descriptor is returned and
    the file is open for writing, even if the mode does not permit writing.
    The file pointer is set to the beginning of the file.  The file descrip-
    tor is set to remain open across exec system calls (see fcntl(S)).  No
    process may have more than FOPENMAX files open simultaneously.  A new
    file may be created with a mode that forbids writing.

    Symbolic constants defining the access permission bits are specified in
    the <sys/stat.h> header file and should be used to construct mode (see
    chmod(S)).

    The call creat(path, mode) is equivalent to the following (see open(S)):

            open(path, OWRONLY | OCREAT | OTRUNC, mode)


    The creat system call fails if one or more of the following is true:

    [EACESS]

                   1.  Search permission is denied on a component of the path
                       prefix.

                   2.  The file does not exist and the directory in which the
                       file is to be created does not permit writing.

                   3.  The file exists and write permission is denied.

    [EAGAIN]       The file exists, mandatory file/record locking is set, and
                   there are outstanding record locks on the file (see
                   chmod(S)).

    [EFAULT]       The path argument points outside the allocated address
                   space of the process.

    [EINTR]        A signal was caught during the creat system call.

    [EISDIR]       The named file is an existing directory.

    [EMFILE]       NOFiles file descriptors are currently open.

    [EMULTIHOP]    Components of path require hopping to multiple remote ma-
                   chines.

    [ENFILE]       The system file table is full.

    [ENOENT]

                   1.  A component of the path prefix does not exist.

                   2.  The pathname is null.

    [ENOLINK]      path points to a remote machine and the link to that ma-
                   chine is no longer active.

    [ENOSPC]       The filesystem is out of inodes.

    [ENOTDIR]      A component of the path prefix is not a directory.

    [EROFS]        The named file resides or would reside on a read-only file
                   system.

    [ETXTBSY]      The file is a pure procedure (shared text) file that is
                   being executed.


 Diagnostics

    Upon successful completion, a non-negative integer, namely the file
    descriptor, is returned.  Otherwise, a value of -1 is returned, and errno
    is set to indicate the error.

 See also

    chmod(S), close(S), dup(S), fcntl(S), lseek(S), open(S), read(S),
    umask(S), write(S)

 Standards conformance

    creat is conformant with:
    AT&T SVID Issue 2;
    X/Open Portability Guide, Issue 3, 1989;
    Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2);
    IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C
    Language] (ISO/IEC 9945-1);
    and NIST FIPS 151-1.