OPEN(2)             Linux Programmer's Manual             OPEN(2)

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
       following:

       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 con-
               trolling terminal 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  sup-
               port 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 call-
               ing process to wait.

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

       O_NOFOLLOW
               If pathname is a  symbolic  link,  then  the  open
               fails.   This  is  a  FreeBSD extension, which was
               added to Linux in version 2.1.126.  Symbolic links
               in  earlier  components of the pathname will still
               be followed.  The headers from glibc  2.0.100  and
               later  include  a definition of this flag; kernels
               before 2.1.126 will ignore it if used.

       O_DIRECTORY
               If pathname is not a directory, cause the open  to
               fail.   This flag is Linux-specific, and was added
               in kernel version 2.1.126, to avoid denial-of-ser-
               vice problems if opendir(3) is called on a FIFO or
               tape device, but should not be used outside of the
               implementation of opendir.

       O_LARGEFILE
               On  32-bit  systems  that  support the Large Files
               System, allow files whose sizes cannot  be  repre-
               sented  in 31 bits to be opened.  The Linux kernel
               does not yet have the  support  for  this  (as  of
               2.1.130), but the flag definition is there and the
               userspace LFS interfaces are present in the  glibc
               2.1 test releases.

       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  permis-
              sion

       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  appropri-
       ately).  Note that open can open device special files, but
       creat cannot 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.

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

       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,  or  O_DIRECTORY  was
               specified and pathname was not a directory.

       ENXIO   O_NONBLOCK  | O_WRONLY is set, the named file id a
               FIFO and no process has the file open for reading.
               Or,  the file is a device special file and no cor-
               responding device exists.

       ENODEV  pathname refers to a device special  file  and  no
               corresponding device exists.

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

       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.

       ELOOP   Too   many  symbolic  links  were  encountered  in
               resolving pathname, or  O_NOFOLLOW  was  specified
               but pathname was a symbolic link.

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

       ENOMEM  Insufficient kernel memory was available.

       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.

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.

       POSIX  provides  for  three different variants of synchro-
       nised I/O, corresponding to the flags O_SYNC, O_DSYNC  and
       O_RSYNC.   Currently  (2.1.130)  these  are all synonymous
       under Linux.

SEE ALSO
       read(2),   write(2),   fcntl(2),   close(2),    unlink(2),
       mknod(2),    stat(2),   umask(2),   mount(2),   socket(2),
       socket(2), fopen(3), link(2).

Linux 2.1.130            28 November 1998                       1