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

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