Return to flock.2 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys

Annotation of 43BSDReno/lib/libc/sys/flock.2, revision 1.1.1.1

1.1       root        1: .\" Copyright (c) 1983 The Regents of the University of California.
                      2: .\" All rights reserved.
                      3: .\"
                      4: .\" Redistribution and use in source and binary forms are permitted provided
                      5: .\" that: (1) source distributions retain this entire copyright notice and
                      6: .\" comment, and (2) distributions including binaries display the following
                      7: .\" acknowledgement:  ``This product includes software developed by the
                      8: .\" University of California, Berkeley and its contributors'' in the
                      9: .\" documentation or other materials provided with the distribution and in
                     10: .\" all advertising materials mentioning features or use of this software.
                     11: .\" Neither the name of the University nor the names of its contributors may
                     12: .\" be used to endorse or promote products derived from this software without
                     13: .\" specific prior written permission.
                     14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
                     15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
                     16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
                     17: .\"
                     18: .\"    @(#)flock.2     6.6 (Berkeley) 6/23/90
                     19: .\"
                     20: .TH FLOCK 2 "June 23, 1990"
                     21: .UC 5
                     22: .SH NAME
                     23: flock \- apply or remove an advisory lock on an open file
                     24: .SH SYNOPSIS
                     25: .nf
                     26: .ft B
                     27: #include <sys/file.h>
                     28: .PP
                     29: .ft B
                     30: .DT
                     31: #define        LOCK_SH 1       /* shared lock */
                     32: #define        LOCK_EX 2       /* exclusive lock */
                     33: #define        LOCK_NB 4       /* don't block when locking */
                     34: #define        LOCK_UN 8       /* unlock */
                     35: .PP
                     36: .ft B
                     37: flock(fd, operation)
                     38: int fd, operation;
                     39: .fi
                     40: .SH DESCRIPTION
                     41: .I Flock
                     42: applies or removes an
                     43: .I advisory
                     44: lock on the file associated with the file descriptor
                     45: .IR fd .
                     46: A lock is applied by specifying an
                     47: .I operation
                     48: parameter that is the inclusive or of
                     49: LOCK_SH or LOCK_EX and, possibly, LOCK_NB.  To unlock
                     50: an existing lock
                     51: .I operation
                     52: should be LOCK_UN.
                     53: .PP
                     54: Advisory locks allow cooperating processes to perform
                     55: consistent operations on files, but do not guarantee
                     56: consistency (i.e., processes may still access files
                     57: without using advisory locks possibly resulting in
                     58: inconsistencies).
                     59: .PP
                     60: The locking mechanism allows two types of locks:
                     61: .I shared
                     62: locks and
                     63: .I exclusive
                     64: locks.
                     65: At any time multiple shared locks may be applied to a file,
                     66: but at no time are multiple exclusive, or both shared and exclusive,
                     67: locks allowed simultaneously on a file.  
                     68: .PP
                     69: A shared lock may be
                     70: .I upgraded
                     71: to an exclusive lock, and vice versa, simply by specifying
                     72: the appropriate lock type; this results in the previous
                     73: lock being released and the new lock applied (possibly
                     74: after other processes have gained and released the lock).
                     75: .PP
                     76: Requesting a lock on an object that is already locked
                     77: normally causes the caller to be blocked until the lock may be
                     78: acquired.  If LOCK_NB is included in
                     79: .IR operation ,
                     80: then this will not happen; instead the call will fail and
                     81: the error EWOULDBLOCK will be returned.
                     82: .SH NOTES
                     83: Locks are on files, not file descriptors.  That is, file descriptors
                     84: duplicated through
                     85: .IR dup (2)
                     86: or
                     87: .IR fork (2)
                     88: do not result in multiple instances of a lock, but rather multiple
                     89: references to a single lock.  If a process holding a lock on a file
                     90: forks and the child explicitly unlocks the file, the parent will
                     91: lose its lock.
                     92: .PP
                     93: Processes blocked awaiting a lock may be awakened by signals.
                     94: .SH "RETURN VALUE
                     95: Zero is returned if the operation was successful;
                     96: on an error a \-1 is returned and an error code is left in
                     97: the global location \fIerrno\fP.
                     98: .SH "ERRORS
                     99: The \fIflock\fP call fails if:
                    100: .TP 20
                    101: [EWOULDBLOCK]
                    102: The file is locked and the LOCK_NB option was specified.
                    103: .TP 20
                    104: [EBADF]
                    105: The argument \fIfd\fP is an invalid descriptor.
                    106: .TP 20
                    107: [EINVAL]
                    108: The argument \fIfd\fP refers to an object other than a file.
                    109: .SH "SEE ALSO"
                    110: 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.