chiark - git - mdw - mLib/blob - man/lock.3

   1 .\" -*-nroff-*-
   2 .TH lock 3mLib "23 May 1999" mLib
   3 .SH NAME
   4 lock \- oversimplified file locking interface
   5 .SH SYNOPSIS
   6 .nf
   7 .B "#include <mLib/lock.h>
   8
   9 .BI "int lock_file(int " fd ", unsigned " how );
  10 .fi
  11 .SH DESCRIPTION
  12 The
  13 .B lock_file
  14 function provides an extremely simplistic interface to POSIX
  15 .BR fcntl (2)
  16 locking.  It locks only entire files, not sections of files.  It doesn't
  17 have a nonblocking `is this file locked?' function.
  18 .PP
  19 On entry,
  20 .I fd
  21 should be a file descriptor on an open file, and
  22 .I how
  23 is a constant which describes how the file is to be locked.  The
  24 possible values of
  25 .I how
  26 are:
  27 .TP
  28 .B LOCK_EXCL
  29 Lock the file exclusively.  Attempts to lock the file exclusively or
  30 nonexclusively will fail until the file is unlocked.
  31 .TP
  32 .B LOCK_NONEXCL
  33 Lock the file nonexclusively.  Until the file is unlocked, attempts to
  34 lock it exclusively will fail, but other nonexclusive locks will
  35 succeed.
  36 .TP
  37 .B LOCK_UNLOCK
  38 Unlocks a locked file.  Any locks afterwards can succeed.
  39 .PP
  40 The
  41 .B lock_file
  42 function will block if it can't obtain a lock immediately.  It will time
  43 itself out after a short while (10 seconds in the current
  44 implementation) if the lock doesn't become available.
  45 .PP
  46 If the call succeeds,
  47 .B lock_file
  48 returns zero.  On failure, \-1 is returned, and
  49 .B errno
  50 is set to an appropriate value.  Most of the error returns are from
  51 .BR fcntl (2)
  52 (q.v.).  If the lock operation times out,
  53 .B errno
  54 is set to
  55 .BR EINTR .
  56 .SH AUTHOR
  57 Mark Wooding, <mdw@nsict.org>