flock(2POSIX)

NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | PARAMETERS | EXTENDED DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO | NOTES

NAME

flock- apply or remove an advisory lock on an open file

SYNOPSIS

#include <sys/file.h>
#define  LOCK_SH   0x01   /* shared file lock */
#define  LOCK_EX   0x02   /* exclusive file lock */
#define  LOCK_NB   0x04   /* do not block when locking */
#define  LOCK_UN   0x08   /* unlock file */

int flock(int fd, int operation);

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

FEATURES

MSDOSFS, NFS_CLIENT, UFS

DESCRIPTION

flock() applies or removes an advisory lock on the file associated with the file descriptor fd. A lock is applied by specifying an operation parameter that is one of LOCK_SH or LOCK_EX with the optional addition of LOCK_NB. An existing lock is removed using the LOCK_UN operation.

PARAMETERS

flock() takes the following parameters:

fd

File descriptor of the file on which to perform operation

operation

Operation to be performed on fd

EXTENDED DESCRIPTION

Advisory locks allow cooperating processes to perform consistent operations on files, but do not guarantee consistency. Processes may, for example, access files without using advisory locks, which may result in inconsistencies.

The locking mechanism allows two types of locks: shared locks and exclusive locks. At any time, multiple shared locks may be applied to a file, but at no time may multiple exclusive locks or both shared and exclusive locks be applied simultaneously to a file.

A shared lock may be upgraded to an exclusive lock and vice versa simply by specifying the appropriate lock type. Upgrading a lock involves releasing the previous lock and applying the new lock, possibly after other processes have obtained and released the lock.

Requesting a lock on an object that is already locked normally causes the caller to be blocked until the lock can be applied. If LOCK_NB is included in operation, the caller is not blocked. Instead, the call fails and flock() returns the error EWOULDBLOCK.

RETURN VALUES

0 is returned if the operation was successful. If unsuccessful, -1 is returned and errno is set to indicate one of the following error conditions.

ERRORS

The flock() call fails if:

EWOULDBLOCK

The file is locked and the LOCK_NB operation was specified.

EBADF

The fd argument is an invalid descriptor.

EINVAL

The fd argument refers to an object other than a file.

EOPNOTSUPP

The fd argument refers to an object that does not support file locking.

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving
MT-level	MT-safe

SEE ALSO

close(2POSIX), dup(2POSIX), open(2POSIX)

NOTES

Locks apply to files, not file descriptors. That is, file descriptors duplicated through dup() or posix_spawn() do not result in multiple instances of a lock, but rather multiple references to a single lock. If, for example, a process holding a lock on a file spawns and the child explicitly unlocks the file, the parent loses its lock.

ChorusOS 5.0  Last Revised December 2001

NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | PARAMETERS | EXTENDED DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO | NOTES