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 the group
ID
of the new file does not match the effective group
ID
or one of the supplementary group
IDs, the S_ISGID bit is cleared.
-
All bits set in the process file mode creation mask are cleared
(see
umask(2)).
-
The ``save text image after execution bit'' of the mode is cleared
(see
chmod(2)
for the values of mode)
-
For each default ACL entry in the parent directory's ACL a corresponding
ACL entry is created in the new file's ACL.
(see
acl(2)).
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