NAME

     open, creat - open and possibly create a file or device


SYNOPSIS

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

     int open(const char *pathname, int flags));
     int open(const char *pathname, int flags, mode_t mode
     int creat(const char *pathname, mode_t mode));


DESCRIPTION

     open attempts to open a file and return a file descriptor (a
     small, non-negative integer for use in read, write, etc.)

     flags is one of O_RDONLY, O_WRONLY or O_RDWR  which  request
     opening   the  file  read-only,  write-only  or  read/write,
     respectively.

     flags may also be bitwise-or'd with one or more of the  fol-
     lowing:

     O_CREAT If the file does not exist it will be created.

     O_EXCL  When used with O_CREAT, if the file  already  exists
             it  is  an  error and the open will fail.  O_EXCL is
             broken on NFS file systems, programs which  rely  on
             it  for performing locking tasks will contain a race
             condition.  The solution for performing atomic  file
             locking  using a lockfile is to create a unique file
             on the same fs  (e.g.,  incorporating  hostname  and
             pid), use link(2) to make a link to the lockfile and
             use stat(2) on the unique file to check if its  link
             count  has  increased  to  2.  Do not use the return
             value of the link() call.

     O_NOCTTY
             If pathname refers to a terminal device - see tty(4)
             -  it will not become the process's controlling ter-
             minal even if the process does not have one.

     O_TRUNC If the file already exists it will be truncated.

     O_APPEND
             The file is opened in append  mode.  Initially,  and
             before each write, the file pointer is positioned at
             the end of the file, as if with lseek.  O_APPEND may
             lead  to corrupted files on NFS file systems if more
             than one process appends data to  a  file  at  once.
             This  is because NFS does not support appending to a
             file, so the client kernel has to simulate it, which
             can't be done without a race condition.

     O_NONBLOCK or O_NDELAY
             The file is opened in non-blocking mode. Neither the
             open  nor  any  subsequent  operations  on  the file
             descriptor which is returned will cause the  calling
             process to wait.

     O_SYNC  The file is opened for synchronous I/O.  Any  writes
             on the resulting file descriptor will block the cal-
             ling process until  the  data  has  been  physically
             written  to  the  underlying hardware.  See RESTRIC-
             TIONS below, though.

     Some of these optional flags  can  be  altered  using  fcntl
     after the file has been opened.

     mode specifies the permissions to  use  if  a  new  file  is
     created.  It is modified by the process's umask in the usual
     way: the  permissions  of  the  created  file  are  (mode  &
     ~umask).

     The following symbolic constants are provided for mode:

     S_IRWXU
          00700 user (file owner) has  read,  write  and  execute
          permission

     S_IRUSR (S_IREAD)
          00400 user has read permission

     S_IWUSR (S_IWRITE)
          00200 user has write permission

     S_IXUSR (S_IEXEC)
          00100 user has execute permission

     S_IRWXG
          00070 group has read, write and execute permission

     S_IRGRP
          00040 group has read permission

     S_IWGRP
          00020 group has write permission

     S_IXGRP
          00010 group has execute permission

     S_IRWXO
          00007 others have read, write and execute permission

     S_IROTH
          00004 others have read permission

     S_IWOTH
          00002 others have write permisson

     S_IXOTH
          00001 others have execute permission

     mode should always be  specified  when  O_CREAT  is  in  the
     flags, and is ignored otherwise.

     creat  is  equivalent  to   open   with   flags   equal   to
     O_CREAT|O_WRONLY|O_TRUNC.


RETURN VALUE

     open and creat return the new file descriptor, or -1  if  an
     error  occurred (in which case, errno is set appropriately).
     Note that open can open device special files, but creat can-
     not create them - use mknod(2) instead.

     On NFS file systems  with  UID  mapping  enabled,  open  may
     return  a  file  descriptor  but  e.g.  read(2) requests are
     denied with EACCES.  This is  because  the  client  performs
     open  by  checking  the permissions, but UID mapping is per-
     formed by the server upon read and write requests.


ERRORS

     EEXIST  pathname already exists and O_CREAT and O_EXCL  were
             used.

     EISDIR  pathname  refers  to  a  directory  and  the  access
             requested involved writing.

     ETXTBSY pathname refers to  an  executable  image  which  is
             currently   being  executed  and  write  access  was
             requested.

     EFAULT  pathname  points  outside  your  accessible  address
             space.

     EACCES  The requested access to the file is not allowed,  or
             one  of  the  directories  in pathname did not allow
             search (execute) permission.

     ENAMETOOLONG
             pathname was too long.

     ENOENT  A directory component in pathname does not exist  or
             is a dangling symbolic link.

     ENOTDIR A component used as a directory in pathname is  not,
             in fact, a directory.

     EMFILE  The process already has the maximum number of  files
             open.

     ENFILE  The limit on the total number of files open  on  the
             system has been reached.

     ENOMEM  Insufficient kernel memory was available.

     EROFS   pathname refers to a file on a read-only  filesystem
             and write access was requested.

     ELOOP   Too many symbolic links were encountered in  resolv-
             ing pathname.

     ENOSPC  pathname was to be created but the device containing
             pathname has no room for the new file.


CONFORMING TO

     SVr4, SVID, POSIX, X/OPEN, BSD 4.3


RESTRICTIONS

     There are many infelicities in the protocol underlying  NFS,
     affecting amongst others O_SYNC and O_NDELAY.


SEE ALSO

     read(2), write(2), fcntl(2), unlink(2),  mknod(2),  stat(2),
     mount(2), socket(2), socket(2), link(2).