diff options
Diffstat (limited to 'lib/libsys/open.2')
| -rw-r--r-- | lib/libsys/open.2 | 880 |
1 files changed, 880 insertions, 0 deletions
diff --git a/lib/libsys/open.2 b/lib/libsys/open.2 new file mode 100644 index 000000000000..a0e905a8f375 --- /dev/null +++ b/lib/libsys/open.2 @@ -0,0 +1,880 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 17, 2025 +.Dt OPEN 2 +.Os +.Sh NAME +.Nm open , openat +.Nd open or create a file for reading, writing or executing +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn open "const char *path" "int flags" "..." +.Ft int +.Fn openat "int fd" "const char *path" "int flags" "..." +.Sh DESCRIPTION +The file name specified by +.Fa path +is opened +for either execution or reading and/or writing as specified by the +argument +.Fa flags +and the file descriptor returned to the calling process. +The +.Fa flags +argument may indicate the file is to be +created if it does not exist (by specifying the +.Dv O_CREAT +flag). +In this case +.Fn open +and +.Fn openat +require an additional argument +.Fa "mode_t mode" , +and the file is created with mode +.Fa mode +as described in +.Xr chmod 2 +and modified by the process' umask value (see +.Xr umask 2 ) . +.Pp +The +.Fn openat +function is equivalent to the +.Fn open +function except in the case where the +.Fa path +specifies a relative path. +For +.Fn openat +and relative +.Fa path , +the file to be opened is determined relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +The +.Fa flag +parameter and the optional fourth parameter correspond exactly to +the parameters of +.Fn open . +If +.Fn openat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used +and the behavior is identical to a call to +.Fn open . +.Pp +When +.Fn openat +is called with an absolute +.Fa path , +it ignores the +.Fa fd +argument. +.Pp +In +.Xr capsicum 4 +capability mode, +.Fn open +is not permitted. +The +.Fa path +argument to +.Fn openat +must be strictly relative to a file descriptor +.Fa fd ; +that is, +.Fa path +must not be an absolute path and must not contain ".." components +which cause the path resolution to escape the directory hierarchy +starting at +.Fa fd . +Additionally, no symbolic link in +.Fa path +may target absolute path or contain escaping ".." components. +.Fa fd +must not be +.Dv AT_FDCWD . +.Pp +If the +.Dv vfs.lookup_cap_dotdot +.Xr sysctl 3 +MIB is set to zero, ".." components in the paths, +used in capability mode, +are completely disabled. +If the +.Dv vfs.lookup_cap_dotdot_nonlocal +MIB is set to zero, ".." is not allowed if found on non-local filesystem. +.Pp +The +.Fa flags +are formed by +.Em or Ns 'ing +the following values: +.Pp +.Bl -tag -width O_RESOLVE_BENEATH +.It Dv O_RDONLY +open for reading only +.It Dv O_WRONLY +open for writing only +.It Dv O_RDWR +open for reading and writing +.It Dv O_EXEC +open for execute only +.It Dv O_SEARCH +open for search only +(an alias for +.Dv O_EXEC +typically used with +.Dv O_DIRECTORY ) +.It Dv O_NONBLOCK +do not block on open +.It Dv O_APPEND +set file pointer to the end of the file before each write +.It Dv O_CREAT +create file if it does not exist +.It Dv O_TRUNC +truncate size to 0 +.It Dv O_EXCL +fail if +.Dv O_CREAT +is set and the file exists +.It Dv O_SHLOCK +atomically obtain a shared lock +.It Dv O_EXLOCK +atomically obtain an exclusive lock +.It Dv O_DIRECT +read and write directly from the backing store +.It Dv O_FSYNC +synchronous data and metadata writes +.Pq historical synonym for Dv O_SYNC +.It Dv O_SYNC +synchronous data and metadata writes +.It Dv O_DSYNC +synchronous data writes +.It Dv O_NOFOLLOW +do not follow symlinks +.It Dv O_NOCTTY +ignored +.It Dv O_TTY_INIT +ignored +.It Dv O_DIRECTORY +error if file is not a directory +.It Dv O_CLOEXEC +automatically close file on +.Xr execve 2 +.It Dv O_CLOFORK +automatically close file on any child process created with +.Fn fork 2 +.It Dv O_VERIFY +verify the contents of the file with +.Xr mac_veriexec 4 +.It Dv O_RESOLVE_BENEATH +.Pq Xr openat 2 only +path resolution must not cross the +.Fa fd +directory +.It Dv O_PATH +record only the target path in the opened descriptor +.It Dv O_EMPTY_PATH +.Pq Xr openat 2 only +open file referenced by +.Fa fd +if path is empty +.It Dv O_NAMEDATTR +open a named attribute or named attribute directory +.El +.Pp +Exactly one of the flags +.Dv O_RDONLY , +.Dv O_WRONLY , +.Dv O_RDWR , +or +.Dv O_EXEC +must be provided. +.Pp +Opening a file with +.Dv O_APPEND +set causes each write on the resulting file descriptor +to be appended to the end of the file. +.Pp +If +.Dv O_TRUNC +is specified and the +file exists, the file is truncated to zero length. +.Pp +If +.Dv O_CREAT +is set, but file already exists, +this flag has no effect except when +.Dv O_EXCL +is set too, in this case +.Fn open +fails with +.Er EEXIST . +This may be used to +implement a simple exclusive access locking mechanism. +In all other cases, the file is created +and the access permission bits (see +.Xr chmod 2) +of the file mode +are set to the value of the third argument taken as +.Fa "mode_t mode" +and passed through the +.Xr umask 2 . +This argument does not affect whether the file is opened +for reading, writing, or for both. +The open' request for a lock on the file, created with +.Dv O_CREAT , +will never fail +provided that the underlying file system supports locking; +see also +.Dv O_SHLOCK +and +.Dv O_EXLOCK +below. +.Pp +If +.Dv O_EXCL +is set and the last component of the pathname is +a symbolic link, +.Fn open +will fail even if the symbolic +link points to a non-existent name. +.Pp +If +.Dv O_NONBLOCK +is specified and the +.Fn open +system call would +block for some reason (for example, waiting for +carrier on a dialup line), +.Fn open +returns immediately. +The descriptor remains in non-blocking mode for subsequent operations. +.Pp +If +.Dv O_SYNC +is used in the mask, all writes will +immediately and synchronously be written to disk. +.Dv O_FSYNC +is an historical synonym for +.Dv O_SYNC . +.Pp +If +.Dv O_DSYNC +is used in the mask, all data and metadata required to read the data will be +synchronously written to disk, but changes to metadata such as file access and +modification timestamps may be written later. +.Pp +If +.Dv O_NOFOLLOW +is used in the mask and the target file passed to +.Fn open +is a symbolic link then the +.Fn open +will fail. +.Pp +When opening a file, a lock with +.Xr flock 2 +semantics can be obtained by setting +.Dv O_SHLOCK +for a shared lock, or +.Dv O_EXLOCK +for an exclusive lock. +.Pp +.Dv O_DIRECT +may be used to minimize or eliminate the cache effects of reading and writing. +The system will attempt to avoid caching the data you read or write. +If it cannot avoid caching the data, +it will minimize the impact the data has on the cache. +Use of this flag can drastically reduce performance if not used with care. +The semantics of this flag are filesystem dependent, +and some filesystems may ignore it entirely. +.Pp +.Dv O_NOCTTY +may be used to ensure the OS does not assign this file as the +controlling terminal when it opens a tty device. +This is the default on +.Fx , +but is present for +POSIX +compatibility. +The +.Fn open +system call will not assign controlling terminals on +.Fx . +.Pp +.Dv O_TTY_INIT +may be used to ensure the OS restores the terminal attributes when +initially opening a TTY. +This is the default on +.Fx , +but is present for +POSIX +compatibility. +The initial call to +.Fn open +on a TTY will always restore default terminal attributes on +.Fx . +.Pp +.Dv O_DIRECTORY +may be used to ensure the resulting file descriptor refers to a +directory. +This flag can be used to prevent applications with elevated privileges +from opening files which are even unsafe to open with +.Dv O_RDONLY , +such as device nodes. +.Pp +.Dv O_CLOEXEC +may be used to set +.Dv FD_CLOEXEC +flag for the newly returned file descriptor. +.Pp +.Dv O_CLOFORK +may be used to set +.Dv FD_CLOFORK +flag for the newly returned file descriptor. +The file will be closed on any child process created with +.Fn fork 2 , +.Fn vfork 2 +or +.Fn rfork 2 +with the +.Dv RFFDG +flag, remaining open in the parent. +Both the +.Dv O_CLOEXEC +and +.Dv O_CLOFORK +flags can be modified with the +.Dv F_SETFD +.Fn fcntl 2 +command. +.Pp +.Dv O_VERIFY +may be used to indicate to the kernel that the contents of the file should +be verified before allowing the open to proceed. +The details of what +.Dq verified +means is implementation specific. +The run-time linker (rtld) uses this flag to ensure shared objects have +been verified before operating on them. +.Pp +.Dv O_RESOLVE_BENEATH +returns +.Er ENOTCAPABLE +if any intermediate component of the specified relative path does not +reside in the directory hierarchy beneath the starting directory. +Absolute paths or even the temporal escape from beneath of the starting +directory is not allowed. +.Pp +When a directory +is opened with +.Dv O_SEARCH , +execute permissions are checked at open time. +The returned file descriptor +may not be used for any read operations like +.Xr getdirentries 2 . +The primary use of this descriptor is as the lookup descriptor for the +.Fn *at +family of functions. +If +.Dv O_SEARCH +was not requested at open time, then the +.Fn *at +functions use the current directory permissions for the directory referenced +by the descriptor at the time of the +.Fn *at +call. +.Pp +.Dv O_PATH +returns a file descriptor that can be used as a directory file descriptor for +.Fn openat +and other system calls taking a file descriptor argument, like +.Xr fstatat 2 +and others. +The other functionality of the returned file descriptor is limited to +the following descriptor-level operations: +.Pp +.Bl -tag -width __acl_aclcheck_fd -offset indent -compact +.It Xr fcntl 2 +but advisory locking is not allowed +.It Xr dup 2 +.It Xr close 2 +.It Xr fstat 2 +.It Xr fstatfs 2 +.It Xr fchdir 2 +.It Xr fchroot 2 +.It Xr fexecve 2 +.It Xr funlinkat 2 +can be passed as the third argument +.It Dv SCM_RIGHTS +can be passed over a +.Xr unix 4 +socket using a +.Dv SCM_RIGHTS +message +.It Xr kqueue 2 +only with +.Dv EVFILT_VNODE +.It Xr __acl_get_fd 2 +.It Xr __acl_aclcheck_fd 2 +.It Xr extattr 2 +.It Xr capsicum 4 +can be passed to +.Fn cap_*_limit +and +.Fn cap_*_get +system calls (such as +.Xr cap_rights_limit 2 ) . +.El +.Pp +Other operations like +.Xr read 2 , +.Xr ftruncate 2 , +and any other that operate on file and not on file descriptor (except +.Xr fstat 2 ) , +are not allowed. +.Pp +A file descriptor created with the +.Dv O_PATH +flag can be opened as a normal (operable) file descriptor by +specifying it as the +.Fa fd +argument to +.Fn openat +with an empty +.Fa path +and the +.Dv O_EMPTY_PATH +flag. +Such an open behaves as if the current path of the file referenced by +.Fa fd +is passed, except that path walk permissions are not checked. +See also the description of +.Dv AT_EMPTY_PATH +flag for +.Xr fstatat 2 +and related syscalls. +.Pp +Conversely, a file descriptor +.Dv fd +referencing a filesystem file can be converted to the +.Dv O_PATH +type of descriptor by using the following call +.Dl opath_fd = openat(fd, \[dq]\[dq], O_EMPTY_PATH | O_PATH); +.Pp +If successful, +.Fn open +returns a non-negative integer, termed a file descriptor. +It returns \-1 on failure. +The file descriptor value returned is the lowest numbered descriptor +currently not in use by the process. +The file pointer used to mark the current position within the +file is set to the beginning of the file. +.Pp +If a sleeping open of a device node from +.Xr devfs 4 +is interrupted by a signal, the call always fails with +.Er EINTR , +even if the +.Dv SA_RESTART +flag is set for the signal. +A sleeping open of a fifo (see +.Xr mkfifo 2 ) +is restarted as normal. +.Pp +When a new file is created, it is assigned the group of the directory +which contains it. +.Pp +Unless +.Dv O_CLOEXEC +flag was specified, +the new descriptor is set to remain open across +.Xr execve 2 +system calls; see +.Xr close 2 , +.Xr fcntl 2 +and the description of the +.Dv O_CLOEXEC +flag. +.Pp +When the +.Dv O_NAMEDATTR +flag is specified for an +.Fn openat +where the +.Fa fd +argument is for a file object, +a named attribute for the file object +is opened and not the file object itself. +If the +.Dv O_CREAT +flag has been specified as well, the named attribute will be +created if it does not exist. +When the +.Dv O_NAMEDATTR +flag is specified for a +.Fn open , +a named attribute for the current working directory is opened and +not the current working directory. +The +.Fa path +argument for this +.Fn openat +or +.Fn open +must be a single component name with no embedded +.Ql / . +If the +.Fa path +argument is +.Ql .\& +then the named attribute directory for the file object is opened. +(See +.Xr named_attribute 7 +for more information.) +.Pp +The system imposes a limit on the number of file descriptors +open simultaneously by one process. +The +.Xr getdtablesize 2 +system call returns the current system limit. +.Sh RETURN VALUES +If successful, +.Fn open +and +.Fn openat +return a non-negative integer, termed a file descriptor. +They return \-1 on failure, and set +.Va errno +to indicate the error. +.Sh ERRORS +The named file is opened unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +.Dv O_CREAT +is not set and the named file does not exist. +.It Bq Er ENOENT +A component of the path name that must exist does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +The required permissions (for reading and/or writing) +are denied for the given flags. +.It Bq Er EACCES +.Dv O_TRUNC +is specified and write permission is denied. +.It Bq Er EACCES +.Dv O_CREAT +is specified, +the file does not exist, +and the directory in which it is to be created +does not permit writing. +.It Bq Er EPERM +.Dv O_CREAT +is specified, the file does not exist, and the directory in which it is to be +created has its immutable flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The named file has its immutable flag set and the file is to be modified. +.It Bq Er EPERM +The named file has its append-only flag set, the file is to be modified, and +.Dv O_TRUNC +is specified or +.Dv O_APPEND +is not specified. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EISDIR +The named file is a directory, and the arguments specify +it is to be modified. +.It Bq Er EISDIR +The named file is a directory, and the flags specified +.Dv O_CREAT +without +.Dv O_DIRECTORY . +.It Bq Er EROFS +The named file resides on a read-only file system, +and the file is to be modified. +.It Bq Er EROFS +.Dv O_CREAT +is specified and the named file would reside on a read-only file system. +.It Bq Er EMFILE +The process has already reached its limit for open file descriptors. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er EMLINK +.Dv O_NOFOLLOW +was specified and the target is a symbolic link. +POSIX +specifies a different error for this case; see the note in +.Sx STANDARDS +below. +.It Bq Er ENXIO +The named file is a character special or block +special file, and the device associated with this special file +does not exist. +.It Bq Er ENXIO +.Dv O_NONBLOCK +is set, the named file is a fifo, +.Dv O_WRONLY +is set, and no process has the file open for reading. +.It Bq Er EINTR +The +.Fn open +operation was interrupted by a signal. +.It Bq Er EOPNOTSUPP +.Dv O_SHLOCK +or +.Dv O_EXLOCK +is specified but the underlying file system does not support locking. +.It Bq Er EOPNOTSUPP +The named file is a special file mounted through a file system that +does not support access to it (for example, NFS). +.It Bq Er EWOULDBLOCK +.Dv O_NONBLOCK +and one of +.Dv O_SHLOCK +or +.Dv O_EXLOCK +is specified and the file is locked. +.It Bq Er ENOSPC +.Dv 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. +.It Bq Er ENOSPC +.Dv 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. +.It Bq Er EDQUOT +.Dv 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. +.It Bq Er EDQUOT +.Dv 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. +.It Bq Er EIO +An I/O error occurred while making the directory entry or +allocating the inode for +.Dv O_CREAT . +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the file system. +.It Bq Er ETXTBSY +The file is a pure procedure (shared text) file that is being +executed and the +.Fn open +system call requests write access. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EEXIST +.Dv O_CREAT +and +.Dv O_EXCL +were specified and the file exists. +.It Bq Er EOPNOTSUPP +An attempt was made to open a socket (not currently implemented). +.It Bq Er EINVAL +An attempt was made to open a descriptor with an illegal combination +of +.Dv O_RDONLY , +.Dv O_WRONLY , +or +.Dv O_RDWR , +and +.Dv O_EXEC +or +.Dv O_SEARCH . +.It Bq Er EINVAL +.Dv O_CREAT +is specified, +and the last component of the +.Fa path +argument is invalid on the file system on which the file is being created. +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is +neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.It Bq Er ENOTDIR +.Dv O_DIRECTORY +is specified and the file is not a directory. +.It Bq Er ECAPMODE +.Dv AT_FDCWD +is specified and the process is in capability mode. +.It Bq Er ECAPMODE +.Fn open +was called and the process is in capability mode. +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path and the process is in capability mode. +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path and +.Dv O_RESOLVE_BENEATH +is specified. +.It Bq Er ENOTCAPABLE +.Fa path +contains a ".." component leading to a directory outside +of the directory hierarchy specified by +.Fa fd +and the process is in capability mode. +.It Bq Er ENOTCAPABLE +.Fa path +contains a ".." component leading to a directory outside +of the directory hierarchy specified by +.Fa fd +and +.Dv O_RESOLVE_BENEATH +is specified. +.It Bq Er ENOTCAPABLE +.Fa path +contains a ".." component, the +.Dv vfs.lookup_cap_dotdot +.Xr sysctl 3 +is set, and the process is in capability mode. +.It Bq Er ENOATTR +.Dv O_NAMEDATTR +has been specified and the file object is not a named attribute +directory or named attribute. +.El +.Sh SEE ALSO +.Xr chmod 2 , +.Xr close 2 , +.Xr dup 2 , +.Xr fexecve 2 , +.Xr fhopen 2 , +.Xr getdtablesize 2 , +.Xr getfh 2 , +.Xr lgetfh 2 , +.Xr lseek 2 , +.Xr read 2 , +.Xr umask 2 , +.Xr write 2 , +.Xr fopen 3 , +.Xr capsicum 4 , +.Xr named_attribute 7 +.Sh STANDARDS +These functions are specified by +.St -p1003.1-2008 . +.Pp +.Fx +sets +.Va errno +to +.Er EMLINK instead of +.Er ELOOP +as specified by +POSIX +when +.Dv O_NOFOLLOW +is set in flags and the final component of pathname is a symbolic link +to distinguish it from the case of too many symbolic link traversals +in one of its non-final components. +.Pp +The Open Group Extended API Set 2 specification, that introduced the +.Fn *at +API, required that the test for whether +.Fa fd +is searchable is based on whether +.Fa fd +is open for searching, not whether the underlying directory currently +permits searches. +The present implementation of the +.Fa openat +system call is believed to be compatible with +.\" .St -p1003.1-2017 , +.\" XXX: This should be replaced in the future when an appropriate argument to +.\" the St macro is available: -p1003.1-2017 +.No IEEE Std 1003.1-2008, 2017 Edition ("POSIX.1") , +which specifies that behavior for +.Dv O_SEARCH , +in the absence of the flag the implementation checks the current +permissions of a directory. +.Sh HISTORY +The +.Fn open +function appeared in +.At v1 . +The +.Fn openat +function was introduced in +.Fx 8.0 . +.Dv O_DSYNC +appeared in 13.0. +.Dv O_NAMEDATTR +appeared in 15.0. +.Dv O_CLOFORK +appeared in +.Fx 15.0 . +.Sh BUGS +The +.Fa mode +argument is variadic and may result in different calling conventions +than might otherwise be expected. |