Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenSolaris 2009.06 - man page for open (opensolaris section 2)

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  rela-
       tive  to the current working directory. If the path argument is absolute, the fildes argu-
       ment 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 description 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 <fcntl.h>. Applications must specify exactly one of the first three val-
       ues (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.   Oth-
	   erwise,  the file is created 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 cre-
	   ated, 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 supple-
	   mentary groups IDs, the S_ISGID bit	is  cleared.  The  access  permission  bits  (see
	   <sys/stat.h>)  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 execution bit" of the mode is
	   cleared (see chmod(2)). O_SYNC Write I/O operations on the file descriptor complete 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 direc-
	   tory with O_EXCL and O_CREAT set. If O_EXCL and O_CREAT are set, and path names a sym-
	   bolic  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 controlling 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_NDELAY

	   These flags 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  with-
		      out  delay.  An open() 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. An open() 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  written 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() function 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 call-
		      ing 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  complete  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 implementation-dependent. The result of using O_TRUNC with O_RDONLY is unde-
	   fined.

       O_XATTR

	   If set in openat(), a relative path argument is  interpreted  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  nor-
	   mal file reference.

       If  O_CREAT  is	set  and  the  file did not previously exist, upon successful 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_NONBLOCK 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 operation 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 the file is a regular file and the local file system is mounted with the  nbmand  mount
       option,	then  a  mandatory  share  reservation is automatically obtained on the file. The
       share reservation is obtained as if fcntl(2) were called with cmd F_SHARE_NBMAND  and  the
       fshare_t values set as follows:

       f_access    Set to the type of read/write access for which the file is opened.

       f_deny	   F_NODNY

       f_id	   The file descriptor value returned from open().

       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 estab-
       lished 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 directo-
		       ries 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 opening files	owned  by
		       UID  0 for writing. The {PRIV_FILE_DAC_READ} privilege allows processes to
		       open files for reading regardless of permission bits.

       EAGAIN	       A mandatory share reservation could not be obtained  because  the  desired
		       access conflicts with an existing f_deny share reservation.

       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.

       EILSEQ	       The path argument includes non-UTF8 characters and the file system accepts
		       only file names where all characters are part of the UTF-8 character code-
		       set.

       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 underlying file system does not support extended
		       file attributes.

       EIO	       The path argument names a STREAMS file and a hangup or error occurred dur-
		       ing 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 resolution 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  special  or  block  special file and the device associated with
		       this special file does not exist or has been retired by the fault  manage-
		       ment framework .

       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 represented correctly  in  an  object  of  type
		       off_t or O_LARGEFILE is set and the size of the file cannot be represented
		       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-terminal 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  allo-
		       cate 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  read-
       ing 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 specifies 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 offsets.  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:

       +-----------------------------+------------------------------+
       |      ATTRIBUTE TYPE	     |	     ATTRIBUTE VALUE	    |
       +-----------------------------+------------------------------+
       |Interface Stability	     |Committed 		    |
       +-----------------------------+------------------------------+
       |MT-Level		     |Async-Signal-Safe 	    |
       +-----------------------------+------------------------------+
       |Standard		     |For open(), see standards(5). |
       +-----------------------------+------------------------------+

SEE ALSO
       Intro(2), chmod(2),  close(2),  creat(2),  dup(2),  exec(2),  fcntl(2),	getmsg(2),  getr-
       limit(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),  stan-
       dards(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.11				   16 Jun 2008					  open(2)


All times are GMT -4. The time now is 12:29 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password