File: *manpages*,  Node: open,  Up: (dir)



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

Linux 2.0.32            December 20, 1996                       1

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

               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.

       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

Linux 2.0.32            December 20, 1996                       2

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

       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.

       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.

Linux 2.0.32            December 20, 1996                       3

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

       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  filesys
               tem and write access was requested.

       ELOOP   Too   many  symbolic  links  were  encountered  in
               resolving pathname.

       ENOSPC  pathname was to be created but the device contain
               ing 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),   close(2),    unlink(2),
       mknod(2),    stat(2),   umask(2),   mount(2),   socket(2),
       socket(2), fopen(3), link(2).

Linux 2.0.32            December 20, 1996                       4

