NAME

locking - locks or unlocks a file region for reading or writing

SYNOPSIS

cc [flag ...] file ... -lx
locking (int fildes, int mode, long size)

DESCRIPTION

locking allows a specified number of bytes in a file to be controlled by the locking process. Other processes which attempt to read or write a portion of the file containing the locked region may sleep until the area become unlocked depending upon the mode in which the file region was locked. A process that attempts to write to or read a file region that has been locked against reading and writing by another process (using the LK_LOCK or LK_NBLCK mode) with sleep until the region of the file has been released by the locking process. A process that attempts to write to a file region that has been locked against writing by another process (using the LK_RLCK or LK_NBRLCK mode) will sleep until the region of the file has been released by the locking process, but a read request for that file region will proceed normally. A process that attempts to lock a region of a file that contains areas that have been locked by other processes will sleep if it has specified the LK_LOCK or LK_RLCK mode in its lock request, but will return with the error EACCES if it specified LK_NBLCK or LK_NBRLCK. fildes is the value returned from a successful create, open, dup, or pipe system call. mode specifies the type of lock operation to be performed on the file region. The available values for mode are:

LK_UNLCK 0

Unlocks the specified region. The calling process releases a region of the file it has previously locked.

LK_LOCK 1 Locks the specified region.  The  calling  process
          will sleep until the entire region is available if
          any part of it has been locked by a different pro-
          cess.   The  region is then locked for the calling
          process and no other process may read or write  in
          any  part  of the locked region (lock against read
          and write).

LK_NBLCK 2

Locks the specified region. If any part of the region is already locked by a different process, return the error EACCES instead of waiting for the region to become available for locking (nonblocking lockrequest).

LK_RLCK 3 Same as LK_LOCK except that the locked region  may
          be read by other processes (read permitted lock).

LK_NBRLCK 4
          Same as LK_NBLCK except that the locked region may
          be read by other processes (nonblocking, read per-
          mitted  lock).   The  locking  utility  uses   the
          current  file  pointer  position  as  the starting
          point for the locking of the file segment.   So  a
          typical  sequence  of  commands to lock a specific
          range within a file might be as follows:
          fd=open("datafile",O_RDWR);
          lseek(fd, 200L, 0);
          locking(fd, LK_LOCK, 200L);
Accordingly, to lock or unlock an entire file a seek to  the
beginning  of  the file (position 0) must be done and then a
locking call must be executed with a size of 0.  size is the
number  of  contiguous bytes to be locked for unlocked.  The
region to be locked starts at  the  current  offset  in  the
file.   If size is 0, the entire file is locked or unlocked.
size may extend beyond the end of the file,  in  which  case
only  the  process  issuing  the lock call may access or add
information to the file within the boundary defined by size.
The  potential for a deadlock occurs when a process control-
ling a locked area is put to sleep by accessing another pro-
cess'  locked  area.   Thus calls to locking, read, or write
scan for a deadlock prior to sleeping on  a  locked  region.
An  EDEADLK  error  return is made if sleeping on the locked
region would cause a deadlock.  Lock requests may, in  whole
or  part,  contain  or  be  contained by a previously locked
region for the same process.   When  this  occurs,  or  when
adjacent regions are locked, the regions are combined into a
single area if the mode of  the  lock  is  the  same  (i.e.;
either  read permitted or regular lock).  If the mode of the
overlapping locks differ, the locked areas will be  assigned
assuming  that  the  most  recent request must be satisfied.
Thus if a read only lock is applied to a region, or part  of
a  region,  that had been previously locked by the same pro-
cess against both reading and writing, the area of the  file
specified  by  the  new  lock  will be locked for read only,
while the remaining  region,  if  any,  will  remain  locked
against reading and writing.  There is no arbitrary limit to
the number of regions which may be locked in a file.  Unlock
requests  may,  in whole or part, release one or more locked
regions controlled by the process.   When  regions  are  not
fully  released, the remaining areas are still locked by the
process.  Release of the center section  of  a  locked  area
requires  an additional locked element to hold the separated
section.  If the lock table is full, an error  is  returned,
and  the requested region is not released.  Only the process
which locked the file  region  may  unlock  it.   An  unlock
request  for a region that the process does not have locked,
or that is already unlocked, has no effect.  When a  process
terminates,  all  locked  regions controlled by that process
are unlocked.  If a process has done more than one open on a
file,  all  locks  put  on  the file by that process will be
released on the first close of the file.  Although no  error
is  returned if locks are applied to special files or pipes,
read/write operations on these types of  files  will  ignore
the locks.  Locks may not be applied to a directory.

SEE ALSO

close(2)  creat(2),  dup(2),  lseek(2),  open(2),   read(2),
write(2)

DIAGNOSTICS

locking returns the value (int)-1 if an error occurs. If any portion of the region has been locked by another process for the LK_LOCK and LK_RLCK actions and the lock request is to test only, errno is set to EAGAIN. If locking the region would cause a deadlock, errno is set to EDEADLK If an internal lock cannot be allocated, errno is set to ENOLCK.