CREAT(2V)

NAME
creat - create a new file

SYNOPSIS

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

SYSTEM V SYNOPSIS

#include <sys/stat.h>

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

DESCRIPTION

This interface is made obsolete by open(2V), since,

    creat(path, mode);

is equivalent to

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

creat() creates a new ordinary file or prepares to rewrite an existing file named by the pathname pointed to by path. If the file did not exist, it is given the mode mode, as modified by the process's mode mask (see umask(2V)). See stat(2V) for the construction of mode.

If the file exists, its mode and owner remain unchanged, but it is truncated to 0 length. Otherwise, the file's owner ID is set to the effective user ID of the process, and upon successful completion, creat() marks for update the st_atime, st_ctime, and st_mtime fields of the file (see stat(2V)) and the st_ctime and st_mtime fields of the parent directory.

The file's group ID is set to either:

•   the effective group ID of the process, if the filesystem was not mounted with the BSD file-creation semantics flag (see mount(2V)) and the set-gid bit of the parent directory is clear, or

•   the group ID of the directory in which the file is created.

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(2V).

•   The “save text image after execution” (sticky) bit of the mode is cleared. See chmod(2V).

•   The “set group ID on execution” bit of the mode is cleared if the effective user ID of the process is not super-user and the process is not a member of the group of the created file.

Upon successful completion, the file descriptor is returned and the file is open for writing, even if the access permissions of the file mode do not permit writing. The file pointer is set to the beginning of the file. The file descriptor is set to remain open across execve(2V) system calls. See fcntl(2V).

If the file did not previously exist, upon successful completion, creat() marks for update the st_ctime and st_mtime fields of the file and the st_ctime and st_mtime fields of the parent directory.

RETURN VALUES

creat() returns a non-negative descriptor that only permits writing on success. On failure, it returns -1 and sets errno to indicate the error.

ERRORS

EACCES
    Search permission is denied for a component of the path prefix.

    The file referred to by path does not exist and the directory in which it is to be created is not writable.

    The file referred to by path exists, but it is unwritable.

EDQUOT
    The directory in which the entry for the new file is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted.

    The user's quota of inodes on the file system on which the file is being created has been exhausted.

EFAULT
    path points outside the process's allocated address space.

EINTR
    The creat() operation was interrupted by a signal.

EIO An I/O error occurred while making the directory entry or allocating the inode.

EISDIR
    The file referred to by path is a directory.

ELOOP
    Too many symbolic links were encountered in translating the pathname pointed to by path.

EMFILE
    There are already too many files open.

ENAMETOOLONG
    The length of the path argument exceeds {PATH_MAX}.

    A pathname component is longer than {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect (see pathconf(2V)).

ENFILE
    The system file table is full.

ENOENT
    A component of the path prefix does not exist.

ENOSPC
    The directory in which the entry for the new file is being placed cannot be extended because there is no space left on the file system containing the directory.

    There are no free inodes on the file system on which the file is being created.

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

ENXIO
    The file is a character special or block special file, and the associated device does not exist.

EOPNOTSUPP
    The file was a socket (not currently implemented).

EROFS
    The file referred to by path resides, or would reside, on a read-only file system.

SYSTEM V ERRORS

In addition to the above, the following may also occur:

ENOENT
    path points to an empty string.

SEE ALSO
close(2V), chmod(2V), execve(2V), fcntl(2V), flock(2), mount(2V), open(2V), write(2V), umask(2V)

NOTES

The mode given is arbitrary; it need not allow writing. This feature has been used in the past by programs to construct a simple exclusive locking mechanism. It is replaced by the O_EXCL open mode, or flock(2) facility.