diff options
Diffstat (limited to 'lib/libc/sys/fcntl.2')
| -rw-r--r-- | lib/libc/sys/fcntl.2 | 481 |
1 files changed, 481 insertions, 0 deletions
diff --git a/lib/libc/sys/fcntl.2 b/lib/libc/sys/fcntl.2 new file mode 100644 index 0000000..f53c02f --- /dev/null +++ b/lib/libc/sys/fcntl.2 @@ -0,0 +1,481 @@ +.\" Copyright (c) 1983, 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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. +.\" +.\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94 +.\" +.Dd January 12, 1994 +.Dt FCNTL 2 +.Os BSD 4.2 +.Sh NAME +.Nm fcntl +.Nd file control +.Sh SYNOPSIS +.Fd #include <fcntl.h> +.Ft int +.Fn fcntl "int fd" "int cmd" "int arg" +.Sh DESCRIPTION +.Fn Fcntl +provides for control over descriptors. +The argument +.Fa fd +is a descriptor to be operated on by +.Fa cmd +as follows: +.Bl -tag -width F_GETOWNX +.It Dv F_DUPFD +Return a new descriptor as follows: +.Pp +.Bl -bullet -compact -offset 4n +.It +Lowest numbered available descriptor greater than or equal to +.Fa arg . +.It +Same object references as the original descriptor. +.It +New descriptor shares the same file offset if the object +was a file. +.It +Same access mode (read, write or read/write). +.It +Same file status flags (i.e., both file descriptors +share the same file status flags). +.It +The close-on-exec flag associated with the new file descriptor +is set to remain open across +.Xr execv 2 +system calls. +.El +.It Dv F_GETFD +Get the close-on-exec flag associated with the file descriptor +.Fa fd . +If the low-order bit of the returned value is 0, +the file will remain open across +.Fn exec , +otherwise the file will be closed upon execution of +.Fn exec +.Fa ( arg +is ignored). +.It Dv F_SETFD +Set the close-on-exec flag associated with +.Fa fd +to the low order bit of +.Fa arg +(0 or 1 as above). +.It Dv F_GETFL +Get descriptor status flags, as described below +.Fa ( arg +is ignored). +.It Dv F_SETFL +Set descriptor status flags to +.Fa arg . +.It Dv F_GETOWN +Get the process ID or process group +currently receiving +.Dv SIGIO +and +.Dv SIGURG +signals; process groups are returned +as negative values +.Fa ( arg +is ignored). +.It Dv F_SETOWN +Set the process or process group +to receive +.Dv SIGIO +and +.Dv SIGURG +signals; +process groups are specified by supplying +.Fa arg +as negative, otherwise +.Fa arg +is interpreted as a process ID. +.El +.Pp +The flags for the +.Dv F_GETFL +and +.Dv F_SETFL +flags are as follows: +.Bl -tag -width O_NONBLOCKX +.It Dv O_NONBLOCK +Non-blocking I/O; if no data is available to a +.Xr read +call, or if a +.Xr write +operation would block, +the read or write call returns -1 with the error +.Er EAGAIN . +.It Dv O_APPEND +Force each write to append at the end of file; +corresponds to the +.Dv O_APPEND +flag of +.Xr open 2 . +.It Dv O_ASYNC +Enable the +.Dv SIGIO +signal to be sent to the process group +when I/O is possible, e.g., +upon availability of data to be read. +.El +.Pp +Several commands are available for doing advisory file locking; +they all operate on the following structure: +.ne 7v +.Bd -literal +struct flock { + off_t l_start; /* starting offset */ + off_t l_len; /* len = 0 means until end of file */ + pid_t l_pid; /* lock owner */ + short l_type; /* lock type: read/write, etc. */ + short l_whence; /* type of l_start */ +}; +.Ed +The commands available for advisory record locking are as follows: +.Bl -tag -width F_SETLKWX +.It Dv F_GETLK +Get the first lock that blocks the lock description pointed to by the +third argument, +.Fa arg , +taken as a pointer to a +.Fa "struct flock" +(see above). +The information retrieved overwrites the information passed to +.Nm fcntl +in the +.Fa flock +structure. +If no lock is found that would prevent this lock from being created, +the structure is left unchanged by this function call except for the +lock type which is set to +.Dv F_UNLCK . +.It Dv F_SETLK +Set or clear a file segment lock according to the lock description +pointed to by the third argument, +.Fa arg , +taken as a pointer to a +.Fa "struct flock" +(see above). +.Dv F_SETLK +is used to establish shared (or read) locks +.Dv (F_RDLCK) +or exclusive (or write) locks, +.Dv (F_WRLCK) , +as well as remove either type of lock +.Dv (F_UNLCK) . +If a shared or exclusive lock cannot be set, +.Nm fcntl +returns immediately with +.Er EACCES . +.It Dv F_SETLKW +This command is the same as +.Dv F_SETLK +except that if a shared or exclusive lock is blocked by other locks, +the process waits until the request can be satisfied. +If a signal that is to be caught is received while +.Nm fcntl +is waiting for a region, the +.Nm fcntl +will be interrupted if the signal handler has not specified the +.Dv SA_RESTART +(see +.Xr sigaction 2 ) . +.El +.Pp +When a shared lock has been set on a segment of a file, +other processes can set shared locks on that segment +or a portion of it. +A shared lock prevents any other process from setting an exclusive +lock on any portion of the protected area. +A request for a shared lock fails if the file descriptor was not +opened with read access. +.Pp +An exclusive lock prevents any other process from setting a shared lock or +an exclusive lock on any portion of the protected area. +A request for an exclusive lock fails if the file was not +opened with write access. +.Pp +The value of +.Fa l_whence +is +.Dv SEEK_SET , +.Dv SEEK_CUR , +or +.Dv SEEK_END +to indicate that the relative offset, +.Fa l_start +bytes, will be measured from the start of the file, +current position, or end of the file, respectively. +The value of +.Fa l_len +is the number of consecutive bytes to be locked. +If +.Fa l_len +is negative, the result is undefined. +The +.Fa l_pid +field is only used with +.Dv F_GETLK +to return the process ID of the process holding a blocking lock. +After a successful +.Dv F_GETLK +request, the value of +.Fa l_whence +is +.Dv SEEK_SET . +.Pp +Locks may start and extend beyond the current end of a file, +but may not start or extend before the beginning of the file. +A lock is set to extend to the largest possible value of the +file offset for that file if +.Fa l_len +is set to zero. If +.Fa l_whence +and +.Fa l_start +point to the beginning of the file, and +.Fa l_len +is zero, the entire file is locked. +If an application wishes only to do entire file locking, the +.Xr flock 2 +system call is much more efficient. +.Pp +There is at most one type of lock set for each byte in the file. +Before a successful return from an +.Dv F_SETLK +or an +.Dv F_SETLKW +request when the calling process has previously existing locks +on bytes in the region specified by the request, +the previous lock type for each byte in the specified +region is replaced by the new lock type. +As specified above under the descriptions +of shared locks and exclusive locks, an +.Dv F_SETLK +or an +.Dv F_SETLKW +request fails or blocks respectively when another process has existing +locks on bytes in the specified region and the type of any of those +locks conflicts with the type specified in the request. +.Pp +This interface follows the completely stupid semantics of System V and +.St -p1003.1-88 +that require that all locks associated with a file for a given process are +removed when \fIany\fP file descriptor for that file is closed by that process. +This semantic means that applications must be aware of any files that +a subroutine library may access. +For example if an application for updating the password file locks the +password file database while making the update, and then calls +.Xr getpwname 3 +to retrieve a record, +the lock will be lost because +.Xr getpwname 3 +opens, reads, and closes the password database. +The database close will release all locks that the process has +associated with the database, even if the library routine never +requested a lock on the database. +Another minor semantic problem with this interface is that +locks are not inherited by a child process created using the +.Xr fork 2 +function. +The +.Xr flock 2 +interface has much more rational last close semantics and +allows locks to be inherited by child processes. +.Xr Flock 2 +is recommended for applications that want to ensure the integrity +of their locks when using library routines or wish to pass locks +to their children. +Note that +.Xr flock 2 +and +.Xr fcntl 2 +locks may be safely used concurrently. +.Pp +All locks associated with a file for a given process are +removed when the process terminates. +.Pp +A potential for deadlock occurs if a process controlling a locked region +is put to sleep by attempting to lock the locked region of another process. +This implementation detects that sleeping until a locked region is unlocked +would cause a deadlock and fails with an +.Er EDEADLK +error. +.Sh RETURN VALUES +Upon successful completion, the value returned depends on +.Fa cmd +as follows: +.Bl -tag -width F_GETOWNX -offset indent +.It Dv F_DUPFD +A new file descriptor. +.It Dv F_GETFD +Value of flag (only the low-order bit is defined). +.It Dv F_GETFL +Value of flags. +.It Dv F_GETOWN +Value of file descriptor owner. +.It other +Value other than -1. +.El +.Pp +Otherwise, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn Fcntl +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +The argument +.Fa arg +is +.Dv F_SETLK , +the type of lock +.Fa (l_type) +is a shared lock +.Dv (F_RDLCK) +or exclusive lock +.Dv (F_WRLCK) , +and the segment of a file to be locked is already +exclusive-locked by another process; +or the type is an exclusive lock and some portion of the +segment of a file to be locked is already shared-locked or +exclusive-locked by another process. +.It Bq Er EBADF +.Fa Fildes +is not a valid open file descriptor. +.Pp +The argument +.Fa cmd +is +.Dv F_SETLK +or +.Dv F_SETLKW , +the type of lock +.Fa (l_type) +is a shared lock +.Dv (F_RDLCK) , +and +.Fa fildes +is not a valid file descriptor open for reading. +.Pp +The argument +.Fa cmd +is +.Dv F_SETLK +or +.Dv F_SETLKW , +the type of lock +.Fa (l_type) +is an exclusive lock +.Dv (F_WRLCK) , +and +.Fa fildes +is not a valid file descriptor open for writing. +.It Bq Er EMFILE +.Fa Cmd +is +.Dv F_DUPFD +and the maximum allowed number of file descriptors are currently +open. +.It Bq Er EDEADLK +The argument +.Fa cmd +is +.Dv F_SETLKW , +and a deadlock condition was detected. +.It Bq Er EINTR +The argument +.Fa cmd +is +.Dv F_SETLKW , +and the function was interrupted by a signal. +.It Bq Er EINVAL +.Fa Cmd +is +.Dv F_DUPFD +and +.Fa arg +is negative or greater than the maximum allowable number +(see +.Xr getdtablesize 2 ) . +.Pp +The argument +.Fa cmd +is +.Dv F_GETLK , +.Dv F_SETLK , +or +.Dv F_SETLKW +and the data to which +.Fa arg +points is not valid, or +.Fa fildes +refers to a file that does not support locking. +.It Bq Er EMFILE +The argument +.Fa cmd +is +.Dv F_DUPED +and the maximum number of file descriptors permitted for the +process are already in use, +or no file descriptors greater than or equal to +.Fa arg +are available. +.It Bq Er ENOLCK +The argument +.Fa cmd +is +.Dv F_SETLK +or +.Dv F_SETLKW , +and satisfying the lock or unlock request would result in the +number of locked regions in the system exceeding a system-imposed limit. +.It Bq Er ESRCH +.Fa Cmd +is +.Dv F_SETOWN +and +the process ID given as argument is not in use. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr execve 2 , +.Xr flock 2 , +.Xr getdtablesize 2 , +.Xr open 2 , +.Xr sigvec 2 +.Sh HISTORY +The +.Nm +function call appeared in +.Bx 4.2 . |
