#include <sys/file.h>

int flock(int fildes, int operation);

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(4)) 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.

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

The flock() function will fail if: EBADF

The flock() function may fail if: EAGAIN

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.

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

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