FLOCK(3C) Standard C Library Functions FLOCK(3C)

NAME

flock - OFD(open file description)-style file locking

SYNOPSIS

#include <sys/file.h>

int flock(int fildes, int operation);

DESCRIPTION

The flock() function allows advisory locks to be applied to and
removed from a file. Calls to flock() from callers that attempt to
lock the locked file section via a different open file handle will
either return an error value or be put to sleep until the resource
becomes unlocked. See fcntl(2) for more information about record
locking. Locks created or removed via this function will apply to the
entire file, including any future growth in the file's length.


The fildes argument is an open file descriptor. A lock can be
established without regard for the mode with which the file was
opened.


The operation argument is a control value that specifies the action
to be taken. The permissible values for operation are defined in
<sys/file.h> as follows:

#define LOCK_SH 1 /* shared file lock */
#define LOCK_EX 2 /* exclusive file lock */
#define LOCK_NB 4 /* do not block when attempting to create lock */
#define LOCK_UN 8 /* remove existing file lock */


To create a lock, either LOCK_SH or LOCK_EX should be specified,
optionally bitwise-ored with LOCK_NB. To remove a lock, LOCK_UN
should be specified. All other values of operation are reserved for
future extensions and will result in an error if not implemented.


This function creates, upgrades, downgrades, or removes either shared
or exclusive OFD-style locks. Locks created by this function are
owned by open files, not file descriptors. That is, file descriptors
duplicated through dup(2), fork(2), or fcntl(2) do not result in
multiple instances of a lock, but rather multiple references to the
same lock. If a process holding a lock on a file forks and the child
explicitly unlocks the file, the parent will lose its lock. See
fcntl(2) for more information about file locking and the interaction
between locks created by this function and those created by other
mechanisms. These locks are currently not supported over remote file
systems (e.g. nfs(5)) which use the Network Lock Manager.


Sleeping on a resource is interrupted with any signal. The alarm(2)
function may be used to provide a timeout facility in applications
that require this facility.

RETURN VALUES

Upon successful completion, 0 is returned. Otherwise, -1 is returned
and errno is set to indicate the error.

ERRORS

The flock() function will fail if:

EBADF
The fildes argument is not a valid open file
descriptor; or operation contains LOCK_SH and
filedes is not open for reading; or operation
contains LOCK_EX and filedes is not open for
writing.


EWOULDBLOCK
The operation argument contains LOCK_NB and a
conflicting lock exists.


EINTR
A signal was caught during execution of the
function.


EINVAL
The operation argument does not contain one of
LOCK_SH, LOCK_EX, or LOCK_UN; or the operation
argument contains LOCK_UN and LOCK_NB; or the
operation argument contains any bits other than
those set by LOCK_SH, LOCK_EX, LOCK_NB, and
LOCK_UN.


The flock() function may fail if:

EAGAIN
The operation argument contains LOCK_SH or
LOCK_EX and the file is mapped with mmap(2).


ENOLCK
The number of locked file regions in the system
would exceed a system-imposed limit.


EOPNOTSUPP
The locking of files of the type indicated by
the fildes argument is not supported.

USAGE

File-locking should not be used in combination with the fopen(3C),
fread(3C), fwrite(3C) and other stdio functions. Instead, the more
primitive, non-buffered functions (such as open(2)) should be used.
Unexpected results may occur in processes that do buffering in the
user address space. The process may later read/write data which
is/was locked. The stdio functions are the most common source of
unexpected buffering.


The alarm(2) function may be used to provide a timeout facility in
applications requiring it.


Locks created by this facility conflict with those created by the
lockf(3C) and fcntl(2) facilities. This facility creates and removed
OFD-style locks; see fcntl(2) for information about the interaction
between OFD-style and POSIX-style file locks.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+

SEE ALSO

Intro(2), alarm(2), chmod(2), close(2), creat(2), fcntl(2), mmap(2),
open(2), read(2), write(2), attributes(7), standards(7)

February 16, 2015 FLOCK(3C)