'\"macro stdmacro
.if n .pH g2.creat @(#)creat	40.25 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} creat 2 "" "\&"
.if \nX=1 .ds x} creat 2 ""
.if \nX=2 .ds x} creat 2 "" "\&"
.if \nX=3 .ds x} creat "" "" "\&"
.TH \*(x}
.SH NAME
\f4creat\f1 \- create a new file or rewrite an existing one
.SH SYNOPSIS
\f4#include <sys/types.h>\f1
.br
\f4#include <sys/stat.h>\f1
.br
\f4#include <fcntl.h>\f1
.PP
\f4int creat(const char \(**path, mode_t mode); \f1
.SH DESCRIPTION
\f4creat\fP
creates a new ordinary file or prepares to rewrite an existing file
named by the
path name
pointed to by
.IR path .
.PP
If the file exists, the length is truncated to 0 and the mode
and owner are unchanged.
.PP
If the file does not exist
the file's owner
.SM ID
is set to the effective user
.SM ID
of the process.
The group
.SM ID
of the file
is set to the effective group
.SM ID
of the process, or
if the \f4S_ISGID\fP bit is set in the parent directory then the group
.SM ID
of the file is inherited from the parent directory.  
The access permission bits of the file mode are set to the value of
.I mode\^
modified as follows:
.IP
If the group
.SM ID
of the new file does not match the effective group
.SM ID
or one of the supplementary group
\s-1ID\s0s, the \f4S_ISGID\fP bit is cleared.  
.IP
All bits set in the process's file mode creation mask are cleared
[see
\f4umask\fP(2)].
.IP
The ``save text image after execution bit'' of the mode is cleared
[see
\f4chmod\fP(2) for the values of mode].
.PP
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 descriptor is set to remain open across
\f4exec\fP
system calls
[see
\f4fcntl\fP(2)].
A new file may be created with a mode that forbids writing.
.PP
The call \f4creat(\f2path\fP, \f2mode\f4)\f1 is equivalent to:
.PP
	\f4open(\f2path\fP, \f4O_WRONLY | O_CREAT | O_TRUNC\fP, \f2mode\fP)
.PP
\f4creat\fP
fails if one or more of the following are true:
.TP 20
\f4EACCES\fP
Search permission is denied on a component of the
path prefix.
.TP
\f4EACCES\fP
The file does not exist and the directory in which the file
is to be created does not permit writing.
.TP
\f4EACCES\fP
The file exists and write permission is denied.
.TP
\f4EAGAIN\fP
The file exists,
mandatory file/record locking is set,
and there are outstanding record locks on the file
[see \f4chmod\fP(2)].
.TP
\f4EFAULT\fP
.I path\^
points outside the allocated address space of the process.
.TP
\f4EISDIR\fP
The named file is an existing directory.
.TP
\f4EINTR\fP
A signal was caught during the \f4creat\fP system call.
.TP
\f4ELOOP\fP
Too many symbolic links were encountered in translating \f2path\f1.
.TP
\f4EMFILE\fP
The process has too many open files [see
\f4getrlimit\fP(2)].
.TP 20
\f4ENAMETOOLONG\fP
The length of the \f2path\f1 argument exceeds {\f4PATH_MAX\f1}, or the
length of a \f2path\f1 component exceeds {\f4NAME_MAX\f1} while
\f4_POSIX_NO_TRUNC\f1 is in effect.
.TP 20
\f4ENOTDIR\fP
A component of the
path prefix
is not a directory.
.TP
\f4ENOENT\fP
A component of the
path prefix
does not exist.
.TP
\f4ENOENT\fP
The path name is null.
.TP
\f4EROFS\fP
The named file resides or would reside on a read-only file system.
.TP
\f4ETXTBSY\fP
The file is a pure procedure (shared text) file that is being executed.
.TP
\f4ENFILE\fP
The system file table is full.
.TP
\f4ENOLINK\fP
\f2path\f1 points to a remote machine and the link
to that machine is no longer active.
.TP
\f4EMULTIHOP\fP
Components of \f2path\f1 require hopping to multiple
remote machines.
.TP
\f4ENOSPC\fP
The file system is out of inodes.
.SH "SEE ALSO"
\f4chmod\fP(2),
\f4close\fP(2),
\f4dup\fP(2),
\f4fcntl\fP(2),
\f4getrlimit\fP(2),
\f4lseek\fP(2),
\f4open\fP(2),
\f4read\fP(2),
\f4umask\fP(2),
\f4write\fP(2),
\f4stat\fP(5).
.SH "DIAGNOSTICS"
Upon successful completion a non-negative integer,
namely the lowest numbered unused file descriptor,
is returned.
Otherwise, a value of \-1 is returned, no files are created or modified, and
\f4errno\fP
is set to indicate the error.
.\"	@(#)creat.2	6.2 of 9/6/83
.Ee
