home | help 
OPEN(2) 		       System Calls Manual			 OPEN(2)

NAME
     open, openat -- open or create a file for reading or writing

SYNOPSIS
     #include <fcntl.h>

     int
     open(const char *path, int oflag, ...);

     int
     openat(int fd, const char *path, int oflag, ...);

DESCRIPTION
     The  file	name  specified by path is opened for reading and/or writing, as
     specified by the argument oflag; the file descriptor  is  returned  to  the
     calling process.

     The  oflag  argument may indicate that the file is to be created if it does
     not exist (by specifying the O_CREAT flag).  In this case, open() and  ope-
     nat()  require an additional argument mode_t mode; the file is created with
     mode mode as described in chmod(2) and modified by the process' umask value
     (see umask(2)).

     The openat() function is equivalent to the open() function  except  in  the
     case where the path specifies a relative path.  In this case the file to be
     opened is determined relative to the directory associated with the file de-
     scriptor  fd  instead of the current working directory.  The oflag argument
     and the optional fourth argument correspond exactly to  the  arguments  for
     open().   If  openat() is passed the special value AT_FDCWD in the fd argu-
     ment, the current working directory is used and the behavior  is  identical
     to a call to open().

     The  flags specified for the oflag argument must include exactly one of the
     following file access modes:

	   O_RDONLY	   open for reading only
	   O_WRONLY	   open for writing only
	   O_RDWR	   open for reading and writing
	   O_SEARCH	   open directory for searching
	   O_EXEC	   open for execute only

     In addition any combination of the following values can be or'ed in oflag:

	   O_NONBLOCK	   do not block on open or for data to become available
	   O_APPEND	   append on each write
	   O_CREAT	   create file if it does not exist
	   O_TRUNC	   truncate size to 0
	   O_EXCL	   error if O_CREAT and the file exists
	   O_SHLOCK	   atomically obtain a shared lock
	   O_EXLOCK	   atomically obtain an exclusive lock
	   O_DIRECTORY	   restrict open to a directory
	   O_NOFOLLOW	   do not follow symlinks
	   O_SYMLINK	   allow open of symlinks
	   O_EVTONLY	   descriptor requested for event notifications only
	   O_CLOEXEC	   mark as close-on-exec
	   O_CLOFORK	   mark as close-on-fork
	   O_NOFOLLOW_ANY  do not follow symlinks in the entire path
	   O_RESOLVE_BENEATH	   path resolution must not escape the directory associated with the file descriptor
	   O_UNIQUE	   ensure a file is opened only if it has a single hard link

     Opening a file with O_APPEND set causes each write on the file  to  be  ap-
     pended  to  the end.  If O_TRUNC is specified and the file exists, the file
     is truncated to zero length.  If O_EXCL is set with O_CREAT  and  the  file
     already  exists,  open() returns an error.  This may be used to implement a
     simple exclusive-access locking mechanism.  If O_EXCL is set  with  O_CREAT
     and the last component of the pathname is a symbolic link, open() will fail
     even if the symbolic link points to a non-existent name.

     If  the O_NONBLOCK flag is specified, do not wait for the device or file to
     be ready or available.  If the open() call would result in the process  be-
     ing  blocked  for some reason (e.g., waiting for carrier on a dialup line),
     open() returns immediately.  This flag also has the effect  of  making  all
     subsequent I/O on the open file non-blocking.

     When opening a file, a lock with flock(2) semantics can be obtained by set-
     ting  O_SHLOCK  for  a  shared lock, or O_EXLOCK for an exclusive lock.  If
     creating a file with O_CREAT, the request for  the  lock  will  never  fail
     (provided that the underlying filesystem supports locking).

     If  O_DIRECTORY is used in the mask and the target file passed to open() is
     not a directory then the open() will fail.

     If O_NOFOLLOW is used in the mask and the target file passed to open() is a
     symbolic link then the open() will fail.

     If O_SYMLINK is used in the mask and the target file passed to open() is  a
     symbolic  link  then  the	open() will be for the symbolic link itself, not
     what it links to.

     The O_EVTONLY flag is only intended for monitoring a file for changes (e.g.
     kqueue). Note: when this flag is used, the opened file will not prevent  an
     unmount of the volume that contains the file.

     The  O_CLOEXEC  flag  causes  the file descriptor to be marked as close-on-
     exec, setting the FD_CLOEXEC flag.  The state of the file descriptor  flags
     can be inspected using the F_GETFD fcntl.	See fcntl(2).

     The  O_CLOFORK  flag  causes  the file descriptor to be marked as close-on-
     fork, setting the FD_CLOFORK flag.

     If O_NOFOLLOW_ANY is used in the mask and any component of the path  passed
     to open() is a symbolic link then the open() will fail.

     If  O_RESOLVE_BENEATH is used in the mask and the specified path resolution
     escapes the directory associated with the fd then the openat() will fail.

     If O_UNIQUE is used in the mask, the open operation will fail if  the  file
     has more than one hard link pointing to it.  The operation succeeds only if
     the file is guaranteed to be uniquely accessible through the provided path-
     name.

     If  successful,  open()  returns  a non-negative integer, termed a file de-
     scriptor.	It returns -1 on failure.  The file pointer (used  to  mark  the
     current position within the file) is set to the beginning of the file.

     When  a  new  file is created, it is given the group of the directory which
     contains it.

     The new descriptor is set to remain open across execve  system  calls;  see
     close(2) and fcntl(2).

     The  system  imposes  a limit on the number of file descriptors that can be
     held open simultaneously by one process.

     A file's metadata can be updated even if the file was opened  in  read-only
     mode.  Getdtablesize(2) returns the current system limit.

RETURN VALUES
     If  successful,  open()  returns  a non-negative integer, termed a file de-
     scriptor.	It returns -1 on failure, and sets errno to indicate the error.

ERRORS
     The named file is opened unless:

     [EACCES]		Search permission is denied for a component of the  path
			prefix.

     [EACCES]		The  required permissions (for reading and/or writing or
			search or executing) are denied for the given flags.

     [EACCES]		O_CREAT is specified, the file does not exist,	and  the
			directory  in  which it is to be created does not permit
			writing.

     [EACCES]		O_TRUNC is specified and write permission is denied.

     [EAGAIN]		path specifies the slave side of a locked  pseudo-termi-
			nal device.

     [EDQUOT]		O_CREAT  is  specified, the file does not exist, and the
			directory in which the entry for the new file  is  being
			placed	cannot	be  extended because the user's quota of
			disk blocks on the file system containing the  directory
			has been exhausted.

     [EDQUOT]		O_CREAT  is  specified, the file does not exist, and the
			user's quota of inodes on the file system on  which  the
			file is being created has been exhausted.

     [EEXIST]		O_CREAT and O_EXCL are specified and the file exists.

     [EFAULT]		Path  points  outside  the  process's  allocated address
			space.

     [EINTR]		The open() operation is interrupted by a signal.

     [EINVAL]		The value of oflag is not valid.

     [EIO]		An I/O error occurs while making the directory entry  or
			allocating the inode for O_CREAT.

     [EISDIR]		The named file is a directory, and the arguments specify
			that it is to be opened for writing.

     [EISDIR]		The named file is a directory, and the arguments specify
			that it is to be opened for executing.

     [ELOOP]		Too  many  symbolic links are encountered in translating
			the pathname.  This is taken to be indicative of a loop-
			ing symbolic link.

     [EMFILE]		The process has already reached its limit for open  file
			descriptors.

     [ENAMETOOLONG]	A component of a pathname exceeds {NAME_MAX} characters,
			or an entire path name exceeded {PATH_MAX} characters.

     [ENFILE]		The system file table is full.

     [ENOTDIR]		O_DIRECTORY was specified and the target is not a direc-
			tory.

     [ENOTDIR]		O_SEARCH  was  specified  and the target is not a direc-
			tory.

     [ELOOP]		O_NOFOLLOW was specified and the target  is  a	symbolic
			link.

     [ELOOP]		O_NOFOLLOW_ANY	was specified and and a component of the
			path is a symbolic link.

     [ENOENT]		O_CREAT is not set and the named file does not exist.

     [ENOENT]		A component of the path name that must	exist  does  not
			exist.

     [ENOSPC]		O_CREAT  is  specified, the file does not exist, and the
			directory in which the entry for the new file  is  being
			placed cannot be extended because there is no space left
			on the file system containing the directory.

     [ENOSPC]		O_CREAT is specified, the file does not exist, and there
			are  no free inodes on the file system on which the file
			is being created.

     [ENOTDIR]		A component of the path prefix is not a directory.

     [EDEADLK]		A component of the pathname refers to a  "dataless"  di-
			rectory that requires materialization and the I/O policy
			of  the current thread or process disallows dataless di-
			rectory materialization (see getiopolicy_np(3)).

     [ENXIO]		The named file is a character-special  or  block-special
			file  and  the	device associated with this special file
			does not exist.

     [ENXIO]		O_NONBLOCK and O_WRONLY are set, the file is a FIFO, and
			no process has it open for reading.

     [EOPNOTSUPP]	O_SHLOCK or O_EXLOCK is specified,  but  the  underlying
			filesystem does not support locking.

     [EOPNOTSUPP]	An  attempt  is made to open a socket (not currently im-
			plemented).

     [EOVERFLOW]	The named file is a regular file and its size  does  not
			fit in an object of type off_t.

     [EROFS]		The  named  file resides on a read-only file system, and
			the file is to be modified.

     [ETXTBSY]		The file is a pure procedure (shared text) file that  is
			being  executed  and  the open() call requests write ac-
			cess.

     [EBADF]		The path argument does not specify an absolute path  and
			the fd argument is neither AT_FDCWD nor a valid file de-
			scriptor open for searching.

     [ENOTDIR]		The path argument is not an absolute path and fd is nei-
			ther  AT_FDCWD	nor  a file descriptor associated with a
			directory.

     [EILSEQ]		The filename does not match the encoding rules.

     [EWOULDBLOCK]	O_SHLOCK or O_EXLOCK  is  specified,  but  the	file  is
			locked and the O_NONBLOCK option was specified.

     [ENOTCAPABLE]	path resolution escapes the directory associated with fd
			and O_RESOLVE_BENEATH option was specified.

     [ENOTCAPABLE]	path  has  multiple  hard  links and O_UNIQUE option was
			specified.

COMPATIBILITY
     open() on a terminal device (i.e., /dev/console) will now make that  device
     a	controlling  terminal  for the process.  Use the O_NOCTTY flag to open a
     terminal device without changing your controlling terminal.

SEE ALSO
     chmod(2), close(2), dup(2),  getdtablesize(2),  lseek(2),	openat_authenti-
     cated_np(2), read(2), umask(2), write(2)

HISTORY
     An  open()  function  call  appeared  in Version 6 AT&T UNIX.  The openat()
     function was introduced in OS X 10.10

4th Berkeley Distribution	  June 3, 2021				 OPEN(2)
home | help