Return to flock.2 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / man2

Annotation of 43BSDTahoe/man/man2/flock.2, revision 1.1.1.1

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