creat

Purpose

     Creates a new file or rewrites an existing file.

Syntax

     #include <stat.h>

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

Description

     The creat system call creates a new ordinary file or pre-
     pares  to rewrite  an  existing file  named  by the  path
     parameter.  If Distributed Services  is installed on your
     system, this path can cross into another node.

     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 process's effec-
     tive user ID, the file's group ID is set to the process's
     effective group ID, and the low-order 12 bits of the file
     mode are set to the  value of the mode parameter modified
     as follows:

     o   Each bit set in the process's file mode creation mask
         clears the corresponding bit in  the mode that is set
         for the  file.  (For information about  the file mode
         creation mask, see "umask.")

     o   The save-text-image-after-execution  bit of  the file
         mode  (S_ISVTX) is  cleared.   (For more  information
         about this bit, see "chmod.")

     See "chmod" for a detailed explanation of file modes.

     No process can  have more than 200  files open simultane-
     ously.   A new  file  can  be created  with  a mode  that
     forbids writing.

     Note that the following two system calls are equivalent:

        creat (path, mode)

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

     See "open" for details about the open system call.

Return Value

     Upon successful completion, a file descriptor (a nonnega-
     tive  integer) is  returned and  the file  is opened  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.  (For information about control of open files, see
     "fcntl.")

     If the creat system call fails, a value of -1 is returned
     and errno is set to indicate the error.

Diagnostics

     The creat  system call fails if  one or more of  the fol-
     lowing are true:

     ENOTDIR    A component of the path prefix is not a direc-
                tory.

     ENOENT     A component of the path prefix does not exist.

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

     ENOENT     The path name is NULL.

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

     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.

     EACCES     The  file  exists   and  write  permission  is
                denied.

     EISDIR     The named file is an existing directory.

     EMFILE     Two  hundred (200)  file descriptors  are cur-
                rently open.

     EFAULT     The path parameter &pointsout..

     ENFILE     The system file table is full.

     EAGAIN     The named file contains a record lock owned by
                another process.  See  "lockf" for information
                about record locks.

     ESTALE     The  process's root  or  current directory  is
                located in a virtual file system that has been
                unmounted.

     If  Distributed Services  is  installed  on your  system,
     creat can also  fail if one or more of  the following are
     true:

     EINVAL        The path parameter identifies a remote file
                   that is  neither a directory nor  a regular
                   file.

     EBUSY         The  special file  to open  for writing  is
                   already mounted.

     EDIST         The   server   has  blocked   new   inbound
                   requests.

     EDIST         Outbound requests are currently blocked.

     EDIST         The server has a  release level of Distrib-
                   uted Services that  cannot communicate with
                   this node.

     EAGAIN        The  server  is  too  busy  to  accept  the
                   request.

     ESTALE        The file  descriptor for a remote  file has
                   become obsolete.

     EPERM         The translate tables of  the server did not
                   contain any entry  for either the effective
                   user  ID  or  effective  group  ID  of  the
                   calling process.

     ENODEV        The named file is  a remote file located on
                   a  device that  has been  unmounted at  the
                   server.

     ENOMEM        Either  this node  or the  server does  not
                   have enough memory available to service the
                   request.

     ENOCONNECT    An attempt to establish  a new network con-
                   nection with a remote node failed.

     EBADCONNECT   An attempt to use  an existing network con-
                   nection with a remote node failed.

Related Information

     In  this  book:    "chmod,"  "close,"   "dup,"  "lseek,"
     "open," "read, readx,"  "umask," and "write, writex."