doc/dotlock.man

   1 .\" -*-nroff-*-
   2 .\"
   3 .\"
   4 .\"     Copyright (C) 1996-8 Michael R. Elkins <me@cs.hmc.edu>
   5 .\"     Copyright (C) 1998-9 Thomas Roessler <roessler@does-not-exist.org>
   6 .\"
   7 .\"     This program is free software; you can redistribute it and/or modify
   8 .\"     it under the terms of the GNU General Public License as published by
   9 .\"     the Free Software Foundation; either version 2 of the License, or
  10 .\"     (at your option) any later version.
  11 .\"
  12 .\"     This program is distributed in the hope that it will be useful,
  13 .\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 .\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 .\"     GNU General Public License for more details.
  16 .\"
  17 .\"     You should have received a copy of the GNU General Public License
  18 .\"     along with this program; if not, write to the Free Software
  19 .\"     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  20 .\"
  21 .TH dotlock 1 "AUGUST 1999" Unix "User Manuals"
  22 .SH NAME
  23 mutt_dotlock \- Lock mail spool files.
  24 .SH SYNOPSIS
  25 .PP
  26 .B mutt_dotlock
  27 [-t|-f|-u|-d] [-p] [-r \fIretries\fP] \fIfile\fP
  28 .SH DESCRIPTION
  29 .PP
  30 .B mutt_dotlock
  31 implements the traditional mail spool file locking method:
  32 To lock \fIfile\fP, a file named \fIfile\fP.lock is
  33 created. The program operates with group mail privileges
  34 if necessary.
  35 .SH OPTIONS
  36 .PP
  37 .IP "-t"
  38 Just try.
  39 .B mutt_dotlock
  40 won't actually lock a file, but inform the invoking
  41 process if it's at all possible to lock \fIfile\fP.
  42 .IP "-f"
  43 Force the lock.  If another process holds a lock on
  44 \fIfile\fP longer than a certain amount of time,
  45 .B mutt_dotlock
  46 will break that lock by removing the lockfile.
  47 .IP "-u"
  48 Unlock.
  49 .B mutt_dotlock
  50 will remove \fIfile\fP.lock.
  51 .IP "-d"
  52 Delete.
  53 .B mutt_dotlock
  54 will lock \fIfile\fP, remove it if it has length 0, and afterwards
  55 remove \fIfile\fP.lock.
  56 .IP "-p"
  57 Use privileges.  If given this option,
  58 .B mutt_dotlock
  59 will operate with group mail privileges when creating and
  60 deleting lock files.
  61 .IP "-r \fIretries\fP"
  62 This command line option tells
  63 .B mutt_dotlock
  64 to try locking
  65 \fIretries\fP times before giving up or (if invoked with
  66 the
  67 .B -f
  68 command line option) break a lock.  The default value is 5.
  69 .B mutt_dotlock
  70 waits one second between successive locking attempts.
  71 .SH FILES
  72 .PP
  73 .IP "\fIfile\fP.lock"
  74 The lock file
  75 .B mutt_dotlock
  76 generates.
  77 .SH SEE ALSO
  78 .PP
  79 .BR fcntl (2),
  80 .BR flock (2),
  81 .BR lockfile (1),
  82 .BR mutt (1)
  83 .SH DIAGNOSTICS
  84 .PP
  85 .B mutt_dotlock
  86 gives all diagnostics in its return values:
  87 .TP
  88 .B "0 \- DL_EX_OK"
  89 The program was successful.
  90 .TP
  91 .B "1 \- DL_EX_ERROR"
  92 An unspecified error such as bad command line parameters,
  93 lack of system memory and the like has occured.
  94 .TP
  95 .B "3 \- DL_EX_EXIST"
  96 The
  97 user wants to lock a file which has been locked by
  98 another process already.  If
  99 .B mutt_dotlock
 100 is invoked with the
 101 .B -f
 102 command line option,
 103 .B mutt_dotlock
 104 won't generate this error, but break other processes'
 105 locks.
 106 .TP
 107 .B "4 \- DL_EX_NEED_RPIVS"
 108 This return value only occurs if
 109 .B mutt_dotlock
 110 has been invoked
 111 with the
 112 .B -t
 113 command line option.  It means that
 114 .B mutt_dotlock
 115 will have to use its group mail privileges to lock
 116 \fIfile\fP.
 117 .TP
 118 .B "5 \- DL_EX_IMPOSSIBLE"
 119 This return value only occurs if
 120 .B mutt_dotlock
 121 has been invoked with the
 122 .B -t
 123 command line option.  It means that
 124 .B mutt_dotlock
 125 is unable to lock \fIfile\fP even with group mail
 126 privileges.
 127 .SH NOTES
 128 .PP
 129 .B mutt_dotlock
 130 tries to implement an NFS-safe dotlocking method which was
 131 borrowed from
 132 .B lockfile
 133 (1).
 134 .PP
 135 If the user can't open \fIfile\fP for reading with his
 136 normal privileges,
 137 .B mutt_dotlock
 138 will return the
 139 .B DL_EX_ERROR
 140 exit value to avoid certain attacks against other users'
 141 spool files. The code carefully avoids race conditions
 142 when checking permissions; for details of all this see the
 143 comments in dotlock.c.
 144 .SH HISTORY
 145 .PP
 146 .B mutt_dotlock
 147 is part of the Mutt mail user agent package.  It has been
 148 created to avoid running mutt with group mail privileges.
 149 .SH AUTHOR
 150 Thomas Roessler <roessler@does-not-exist.org>