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

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for file locking
   4 .\"
   5 .\" (c) 1999, 2001, 2005, 2009, 2023, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH lock 3mLib "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @lock_file
  33 .
  34 .\"--------------------------------------------------------------------------
  35 .SH NAME
  36 lock \- oversimplified file locking interface
  37 .
  38 .\"--------------------------------------------------------------------------
  39 .SH SYNOPSIS
  40 .
  41 .nf
  42 .B "#include <mLib/lock.h>"
  43 .PP
  44 .ta 2n
  45 .B "enum {"
  46 .B "    LOCK_UNLOCK = ...,"
  47 .B "    LOCK_EXCL = ...,"
  48 .B "    LOCK_NONEXCL = ..."
  49 .B "};"
  50 .PP
  51 .BI "int lock_file(int " fd ", unsigned " how );
  52 .fi
  53 .
  54 .\"--------------------------------------------------------------------------
  55 .SH DESCRIPTION
  56 .
  57 The
  58 .B lock_file
  59 function provides an extremely simplistic interface to POSIX
  60 .BR fcntl (2)
  61 locking.  It locks only entire files, not sections of files.  It doesn't
  62 have a nonblocking `is this file locked?' function.
  63 .PP
  64 On entry,
  65 .I fd
  66 should be a file descriptor on an open file, and
  67 .I how
  68 is a constant which describes how the file is to be locked.  The
  69 possible values of
  70 .I how
  71 are:
  72 .TP
  73 .B LOCK_EXCL
  74 Lock the file exclusively.  Attempts to lock the file exclusively or
  75 nonexclusively will fail until the file is unlocked.
  76 .TP
  77 .B LOCK_NONEXCL
  78 Lock the file nonexclusively.  Until the file is unlocked, attempts to
  79 lock it exclusively will fail, but other nonexclusive locks will
  80 succeed.
  81 .TP
  82 .B LOCK_UNLOCK
  83 Unlocks a locked file.  Any locks afterwards can succeed.
  84 .PP
  85 The
  86 .B lock_file
  87 function will block if it can't obtain a lock immediately.  It will time
  88 itself out after a short while (10 seconds in the current
  89 implementation) if the lock doesn't become available.
  90 .PP
  91 If the call succeeds,
  92 .B lock_file
  93 returns zero.  On failure, \-1 is returned, and
  94 .B errno
  95 is set to an appropriate value.  Most of the error returns are from
  96 .BR fcntl (2)
  97 (q.v.).  If the lock operation times out,
  98 .B errno
  99 is set to
 100 .BR EINTR .
 101 .
 102 .\"--------------------------------------------------------------------------
 103 .SH "SEE ALSO"
 104 .
 105 .BR fcntl (2),
 106 .BR mLib (3).
 107 .
 108 .\"--------------------------------------------------------------------------
 109 .SH AUTHOR
 110 .
 111 Mark Wooding, <mdw@distorted.org.uk>
 112 .
 113 .\"----- That's all, folks --------------------------------------------------