'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright (c) 1983 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement specifies the terms and conditions for redistribution.
.TH FLOCK 3UCB "Oct 30, 2007"
.SH NAME
flock \- apply or remove an advisory lock on an open file
.SH SYNOPSIS
.LP
.nf
\fB/usr/ucb/cc\fR[ \fIflag\fR ... ] \fIfile\fR ...
#include <sys/file.h>

\fBint\fR \fBflock\fR( \fIfd\fR,  \fIoperation\fR)

\fBint\fR \fIfd\fR, \fIoperation\fR;
.fi

.SH DESCRIPTION
.sp
.LP
\fBflock()\fR applies or removes an \fIadvisory\fR lock on the file associated
with the file descriptor \fIfd\fR. The compatibility version of \fBflock()\fR
has been implemented on top of \fBfcntl\fR(2) locking.  It does not provide
complete binary compatibility.
.sp
.LP
Advisory locks allow cooperating processes to perform consistent operations on
files, but do not guarantee exclusive access (that is, processes may still
access files without using advisory locks, possibly resulting in
inconsistencies).
.sp
.LP
The locking mechanism allows two types of locks: shared locks and exclusive
locks. More than one process may hold a shared lock for a file at any given
time, but multiple exclusive, or both shared and exclusive, locks may not exist
simultaneously on a file.
.sp
.LP
A lock is applied by specifying an \fIoperation\fR parameter \fBLOCK_SH\fR for
a shared lock or \fBLOCK_EX\fR for an exclusive lock. The \fIoperation\fR
parameter may be ORed with \fBLOCK_NB\fR to make the operation non-blocking. To
unlock an existing lock, the \fIoperation\fR should be \fBLOCK_UN.\fR
.sp
.LP
Read permission is required on a file to obtain a shared lock, and write
permission is required to obtain an exclusive lock. Locking a segment that is
already locked by the calling process causes the old lock type to be removed
and the new lock type to take effect.
.sp
.LP
Requesting a lock on an object that is already locked normally causes the
caller to block until the lock may be acquired.  If \fBLOCK_NB\fR is included
in \fIoperation\fR, then this will not happen; instead, the call will fail and
the error \fBEWOULDBLOCK\fR will be returned.
.SH RETURN VALUES
.sp
.LP
\fBflock()\fR returns:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 9n
on success.
.RE

.sp
.ne 2
.na
\fB\fB\(mi1\fR\fR
.ad
.RS 9n
on failure and sets \fBerrno\fR to indicate the error.
.RE

.SH ERRORS
.sp
.ne 2
.na
\fB\fBEBADF\fR\fR
.ad
.RS 15n
The argument \fIfd\fR is an invalid descriptor.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 15n
\fIoperation\fR is not a valid argument.
.RE

.sp
.ne 2
.na
\fB\fBEOPNOTSUPP\fR\fR
.ad
.RS 15n
The argument \fIfd\fR refers to an object other than a file.
.RE

.sp
.ne 2
.na
\fB\fBEWOULDBLOCK\fR\fR
.ad
.RS 15n
The file is locked and the  \fBLOCK_NB\fR option was specified.
.RE

.SH SEE ALSO
.sp
.LP
\fBlockd\fR(1M), \fBchmod\fR(2), \fBclose\fR(2), \fBdup\fR(2), \fBexec\fR(2),
\fBfcntl\fR(2), \fBfork\fR(2), \fBopen\fR(2), \fBlockf\fR(3C)
.SH NOTES
.sp
.LP
Use of these interfaces should be restricted to only applications written on
BSD platforms.  Use of these interfaces with any of the system libraries or in
multi-thread applications is unsupported.
.sp
.LP
Locks are on files, not file descriptors.  That is, file descriptors duplicated
through \fBdup\fR(2) or \fBfork\fR(2) do not result in multiple instances of a
lock, but rather multiple references to a single lock.  If a process holding a
lock on a file forks and the child explicitly unlocks the file, the parent will
lose its lock. Locks are not inherited by a child process.
.sp
.LP
Processes blocked awaiting a lock may be awakened by signals.
.sp
.LP
Mandatory locking may occur, depending on the mode bits of the file.  See
\fBchmod\fR(2).
.sp
.LP
Locks obtained through the \fBflock()\fR mechanism under SunOS 4.1 were known
only within the system on which they were placed.  This is no longer true.