unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

open(2)                          System Calls                          open(2)



NAME
       open, openat - open a file

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

       int open(const char *path, int oflag, /* mode_t mode */);

       int openat(int fildes, const char *path, int oflag, /* mode_t mode */);

DESCRIPTION
       The  open()  function  establishes  the connection between a file and a
       file descriptor. It creates an open file description that refers  to  a
       file  and  a file descriptor that refers to that open file description.
       The file descriptor is used by other I/O functions  to  refer  to  that
       file.  The path argument points to a pathname naming the file.

       The  openat()  function is identical to the open() function except that
       the path argument is interpreted relative to the starting point implied
       by  the  fildes  argument. If the fildes argument has the special value
       AT_FDCWD, a relative path argument will be  resolved  relative  to  the
       current working directory. If the path argument is absolute, the fildes
       argument is ignored.

       The open() function returns a file descriptor for the named  file  that
       is  the lowest file descriptor not currently open for that process. The
       open file description is new, and therefore the  file  descriptor  does
       not  share it with any other process in the system. The FD_CLOEXEC file
       descriptor flag associated with the new file descriptor is cleared.

       The file offset used to mark the current position within  the  file  is
       set to the beginning of the file.

       The  file  status flags and file access modes of the open file descrip-
       tion are set according to the value of oflag. The mode argument is used
       only when O_CREAT is specified (see below.)

       Values  for  oflag  are  constructed by a bitwise-inclusive-OR of flags
       from the following list, defined in <&lt;fcntl.h>&gt;. Applications must  spec-
       ify  exactly one of the first three values (file access modes) below in
       the value of oflag:

       O_RDONLY        Open for reading only.



       O_WRONLY        Open for writing only.



       O_RDWR          Open for reading and writing. The result  is  undefined
                       if this flag is applied to a FIFO.



       Any combination of the following may be used:

       O_APPEND        If  set,  the file offset is set to the end of the file
                       prior to each write.



       O_CREAT         Create the  file  if  it  does  not  exist.  This  flag
                       requires that the mode argument be specified.

                       If  the  file exists, this flag has no effect except as
                       noted under O_EXCL below.  Otherwise, the file is  cre-
                       ated  with the user ID of the file set to the effective
                       user ID of the process. The group ID of the file is set
                       to  the  effective  group IDs of the process, or if the
                       S_ISGID bit is set in the directory in which  the  file
                       is  being  created,  the  file's group ID is set to the
                       group ID of its parent directory.  If the group  ID  of
                       the  new  file does not match the effective group ID or
                       one of the supplementary groups IDs, the S_ISGID bit is
                       cleared.  The access permission bits (see <&lt;sys/stat.h>&gt;)
                       of the file mode are set to the value of mode, modified
                       as  follows  (see creat(2)): a bitwise-AND is performed
                       on the file-mode bits and the corresponding bits in the
                       complement  of  the  process's file mode creation mask.
                       Thus, all bits set in the process's file mode  creation
                       mask  (see umask(2)) are correspondingly cleared in the
                       file's permission mask. The "save text image after exe-
                       cution  bit"  of  the  mode  is cleared (see chmod(2)).
                       O_SYNC Write I/O operations on the file descriptor com-
                       plete  as  defined  by  synchronized I/O file integrity
                       completion  (see fcntl.h(3HEAD) definition of  O_SYNC.)
                       When  bits other than the file permission bits are set,
                       the effect is unspecified. The mode argument  does  not
                       affect whether the file is open for reading, writing or
                       for both.



       O_DSYNC         Write I/O operations on the file descriptor complete as
                       defined by synchronized I/O data integrity completion.



       O_EXCL          If O_CREAT and O_EXCL are set, open() fails if the file
                       exists. The check for the existence of the file and the
                       creation  of  the  file  if it does not exist is atomic
                       with respect to other threads executing  open()  naming
                       the same filename in the same directory with O_EXCL and
                       O_CREAT set. If O_EXCL and O_CREAT are  set,  and  path
                       names  a  symbolic link, open() fails and sets errno to
                       EEXIST, regardless of  the  contents  of  the  symbolic
                       link.  If  O_EXCL  is  set  and O_CREAT is not set, the
                       result is undefined.



       O_LARGEFILE     If set, the offset maximum in the open file description
                       is  the largest value that can be represented correctly
                       in an object of type off64_t.



       O_NOCTTY        If set and path identifies a  terminal  device,  open()
                       does  not  cause the terminal device to become the con-
                       trolling terminal for the process.



       O_NOFOLLOW      If the path names a symbolic  link,  open()  fails  and
                       sets errno to ELOOP.



       O_NOLINKS       If  the link count of the named file is greater than 1,
                       open() fails and sets errno to EMLINK.



       O_NONBLOCK or O_NTDhEeLsAeYflags can affect subsequent reads and writes (see
                       read(2)  and write(2)). If both O_NDELAY and O_NONBLOCK
                       are set, O_NONBLOCK takes precedence.

                       When opening a FIFO with O_RDONLY or O_WRONLY set:


                         o  If O_NONBLOCK or O_NDELAY is set,  an  open()  for
                            reading  only returns without delay.  Anopen() for
                            writing only returns an error if no  process  cur-
                            rently has the file open for reading.

                         o  If  O_NONBLOCK  and  O_NDELAY are clear, an open()
                            for reading only blocks until a thread  opens  the
                            file  for  writing.   Anopen()  for  writing  only
                            blocks the calling thread until a thread opens the
                            file for reading.

                       After both ends of a FIFO have been opened, there is no
                       guarantee  that  further  calls  to   open()   O_RDONLY
                       (O_WRONLY)  will synchronize with later calls to open()
                       O_WRONLY (O_RDONLY) until both ends of  the  FIFO  have
                       been closed by all readers and writers.  Any data writ-
                       ten into a FIFO will be lost if both ends of  the  FIFO
                       are closed before the data is read.

                       When  opening a block special or character special file
                       that supports non-blocking opens:


                         o  If O_NONBLOCK or O_NDELAY is set, the open() func-
                            tion returns without blocking for the device to be
                            ready or available.  Subsequent  behavior  of  the
                            device is device-specific.

                         o  If  O_NONBLOCK  and O_NDELAY are clear, the open()
                            function  blocks  the  calling  thread  until  the
                            device is ready or available before returning.

                       Otherwise,  the  behavior of O_NONBLOCK and O_NDELAY is
                       unspecified.



       O_RSYNC         Read I/O operations on the file descriptor complete  at
                       the same level of integrity as specified by the O_DSYNC
                       and O_SYNC flags.  If both O_DSYNC and O_RSYNC are  set
                       in  oflag,  all  I/O  operations on the file descriptor
                       complete as defined by synchronized I/O data  integrity
                       completion.   If  both  O_SYNC  and  O_RSYNC are set in
                       oflag, all I/O operations on the file  descriptor  com-
                       plete  as  defined  by  synchronized I/O file integrity
                       completion.



       O_SYNC          Write I/O operations on the file descriptor complete as
                       defined by synchronized I/O file integrity completion.



       O_TRUNC         If  the file exists and is a regular file, and the file
                       is successfully opened O_RDWR or O_WRONLY,  its  length
                       is truncated to 0 and the mode and owner are unchanged.
                       It has no effect on  FIFO  special  files  or  terminal
                       device  files. Its effect on other file types is imple-
                       mentation-dependent. The result of using  O_TRUNC  with
                       O_RDONLY is undefined.



       O_XATTR         If  set in openat(), a relative path argument is inter-
                       preted as a reference to an extended attribute  of  the
                       file  associated  with  the  supplied  file descriptor.
                       This flag therefore requires the presence  of  a  legal
                       fildes  argument.  If  set  in open(), the implied file
                       descriptor is that for the current  working  directory.
                       Extended  attributes must be referenced with a relative
                       path; providing an absolute path results  in  a  normal
                       file reference.



       If  O_CREAT is set and the file did not previously exist, upon success-
       ful completion, open() marks for update  the  st_atime,  st_ctime,  and
       st_mtime fields of the file and the st_ctime and st_mtime fields of the
       parent directory.

       If O_TRUNC is set and the file did previously  exist,  upon  successful
       completion, open() marks for update the st_ctime and st_mtime fields of
       the file.

       If both the O_SYNC and O_DSYNC flags are set, the effect is as if  only
       the O_SYNC flag was set.

       If  path refers to a STREAMS file, oflag may be constructed from O_NON-
       BLOCK or O_NODELAY OR-ed with either  O_RDONLY,  O_WRONLY,  or  O_RDWR.
       Other  flag  values  are  not applicable to STREAMS devices and have no
       effect on them.  The values O_NONBLOCK and O_NODELAY affect the  opera-
       tion  of STREAMS drivers and certain functions (see read(2), getmsg(2),
       putmsg(2), and write(2)) applied to file  descriptors  associated  with
       STREAMS  files.   For STREAMS drivers, the implementation of O_NONBLOCK
       and O_NODELAY is device-specific.

       When open() is invoked to open a named stream, and  the  connld  module
       (see  connld(7M))  has been pushed on the pipe, open() blocks until the
       server process has issued an I_RECVFD  ioctl()  (see  streamio(7I))  to
       receive the file descriptor.

       If  path  names the master side of a pseudo-terminal device, then it is
       unspecified whether open() locks the slave side so that  it  cannot  be
       opened.   Portable  applications  must call unlockpt(3C) before opening
       the slave side.

       If path is a symbolic link and O_CREAT and O_EXCL are set, the link  is
       not followed.

       Certain  flag  values  can  be  set  following  open()  as described in
       fcntl(2).

       The largest value that can be represented correctly  in  an  object  of
       type  off_t  is  established  as  the  offset  maximum in the open file
       description.

RETURN VALUES
       Upon successful completion, the open()  function  opens  the  file  and
       return  a  non-negative integer representing the lowest numbered unused
       file descriptor. Otherwise, -1 is returned, errno is  set  to  indicate
       the error, and no files are created or modified.

ERRORS
       The open() and openat() functions will fail if:

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

                       The file exists and the permissions specified by  oflag
                       are denied.

                       The  file does not exist and write permission is denied
                       for the parent directory of the file to be created.

                       O_TRUNC is specified and write permission is denied.

                       The {PRIV_FILE_DAC_SEARCH} privilege  allows  processes
                       to  search  directories  regardless of permission bits.
                       The {PRIV_FILE_DAC_WRITE} privilege allows processes to
                       open  files  for writing regardless of permission bits.
                       See privileges(5) for special considerations when open-
                       ing   files   owned   by   UID   0   for  writing.  The
                       {PRIV_FILE_DAC_READ} privilege allows processes to open
                       files for reading regardless of permission bits.



       EBADF           The file descriptor provided to openat() is invalid.



       EDQUOT          The  file  does  not  exist,  O_CREAT is specified, and
                       either the directory where the new file entry is  being
                       placed  cannot  be extended because the user's quota of
                       disk blocks on that file system has been exhausted,  or
                       the user's quota of inodes on the file system where the
                       file is being created has been exhausted.



       EEXIST          The O_CREAT and O_EXCL flags are set and the named file
                       exists.



       EINTR           A signal was caught during open().



       EFAULT          The path argument points to an illegal address.



       EINVAL          The  system  does not support synchronized I/O for this
                       file, or the O_XATTR flag was supplied and the underly-
                       ing   file   system  does  not  support  extended  file
                       attributes.



       EIO             The path argument names a STREAMS file and a hangup  or
                       error occurred during the open().



       EISDIR          The  named  file  is  a  directory  and  oflag includes
                       O_WRONLY or O_RDWR.



       ELOOP           Too many symbolic links were encountered  in  resolving
                       path.

                       A loop exists in symbolic links encountered during res-
                       olution of the path argument.

                       The O_NOFOLLOW flag is set and the final  component  of
                       path is a symbolic link.



       EMFILE          There are currently {OPEN_MAX} file descriptors open in
                       the calling process.



       EMLINK          The O_NOLINKS flag is set and the named file has a link
                       count greater than 1.



       EMULTIHOP       Components  of  path require hopping to multiple remote
                       machines and the file system does not allow it.



       ENAMETOOLONG    The length of the path argument exceeds {PATH_MAX} or a
                       pathname component is longer than {NAME_MAX}.



       ENFILE          The maximum allowable number of files is currently open
                       in the system.



       ENOENT          The O_CREAT flag is not set and the named file does not
                       exist;  or  the O_CREAT flag is set and either the path
                       prefix does not exist or the path argument points to an
                       empty string.



       ENOLINK         The  path  argument points to a remote machine, and the
                       link to that machine is no longer active.



       ENOSR           The path argument names a STREAMS-based  file  and  the
                       system is unable to allocate a STREAM.



       ENOSPC          The directory or file system that would contain the new
                       file cannot be expanded, the file does not  exist,  and
                       O_CREAT is specified.



       ENOSYS          The  device specified by path does not support the open
                       operation.



       ENOTDIR         A component of the path prefix is not a directory or  a
                       relative  path  was  supplied  to openat(), the O_XATTR
                       flag was not supplied, and the file descriptor does not
                       refer to a directory.



       ENXIO           The  O_NONBLOCK  flag is set, the named file is a FIFO,
                       the O_WRONLY flag is set, and no process has  the  file
                       open for reading; or the named file is a character spe-
                       cial or block special file and  the  device  associated
                       with this special file does not exist.



       EOPNOTSUPP      An  attempt was made to open a path that corresponds to
                       a AF_UNIX socket.



       EOVERFLOW       The named file is a regular file and either O_LARGEFILE
                       is  not  set  and the size of the file cannot be repre-
                       sented correctly in an object of type off_t or O_LARGE-
                       FILE  is  set and the size of the file cannot be repre-
                       sented correctly in an object of type off64_t.



       EROFS           The named file resides on a read-only file  system  and
                       either  O_WRONLY,  O_RDWR,  O_CREAT  (if  file does not
                       exist), or O_TRUNC is set in the oflag argument.



       The openat() function will fail if:

       EBADF           The fildes argument is not a valid open file descriptor
                       or is not AT_FTCWD.



       The open() function may fail if:

       EAGAIN          The path argument names the slave side of a pseudo-ter-
                       minal device that is locked.



       EINVAL          The value of the oflag argument is not valid.



       ENAMETOOLONG    Pathname resolution of  a  symbolic  link  produced  an
                       intermediate result whose length exceeds {PATH_MAX}.



       ENOMEM          The  path  argument names a STREAMS file and the system
                       is unable to allocate resources.



       ETXTBSY         The file is a pure procedure (shared text) file that is
                       being executed and oflag is O_WRONLY or O_RDWR.



EXAMPLES
       Example 1:  Open a file for writing by the owner.

       The  following  example opens the file /tmp/file, either by creating it
       if it does not already exist, or by truncating its length to  0  if  it
       does  exist. If the call creates a new file, the access permission bits
       in the file mode of the file are set to permit reading and  writing  by
       the owner, and to permit reading only by group members and others.

       If the call to open() is successful, the file is opened for writing.

       #include <fcntl.h>
       ...
       int fd;
       mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
       char *filename = "/tmp/file";
       ...
       fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, mode);
       ...


       Example 2: Open a file using an existence check.

       The  following  example  uses  the open() function to try to create the
       LOCKFILE file and open it for writing. Since the open() function speci-
       fies  the  O_EXCL  flag,  the call fails if the file already exists. In
       that case, the application assumes that someone else  is  updating  the
       password file and exits.

       #include <fcntl.h>
       #include <stdio.h>
       #include <stdlib.h>
       #define LOCKFILE "/etc/ptmp"
       ...
       int pfd; /* Integer for file descriptor returned by open() call. */
       ...
       if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL,
               S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
       {
               fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\n");
               exit(1);
       }
       ...


       Example 3: Open a file for writing.

       The following example opens a file for writing, creating the file if it
       does not already exist. If the file does exist,  the  system  truncates
       the file to zero bytes.

       #include <fcntl.h>
       #include <stdio.h>
       #include <stdlib.h>
       #define LOCKFILE "/etc/ptmp"
       ...
       int pfd;
       char filename[PATH_MAX+1];
       ...
       if ((pfd = open(filename, O_WRONLY | O_CREAT | O_TRUNC,
               S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
       {
               perror("Cannot open output file\n"); exit(1);
       }
       ...


USAGE
       The  open()  function has a transitional interface for 64-bit file off-
       sets.  See lf64(5). Note that using open64()  is  equivalent  to  using
       open() with O_LARGEFILE set in oflag.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE  TYPEATTRIBUTE  VALUE  Interface  StabilityT{
       open() is Standard; openat() is Evolving T} MT-LevelAsync-Signal-Safe


SEE ALSO
       intro(2),  chmod(2),  close(2),  creat(2),  dup(2),  exec(2), fcntl(2),
       getmsg(2),  getrlimit(2),  lseek(2),   putmsg(2),   read(2),   stat(2),
       umask(2),   write(2),   attropen(3C),   fcntl.h(3HEAD),  stat.h(3HEAD),
       unlockpt(3C),   attributes(5),   lf64(5),    privileges(5)standards(5),
       connld(7M), streamio(7I)

NOTES
       Hierarchical  Storage Management (HSM) file systems can sometimes cause
       long delays when opening a file, since HSM files must be recalled  from
       secondary storage.



SunOS 5.10                        2 Jul 2004                           open(2)