creat(2)


creat, creat64 -- create a new file or rewrite an existing one

Synopsis

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

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

int creat64(const char *path, mode_t mode);

Description

creat creates a new ordinary file or prepares to rewrite an existing file named by the pathname pointed to by path.

If the file exists, the length is truncated to 0 and the mode and owner are unchanged.

If the file does not exist the file's owner ID is set to the effective user ID of the process. The group ID of the file is set to the effective group ID of the process, or if the S_ISGID bit is set in the parent directory then the group ID of the file is inherited from the parent directory.

The mode bits and Access Control List (ACL) of the file are based on the value of mode, modified as follows:

If creat succeeds, it returns a write-only file descriptor 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 descriptor is set to remain open across exec system calls (see fcntl(2)). A new file may be created with a mode that forbids writing.

The call creat(path, mode) is equivalent to:

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

The call creat64(path, mode) is equivalent to:

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

Return values

On success, creat and creat64 return a non-negative integer, namely the lowest numbered unused file descriptor. On failure, creat and creat64 return -1, set errno to identify the error, and no files are created or modified.

In the following condition, creat fails and sets errno to:


EOVERFLOW
The named file is a regular file and the size of the file cannot be represented correctly in an object of type off_t.

In the following conditions, creat and creat64 fail and set errno to:


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

EACCES
The file does not exist and write permission on the directory in which the file is to be created is denied.

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

EFAULT
path points outside the allocated address space of the process.

EINTR
A signal was caught during the creat or creat64 system call.

EISDIR
The named file is an existing directory.

ELOOP
Too many symbolic links were encountered in translating path.

EMFILE
The process has too many open files (see getrlimit(2)).

ENAMETOOLONG
The length of the path argument exceeds {PATH_MAX}, or the length of a path component exceeds {NAME_MAX} while _POSIX_NO_TRUNC is in effect.

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

ENOENT
A component of the path prefix does not exist.

ENOENT
The pathname is null.

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.

ENFILE
The system file table is full.

ENOLINK
path points to a remote machine and the link to that machine is no longer active.

EMULTIHOP
Components of path require hopping to multiple remote machines.

ENOSPC
The file system is out of inodes.

References

chmod(2), close(2), dup(2), fcntl(2), getrlimit(2), intro(2), lseek(2), open(2), read(2), stat(5), umask(2), write(2)

Notices

Considerations for threads programming

Open file descriptors are a process resource and available to any sibling thread; if used concurrently, actions by one thread can interfere with those of a sibling.

Considerations for large file support

creat64 supports large files, but is otherwise identical to creat. For details on programming for large file capable applications, see ``Large File Support'' in intro(2).
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004