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