+++ /dev/null
-.\" -*-nroff-*-
-.\"
-.\"
-.\" Copyright (C) 1996-8 Michael R. Elkins <me@cs.hmc.edu>
-.\" Copyright (C) 1998-9 Thomas Roessler <roessler@does-not-exist.org>
-.\"
-.\" This program is free software; you can redistribute it and/or modify
-.\" it under the terms of the GNU General Public License as published by
-.\" the Free Software Foundation; either version 2 of the License, or
-.\" (at your option) any later version.
-.\"
-.\" This program is distributed in the hope that it will be useful,
-.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-.\" GNU General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public License
-.\" along with this program; if not, write to the Free Software
-.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-.\"
-.TH dotlock 1 "AUGUST 1999" Unix "User Manuals"
-.SH NAME
-mutt_dotlock \- Lock mail spool files.
-.SH SYNOPSIS
-.PP
-.B mutt_dotlock
-[\-t|\-f|\-u|\-d] [\-p] [\-r \fIretries\fP] \fIfile\fP
-.SH DESCRIPTION
-.PP
-.B mutt_dotlock
-implements the traditional mail spool file locking method:
-To lock \fIfile\fP, a file named \fIfile\fP.lock is
-created. The program operates with group mail privileges
-if necessary.
-.SH OPTIONS
-.PP
-.IP "-t"
-Just try.
-.B mutt_dotlock
-won't actually lock a file, but inform the invoking
-process if it's at all possible to lock \fIfile\fP.
-.IP "-f"
-Force the lock. If another process holds a lock on
-\fIfile\fP longer than a certain amount of time,
-.B mutt_dotlock
-will break that lock by removing the lockfile.
-.IP "-u"
-Unlock.
-.B mutt_dotlock
-will remove \fIfile\fP.lock.
-.IP "-d"
-Delete.
-.B mutt_dotlock
-will lock \fIfile\fP, remove it if it has length 0, and afterwards
-remove \fIfile\fP.lock.
-.IP "-p"
-Use privileges. If given this option,
-.B mutt_dotlock
-will operate with group mail privileges when creating and
-deleting lock files.
-.IP "-r \fIretries\fP"
-This command line option tells
-.B mutt_dotlock
-to try locking
-\fIretries\fP times before giving up or (if invoked with
-the
-.B -f
-command line option) break a lock. The default value is 5.
-.B mutt_dotlock
-waits one second between successive locking attempts.
-.SH FILES
-.PP
-.IP "\fIfile\fP.lock"
-The lock file
-.B mutt_dotlock
-generates.
-.SH SEE ALSO
-.PP
-.BR fcntl (2),
-.BR flock (2),
-.BR lockfile (1),
-.BR mutt (1)
-.SH DIAGNOSTICS
-.PP
-.B mutt_dotlock
-gives all diagnostics in its return values:
-.TP
-.B "0 \- DL_EX_OK"
-The program was successful.
-.TP
-.B "1 \- DL_EX_ERROR"
-An unspecified error such as bad command line parameters,
-lack of system memory and the like has occurred.
-.TP
-.B "3 \- DL_EX_EXIST"
-The
-user wants to lock a file which has been locked by
-another process already. If
-.B mutt_dotlock
-is invoked with the
-.B -f
-command line option,
-.B mutt_dotlock
-won't generate this error, but break other processes'
-locks.
-.TP
-.B "4 \- DL_EX_NEED_RPIVS"
-This return value only occurs if
-.B mutt_dotlock
-has been invoked
-with the
-.B -t
-command line option. It means that
-.B mutt_dotlock
-will have to use its group mail privileges to lock
-\fIfile\fP.
-.TP
-.B "5 \- DL_EX_IMPOSSIBLE"
-This return value only occurs if
-.B mutt_dotlock
-has been invoked with the
-.B -t
-command line option. It means that
-.B mutt_dotlock
-is unable to lock \fIfile\fP even with group mail
-privileges.
-.SH NOTES
-.PP
-.B mutt_dotlock
-tries to implement an NFS-safe dotlocking method which was
-borrowed from
-.B lockfile
-(1).
-.PP
-If the user can't open \fIfile\fP for reading with his
-normal privileges,
-.B mutt_dotlock
-will return the
-.B DL_EX_ERROR
-exit value to avoid certain attacks against other users'
-spool files. The code carefully avoids race conditions
-when checking permissions; for details of all this see the
-comments in dotlock.c.
-.SH HISTORY
-.PP
-.B mutt_dotlock
-is part of the Mutt mail user agent package. It has been
-created to avoid running mutt with group mail privileges.
-.SH AUTHOR
-Thomas Roessler <roessler@does-not-exist.org>
projects / asd-repo.git / blobdiff