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	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  re-
		       quires 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 re-
		       sult 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 de-
			    vice is device-specific.

			 o  If	O_NONBLOCK  and	O_NDELAY are clear, the	open()
			    function blocks the	calling	thread until  the  de-
			    vice 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  de-
		       vice files. Its effect on other file types is implemen-
		       tation-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 de-
		       scriptor	is that	for the	current	working	directory. Ex-
		       tended  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 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.

		       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 ei-
		       ther 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 at-
		       tributes.

       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 ex-
		       ist), 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  in-
		       termediate 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),  un-
       lockpt(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