locking(2)                                             locking(2)



     NAME
          locking - provide exclusive  file  regions  for  reading  or
          writing

     SYNOPSIS
          int locking(fildes, mode, size)
          int fildes;
          int mode;
          int size;

     DESCRIPTION
          locking will allow a specified number of bytes to be ac-
          cessed only by the locking process (mandatory locking).
          Other processes which attempt to lock, read, or write the
          locked area will sleep until the area becomes unlocked.
          (Advisory locking is available via lockf(3C)).

          fildes is the word returned from a successful open, creat,
          dup, or pipe system call.

          mode is zero to unlock the area.  mode is one or two for
          making the area locked. If the mode is one and the area has
          some other lock on it, then the process will sleep until the
          entire area is available. If the mode is two and the area is
          locked, an error will be returned.

          size is the number of contiguous bytes to be locked or un-
          locked.  The area to be locked starts at the current offset
          in the file.  If size is zero, the area to the end of file
          is locked.

          The potential for a deadlock occurs when a process control-
          ling a locked area is put to sleep by accessing another
          process's locked area.  Thus calls to locking, read, or
          write scan for a deadlock prior to sleeping on a locked
          area.  An error return is made if sleeping on the locked
          area would cause a deadlock.

          Lock requests may, in whole or part, contain or be contained
          by a previously locked area for the same process.  When this
          or adjacent areas occur, the areas are combined into a sin-
          gle area.  If the request requires a new lock element with
          the lock table full, an error is returned, and the area is
          not locked.

          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 lock element to hold the cut off sec-
          tion. If the lock table is full, an error is returned, and
          the requested area is not released.



     April, 1990                                                     1

     locking(2)                                             locking(2)



          While locks may be applied to special files or pipes,
          read/write operations will not be blocked.  Locks may not be
          applied to a directory.

          Note that close(2) automatically removes any locks that were
          associated with the closed file descriptor.

     RETURN VALUE
          The value -1 is returned if the file does not exist, or if a
          deadlock using file locks would occur.

     ERRORS
          locking will fail if the following are true:

          [EACCES]  The area is already locked by another process.

          [EDEADLOCK]
                    Returned by read, write, or locking if a deadlock
                    would occur.

          [EDEADLOCK]
                    Locktable overflow.

          [EREMOTE] fildes is a file descriptor that refers to file on
                    a remotely mounted file system.

     SEE ALSO
          close(2), creat(2), dup(2), open(2), read(2), write(2),
          lockf(3C).


























     2                                                     April, 1990