From: Kirk McKusick Date: Thu, 8 Jul 1993 01:56:15 +0000 (-0800) Subject: add description for lockf advisory file locking X-Git-Tag: BSD-4_4_Lite1-Snapshot-Development~2423 X-Git-Url: https://git.subgeniuskitty.com/unix-history/.git/commitdiff_plain/bc4228693066196bd8d779ef4169c5421faeb82b add description for lockf advisory file locking SCCS-vsn: lib/libc/sys/fcntl.2 6.11 --- diff --git a/usr/src/lib/libc/sys/fcntl.2 b/usr/src/lib/libc/sys/fcntl.2 index 868518450b..5d83bce977 100644 --- a/usr/src/lib/libc/sys/fcntl.2 +++ b/usr/src/lib/libc/sys/fcntl.2 @@ -3,7 +3,7 @@ .\" .\" %sccs.include.redist.man% .\" -.\" @(#)fcntl.2 8.1 (Berkeley) %G% +.\" @(#)fcntl.2 6.11 (Berkeley) %G% .\" .Dd .Dt FCNTL 2 @@ -99,7 +99,7 @@ The flags for the and .Dv F_SETFL flags are as follows: -.Bl -tag -width F_GETOWNX +.Bl -tag -width O_NONBLOCKX .It Dv O_NONBLOCK Non-blocking I/O; if no data is available to a .Xr read @@ -121,6 +121,188 @@ 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: +.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 @@ -145,15 +327,71 @@ is set to indicate the error. .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 @@ -163,6 +401,38 @@ and 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 @@ -173,6 +443,7 @@ the process ID given as argument is not in use. .Sh SEE ALSO .Xr close 2 , .Xr execve 2 , +.Xr flock 2 , .Xr getdtablesize 2 , .Xr open 2 , .Xr sigvec 2