jcs.org
mutt stable branch with some hacks
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
23mutt_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
31implements the traditional mail spool file locking method:
32To lock \fIfile\fP, a file named \fIfile\fP.lock is
33created. The program operates with group mail privileges
34if necessary.
35.SH OPTIONS
36.PP
37.IP "-t"
38Just try.
39.B mutt_dotlock
40won't actually lock a file, but inform the invoking
41process if it's at all possible to lock \fIfile\fP.
42.IP "-f"
43Force the lock. If another process holds a lock on
44\fIfile\fP longer than a certain amount of time,
45.B mutt_dotlock
46will break that lock by removing the lockfile.
47.IP "-u"
48Unlock.
49.B mutt_dotlock
50will remove \fIfile\fP.lock.
51.IP "-d"
52Delete.
53.B mutt_dotlock
54will lock \fIfile\fP, remove it if it has length 0, and afterwards
55remove \fIfile\fP.lock.
56.IP "-p"
57Use privileges. If given this option,
58.B mutt_dotlock
59will operate with group mail privileges when creating and
60deleting lock files.
61.IP "-r \fIretries\fP"
62This command line option tells
63.B mutt_dotlock
64to try locking
65\fIretries\fP times before giving up or (if invoked with
66the
67.B -f
68command line option) break a lock. The default value is 5.
69.B mutt_dotlock
70waits one second between successive locking attempts.
71.SH FILES
72.PP
73.IP "\fIfile\fP.lock"
74The lock file
75.B mutt_dotlock
76generates.
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
86gives all diagnostics in its return values:
87.TP
88.B "0 \- DL_EX_OK"
89The program was successful.
90.TP
91.B "1 \- DL_EX_ERROR"
92An unspecified error such as bad command line parameters,
93lack of system memory and the like has occurred.
94.TP
95.B "3 \- DL_EX_EXIST"
96The
97user wants to lock a file which has been locked by
98another process already. If
99.B mutt_dotlock
100is invoked with the
101.B -f
102command line option,
103.B mutt_dotlock
104won't generate this error, but break other processes'
105locks.
106.TP
107.B "4 \- DL_EX_NEED_RPIVS"
108This return value only occurs if
109.B mutt_dotlock
110has been invoked
111with the
112.B -t
113command line option. It means that
114.B mutt_dotlock
115will have to use its group mail privileges to lock
116\fIfile\fP.
117.TP
118.B "5 \- DL_EX_IMPOSSIBLE"
119This return value only occurs if
120.B mutt_dotlock
121has been invoked with the
122.B -t
123command line option. It means that
124.B mutt_dotlock
125is unable to lock \fIfile\fP even with group mail
126privileges.
127.SH NOTES
128.PP
129.B mutt_dotlock
130tries to implement an NFS-safe dotlocking method which was
131borrowed from
132.B lockfile
133(1).
134.PP
135If the user can't open \fIfile\fP for reading with his
136normal privileges,
137.B mutt_dotlock
138will return the
139.B DL_EX_ERROR
140exit value to avoid certain attacks against other users'
141spool files. The code carefully avoids race conditions
142when checking permissions; for details of all this see the
143comments in dotlock.c.
144.SH HISTORY
145.PP
146.B mutt_dotlock
147is part of the Mutt mail user agent package. It has been
148created to avoid running mutt with group mail privileges.
149.SH AUTHOR
150Thomas Roessler <roessler@does-not-exist.org>