Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 fd argument. If the fd argument has the special value  AT_FDCWD,
       a relative path argument	will be	resolved relative to the current work-
       ing directory. If the path argument is absolute,	the fd argument	is ig-
       nored.

       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 <fcntl.h>. 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 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	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
	     <sys/stat.h>) of the file mode are	set to the value of mode, mod-
	     ified 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	corre-
	     spondingly	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 fc-
	     ntl(3HEAD)	definition of O_SYNC.) When bits other than  the  file
	     permission	 bits are set, the effect is unspecified. The mode ar-
	     gument 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  pro-
	     cesses  executing open() naming the same filename in the same di-
	     rectory with O_EXCL and O_CREAT set. If O_CREAT is	not  set,  the
	     effect 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_NONBLOCK or O_NDELAY
	     These  flags  may affect subsequent reads and writes (see read(2)
	     and write(2)). If both O_NDELAY and O_NONBLOCK  are  set,	O_NON-
	     BLOCK takes precedence.

	     When opening a FIFO with O_RDONLY or O_WRONLY set:

	     If	O_NONBLOCK or O_NDELAY is set:

	     An	 open()	for reading only returns without delay.	 An open() for
	     writing only returns an error if no  process  currently  has  the
	     file open for reading.

	     If	O_NONBLOCK and O_NDELAY	are clear:

	     An	 open()	for reading only blocks	until a	process	opens the file
	     for writing.  An open() for writing only blocks until  a  process
	     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  sup-
	     ports non-blocking	opens:

	     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.

	     If	 O_NONBLOCK and	O_NDELAY are clear:

	     The open()	function blocks	until the device is ready or available
	     before returning.

	     Otherwise,	the behavior of	O_NONBLOCK and	O_NDELAY  is  unspeci-
	     fied.

       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  de-
	     fined 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  suc-
	     cessfully 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 undefined.

       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  im-
	     plied  file descriptor is that for	the current working directory.
	     Extended attributes must be referenced with a relative path; pro-
	     viding 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 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 ef-
       fect 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 re-
       ceive 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  fc-
       ntl(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  de-
       scription.

RETURN VALUES
       Upon  successful	completion, the	open() function	opens the file and re-
       turn 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, or
	     the  file	exists	and the	permissions specified by oflag are de-
	     nied, or the file does not	exist and write	permission  is	denied
	     for the parent directory of the file to be	created, or O_TRUNC is
	     specified and write permission is denied.

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

       EDQUOT
	     The file does not exist, O_CREAT is specified, and	either the di-
	     rectory  where  the  new file entry is being placed cannot	be ex-
	     tended because the	user's quota of	disk blocks on that file  sys-
	     tem 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 underlying file system does
	     not support extended file attributes.

       EIO   The path argument names a STREAMS file and	a hangup or error  oc-
	     curred 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.

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

       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 can-
	     not  be  expanded,	the file does not exist, and O_CREAT is	speci-
	     fied.

       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 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 read-
	     ing; or the named file is a character special  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 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  de-
	     vice 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 ex-
	     ecuted and	oflag is O_WRONLY or O_RDWR.

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:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |open()  is  Standard;  ope-  |
       |			     |nat() is Evolving		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Async-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),  unlockpt(3C),  attributes(5),  fc-
       ntl(3HEAD), lf64(5), stat(3HEAD), 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.9			  10 Dec 2001			       open(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=open&sektion=2&manpath=SunOS+5.9>

home | help