flock(2)
_________________________________________________________________
flock System Call
Apply or remove an advisory or mandatory file lock.
_________________________________________________________________
SYNTAX
#include <sys/types.h>
#include <sys/file.h>
#define LOCK_SH 1 /*shared lock
#define LOCK_EX 2 /*exclusive lock
#define LOCK_NB 4 /*don't block when locking
#define LOCK_UN 8 /*unlock
int flock (fildes, operation)
int fildes;
int operation;
PARAMETERS
fildes A valid active file descriptor.
operation A type of lock operation.
DESCRIPTION
<Fildes> is a valid, active file descriptor referring to an open
file of type ordinary, directory, block special, or character
special. Flock applies or removes a lock to the entire file,
depending on the <operation> specified. Recognized values of
<operation> are:
* LOCK_UN - Unlock.
* LOCK_EX - Obtain an exclusive lock.
* LOCK_SH - Obtain a shared lock.
LOCK_EX and LOCK_SH may be or-ed with LOCK_NB to specify a non-
blocking request for a lock. Bits in <operation> other than
these four flags are always ignored. The flags are listed in
order of precedence. That is, if LOCK_UN is specified, LOCK_EX,
LOCK_SH, and LOCK_NB are ignored. If LOCK_UN is not specified,
but LOCK_EX is, LOCK_SH is ignored. If only LOCK_NB is
specified, no action is taken, but an error is not returned.
Advisory locks allow cooperating processes to perform consistent
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
flock(2)
operations on files, but do not guarantee consistency (i.e.,
processes may still access files without using advisory locks,
possibly resulting in inconsistencies).
Locks are obtained by specifying either LOCK_SH or LOCK_EX in
<operation>. At any time multiple shared locks may be applied to
a file, but at no time are multiple exclusive, or both shared and
exclusive, locks allowed simultaneously on a file. To unlock an
existing lock, <operation> should be LOCK_UN.
A shared lock may be changed to an exclusive lock, and vice
versa, by specifying the new lock type in <operation>. The
previous lock is released, and the new lock is applied, possibly
after other processes have gained and released the lock.
Requesting a lock on a file that is not available for that type
of lock normally causes the caller to block until the lock may be
acquired. If a shared or exclusive lock is requested with
LOCK_NB set, the calling process will not block if the lock is
unavailable. Instead the call fails and the error EWOULDBLOCK is
returned.
The call has no effect and returns without error if the process
requests a type of lock that it already holds on a file or if it
tries to release a lock that it does not hold. Locks are on
files rather than file descriptors. Hence, file descriptors
duplicated through dup or fork 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.
Processes blocked awaiting a lock may be awakened by signals; the
process does not receive the requested lock, and errno is set to
EINTR.
All advisory locks on a file are released on the last close of
the file. The last close may happen as the result of a close,
exec, or exit system call.
The F_GETFL operation of the fcntl system call allows a process
to view the type of advisory lock (if any) it holds on a file.
This operation returns the file pointer status flags associated
with a file descriptor. If the FSHLOCK flag (0200) is set, the
process holds a shared lock on the file. If the FEXLOCK flag
(0400) is set, the process holds an exclusive lock on the file.
Locks on files of type pipe, FIFO, block special, and character
special are always interpreted as being advisory. Locks on
ordinary files are interpreted as either advisory or mandatory,
depending on the enforcement mode of the file. If the
enforcement mode is S_ENFMT, all locks on that file are
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
flock(2)
considered mandatory. Any other value of the enforcement mode
indicates that locks are advisory. Note that as enforcement is
an attribute of the file and not of individual locks, there
cannot be a mixture of advisory and mandatory locks on a file.
Also, it is possible to change the interpretation of a lock on an
open file simply by altering the file's enforcement mode.
The advisory interpretation of locks allows cooperating processes
to perform consistent operations on files, but does not guarantee
consistency. That is, a process attempting to read or write a
section of a file on which another process holds a lock will not
block or be informed of the presence of the lock.
The mandatory interpretation of locks guarantees consistent file
operations. A process attempting to read or write a section of
an ordinary file on which another process holds a lock will block
until the entire section is free of locks by other processes. A
creat or open call that attempts to truncate a file will fail
with the error condition [EAGAIN] if another process has locked
any portion of the file.
A potential for deadlock occurs if a process holding a lock is
put to sleep when attempting to lock or access a section of a
file locked by another process. Thus, lockf, read, and write
scan for deadlock prior to sleeping on a locked file section.
Circular waits by processes on file sections are detected as
deadlocks. Deadlocks involving other system resources or
synchronization mechanisms are not detected. Any of the
processes involved in the deadlock that are attempting to obtain
a lock may be chosen to fail in the attempt. The system call
fails, and errno is set to EDEADLK.
Processes that block awaiting a lock may suffer indefinite
postponement.
Blocked processes may be awakened by signals; the lockf, read, or
write call fails without obtaining the lock or performing the
I/O, and errno is set to EINTR.
ACCESS CONTROL
None.
RETURN VALUE
0 The lock operation was successful.
-1 An error occurred. Errno is set to indicate the
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)
flock(2)
error.
EXCEPTIONS
Errno may be set to one of the following error codes:
EBADF <Fildes> is not a valid descriptor.
EOPNOTSUPP <Fildes> refers to an object other than a file.
EINTR An interrupt was received before the lock was
obtained.
EACCES The file is locked and the LOCK_NB option was
specified.
EINVAL <operation> is not a valid lock operation.
EDEADLK Awaiting the lock would cause a deadlock.
ENOLCK The request would exceed the per-process limit for
lock resources.
SEE ALSO
The related system calls: lockf(2), open(2), close(2), dup(2),
exec(2), fork(2), fcntl(2).
DG/UX 4.00 Page 4
Licensed material--property of copyright holder(s)