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

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