Return to flock.2 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man2

Annotation of cci/usr/src/man/man2/flock.2, revision 1.1.1.1

1.1       root        1: .TH FLOCK 2 "27 July 1983"
                      2: .UC 4
                      3: .SH NAME
                      4: flock \- apply or remove an advisory lock on an open file
                      5: .SH SYNOPSIS
                      6: .nf
                      7: .ft B
                      8: #include <sys/file.h>
                      9: .PP
                     10: .ft B
                     11: .DT
                     12: #define        LOCK_SH 1       /* shared lock */
                     13: #define        LOCK_EX 2       /* exclusive lock */
                     14: #define        LOCK_NB 4       /* don't block when locking */
                     15: #define        LOCK_UN 8       /* unlock */
                     16: .PP
                     17: .ft B
                     18: flock(fd, operation)
                     19: int fd, operation;
                     20: .fi
                     21: .SH DESCRIPTION
                     22: .I Flock
                     23: applies or removes an
                     24: .I advisory
                     25: lock on the file associated with the file descriptor
                     26: .IR fd .
                     27: A lock is applied by specifying an
                     28: .I operation
                     29: parameter which is the inclusive or of
                     30: LOCK_SH or LOCK_EX and, possibly, LOCK_NB.  To unlock
                     31: an existing lock
                     32: .I operation
                     33: should be LOCK_UN.
                     34: .PP
                     35: Advisory locks allow cooperating processes to perform
                     36: consistent operations on files, but do not guarantee
                     37: consistency (i.e. processes may still access files
                     38: without using advisory locks possibly resulting in
                     39: inconsistencies).
                     40: .PP
                     41: The locking mechanism allows two types of locks:
                     42: .I shared
                     43: locks and
                     44: .I exclusive
                     45: locks.
                     46: At any time multiple shared locks may be applied to a file,
                     47: but at no time are multiple exclusive, or both shared and exclusive,
                     48: locks allowed simultaneously on a file.  
                     49: .PP
                     50: A shared lock may be
                     51: .I upgraded
                     52: to an exclusive lock, and vice versa, simply by specifying
                     53: the appropriate lock type; this results in the previous
                     54: lock being released and the new lock applied (possibly
                     55: after other processes have gained and released the lock).
                     56: .PP
                     57: Requesting a lock on an object which is already locked
                     58: normally causes the caller to blocked until the lock may be
                     59: acquired.  If LOCK_NB is included in
                     60: .IR operation ,
                     61: then this will not happen; instead the call will fail and
                     62: the error EWOULDBLOCK will be returned.
                     63: .SH NOTES
                     64: Locks are on files, not file descriptors.  That is, file descriptors
                     65: duplicated through
                     66: .IR dup (2)
                     67: or
                     68: .IR fork (2)
                     69: do not result in multiple instances of a lock, but rather multiple
                     70: references to a single lock.  If a process holding a lock on a file
                     71: forks and the child explicitly unlocks the file, the parent will
                     72: lose its lock.
                     73: .PP
                     74: Processes blocked awaiting a lock may be awakened by signals.
                     75: .SH "RETURN VALUE
                     76: Zero is returned if the operation was successful;
                     77: on an error a \-1 is returned and an error code is left in
                     78: the global location \fIerrno\fP.
                     79: .SH "ERRORS
                     80: The \fIflock\fP call fails if:
                     81: .TP 20
                     82: [EWOULDBLOCK]
                     83: The file is locked and the LOCK_NB option was specified.
                     84: .TP 20
                     85: [EBADF]
                     86: The argument \fIfd\fP is an invalid descriptor.
                     87: .TP 20
                     88: [EINVAL]
                     89: The argument \fIfd\fP refers to an object other than a file.
                     90: .SH "SEE ALSO"
                     91: open(2), close(2), dup(2), execve(2), fork(2)

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.