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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
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 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 <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 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	 <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 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_NDELAYflags 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:

       +-----------------------------+-----------------------------+
       |      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),   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)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | 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.10>

home | help