lockf(2)
_________________________________________________________________
lockf System Call
Apply or remove an advisory or mandatory file lock.
_________________________________________________________________
SYNTAX
#include <unistd.h>
int lockf (fildes, operation, size)
int fildes;
int operation;
long size;
PARAMETERS
fildes An active, valid file descriptor
operation Type of the lock operation.
size Length in bytes of the portion of the file to be
locked.
DESCRIPTION
<Fildes> is a valid, active file descriptor, referring to a file
of type ordinary, FIFO, pipe, block special, or character
special. Lockf allows lock operations to be performed on a
section of the file referenced by <fildes>, including setting a
lock, unlocking a lock, and testing for the presence of a lock.
Locks set by lockf are equivalent to write locks set by fcntl.
A lock covers an arbitrary sequence of bytes within a file.
Locks obtained by lockf are exclusive, and a lockf call by a
process attempting to lock a section already locked by another
process either returns an error or causes the calling process to
sleep until the section is unlocked. Locks on disjoint sections
of the file may coexist with no effect on each other.
A lock persists until it is unlocked or the file is closed by the
process that set the lock. Even if there are multiple valid,
active descriptors for a file, a close of one of them causes all
locks on the file held by the process to be released. When a
process terminates, all its locks are released as part of the
automatic closing of files. Similarly, exec unlocks the
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
lockf(2)
process's locks on files whose close-on-exec attribute bit is
set, but leaves locks on other files. Locks are not inherited by
a child process during a fork system call.
The lock operation to be performed is specified by operation,
which can have the following values:
F_ULOCK 0 Unlock a previously locked section.
F_LOCK 1 Lock a section; wait if not available.
F_TLOCK 2 Lock a section; don't wait if not available.
F_TEST 3 Test a section for the presence of other
process' locks.
Values of operation other than those listed above will cause
lockf to fail with the error condition EINVAL.
The section of the file that the operation is performed on is
determined by <size> and the current offset in the file. If
<size> is non-zero, it gives the number of contiguous bytes in
the section. The section starts at the current offset in the
file and extends forward for a positive <size> and backwards for
a negative <size> (the preceeding bytes up to but not including
the current offset). If <size> is zero, the section specified
extends from the current offset through the largest file offset
(i.e., through the present or any future end-of-file). The start
or end of the section may be located past the current end-of-
file, but neither can be negative relative to the beginning of
the file.
The F_LOCK and F_TLOCK operations lock a section of the file.
The section may contain, be contained by, or partly overlap one
or more previously locked regions for the same process. In this
case, the sections are combined into a single locked section
covering the union of the individual sections.
If another process holds a lock on any portion of the specified
section, then the section is not available for locking. F_LOCK
and F_TLOCK differ only in the action taken when this occurs.
F_LOCK causes the process to sleep until the section is
available, at which time another attempt is made to lock it.
F_TLOCK fails without obtaining the lock and sets errno to
EACCES.
The F_ULOCK operation unlocks all sections or portions of
sections previously locked by the calling process that lie within
the section specified for this call. The released areas become
available for locking by other processes. When a previously
locked section is not fully unlocked, the remaining portions are
still locked by the process. Specifying a section that contains
no locked areas does not produce an error. Locks by other
processes within the specified section are unaffected.
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
lockf(2)
The F_LOCK and F_TLOCK operations and the F_ULOCK operation may
fail by exceeding per-process limits on lock resources. If this
happens, no locks are altered by the call, and errno is set to
FNOLCK.
The F_TEST operation checks whether a lock by another process is
present on any part of the specified section. If so, the call
fails and errno is set to EACCES. If no locks are detected, the
call returns without error. F_TEST does not alter the state of
any lock.
Locks on files of type 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 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.
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)
lockf(2)
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
<Fildes> must give the process O_WRONLY or O_RDWR access to the
file.
RETURN VALUE
0 The lock operation was successful.
-1 An error occurred. Errno is set to indicate the
error.
EXCEPTIONS
Errno may be set to one of the following error codes:
EACCES The lock could not be obtained.
EBADF <Fildes> is not an active, valid descriptor.
EBADF <Fildes> does not give the process write access to
the file.
EDEADLK A deadlock would occur if the process were to
block awaiting the lock.
EINTR An interrupt was received before the lock could
obtained.
EINVAL <Function> is not a valid lock operation.
ENOLCK The request would exceed the per- process limit
for lock resources.
DG/UX 4.00 Page 4
Licensed material--property of copyright holder(s)
lockf(2)
SEE ALSO
The related system calls: flock(2), chmod(2), close(2),
creat(2), fcntl(2), open(2), read(2), write(2), flock(2).
DG/UX 4.00 Page 5
Licensed material--property of copyright holder(s)