simplfications
[apps/madmutt.git] / legacy / 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@guug.de>
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 madmutt_dotlock \- Lock mail spool files.
24 .SH SYNOPSIS
25 .PP
26 .B madmutt_dotlock 
27 [-t|-f|-u|-d] [-p] [-r \fIretries\fP] \fIfile\fP
28 .SH DESCRIPTION
29 .PP
30 .B madmutt_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 madmutt_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 madmutt_dotlock
46 will break that lock by removing the lockfile.
47 .IP "-u"
48 Unlock.
49 .B madmutt_dotlock 
50 will remove \fIfile\fP.lock.
51 .IP "-d"
52 Delete.
53 .B madmutt_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 madmutt_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 madmutt_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 madmutt_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 madmutt_dotlock
76 generates.
77 .SH SEE ALSO
78 .PP
79 .BR fcntl (2),
80 .BR flock (2),
81 .BR lockfile (1),
82 .BR madmutt (1)
83 .SH DIAGNOSTICS
84 .PP
85 .B madmutt_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 madmutt_dotlock
100 is invoked with the
101 .B -f 
102 command line option, 
103 .B madmutt_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 madmutt_dotlock 
110 has been invoked
111 with the 
112 .B -t
113 command line option.  It means that
114 .B madmutt_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 madmutt_dotlock
121 has been invoked with the
122 .B -t
123 command line option.  It means that
124 .B madmutt_dotlock 
125 is unable to lock \fIfile\fP even with group mail
126 privileges.
127 .SH NOTES
128 .PP
129 .B madmutt_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 madmutt_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 madmutt_dotlock
147 is part of the Madmutt mail user agent package.  It has been
148 created to avoid running Madmutt with group mail privileges.
149 .SH AUTHOR
150 Thomas Roessler <roessler@guug.de>, Nico Golde <nion@madmutt.or>>