Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 285 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man1/lockfile.1 b/upstream/debian-unstable/man1/lockfile.1
new file mode 100644
index 00000000..952539fc
--- /dev/null
+++ b/upstream/debian-unstable/man1/lockfile.1
@@ -0,0 +1,285 @@
+.\"if n .pl +(135i-\n(.pu)
+.de Id
+.ds Rv \\$3
+.ds Dt \\$4
+..
+.Id $Id$
+.TH LOCKFILE 1 \*(Dt BuGless
+.rn SH Sh
+.de SH
+.br
+.ne 11
+.Sh "\\$1"
+..
+.rn SS Ss
+.de SS
+.br
+.ne 10
+.Ss "\\$1"
+..
+.rn TP Tp
+.de TP
+.br
+.ne 9
+.Tp \\$1
+..
+.rn RS Rs
+.de RS
+.na
+.nf
+.Rs
+..
+.rn RE Re
+.de RE
+.Re
+.fi
+.ad
+..
+.de Sx
+.PP
+.ne \\$1
+.RS
+..
+.de Ex
+.RE
+.PP
+..
+.na
+.SH NAME
+lockfile \- conditional semaphore-file creator
+.SH SYNOPSIS
+.B lockfile
+.I "\fB\-\fPsleeptime"
+|
+.I "\fB\-r \fPretries"
+|
+.if n .ti +0.5i
+.I "\fB\-l \fPlocktimeout"
+|
+.I "\fB\-s \fPsuspend"
+|
+.B "\-!"
+|
+.B "\-ml"
+|
+.B "\-mu"
+|
+.I filename
+\&.\|.\|.
+.ad
+.SH DESCRIPTION
+.B lockfile
+can be used to create one or more
+.I semaphore
+.IR files .
+If lockfile can't create all the specified files (in the specified order),
+it waits
+.I sleeptime
+(defaults to 8) seconds and retries the last file that didn't
+succeed.  You can specify the number of
+.I retries
+to do until failure is returned.
+If the number of
+.I retries
+is \-1 (default, i.e.,
+.BR \-r\-1 )
+lockfile will retry forever.
+.PP
+If the number of
+.I retries
+expires before all files have been created, lockfile returns failure and
+removes all the files it created up till that point.
+.PP
+Using lockfile as the condition of a loop in a shell script can be done
+easily by using the
+.B \-!
+flag to invert the exit status.  To prevent infinite loops, failures
+for any reason other than the lockfile already existing are not
+inverted to success but rather are still returned as failures.
+.PP
+All flags can be specified anywhere on the command line, they will be
+processed when encountered.  The command line is simply parsed from
+left to right.
+.PP
+All files created by lockfile will be read-only, and therefore
+will have to be removed with
+.B rm
+.BR \-f .
+.PP
+If you specify a
+.I locktimeout
+then a lockfile will be removed by force after locktimeout seconds have
+passed since the lockfile was last modified/created (most likely by some
+other program that unexpectedly died a long time ago, and hence could not clean
+up any leftover lockfiles).  Lockfile is clock skew immune.  After a lockfile
+has been removed by force, a suspension of
+.I suspend
+seconds (defaults to 16) is taken into account, in order to prevent
+the inadvertent immediate removal of any newly created lockfile by another
+program (compare
+.BR SUSPEND
+in
+.BR procmail (1)).
+.SS "Mailbox locks"
+If the permissions on the system mail spool directory allow it, or if lockfile
+is suitably setgid, it will be able to lock and unlock your system mailbox by
+using the options
+.B "\-ml"
+and
+.B "\-mu"
+respectively.
+.SH EXAMPLES
+Suppose you want to make sure that access to the file "important" is
+serialised, i.e., no more than one program or shell script should be allowed
+to access it.  For simplicity's sake, let's suppose that it is a shell
+script.  In this case you could solve it like this:
+.RS
+\&.\|.\|.
+lockfile important.lock
+\&.\|.\|.
+access_"important"_to_your_hearts_content
+\&.\|.\|.
+rm \-f important.lock
+\&.\|.\|.
+.RE
+Now if all the scripts that access "important" follow this guideline, you
+will be assured that at most one script will be executing between the
+`lockfile' and the `rm' commands.
+.SH ENVIRONMENT
+.TP 2.3i
+.B LOGNAME
+used as a hint to determine the invoker's loginname
+.SH FILES
+.TP 2.3i
+.B /etc/passwd
+to verify and/or correct the invoker's loginname (and to find out his HOME
+directory, if needed)
+.TP
+.B /var/mail/$LOGNAME.lock
+lockfile for the system mailbox, the environment variables present in here
+will not be taken from the environment, but will be determined by looking
+in /etc/passwd
+.SH "SEE ALSO"
+.na
+.nh
+.BR rm (1),
+.BR mail (1),
+.BR sendmail (8),
+.BR procmail (1)
+.hy
+.ad
+.SH DIAGNOSTICS
+.TP 2.3i
+Filename too long, .\|.\|.
+Use shorter filenames.
+.TP
+Forced unlock denied on "x"
+No write permission in the directory where lockfile "x" resides, or more than
+one lockfile trying to force a lock at exactly the same time.
+.TP
+Forcing lock on "x"
+Lockfile "x" is going to be removed by force because of a timeout
+(compare
+.BR LOCKTIMEOUT
+in
+.BR procmail (1)).
+.TP
+Out of memory, .\|.\|.
+The system is out of swap space.
+.TP
+Signal received, .\|.\|.
+Lockfile will remove anything it created till now and terminate.
+.TP
+Sorry, .\|.\|.
+The
+.I retries
+limit has been reached.
+.TP
+Truncating "x" and retrying lock
+"x" does not seem to be a valid filename.
+.TP
+Try praying, .\|.\|.
+Missing subdirectories or insufficient privileges.
+.SH BUGS
+Definitely less than one.
+.SH WARNINGS
+The behavior of the
+.B \-!
+flag, while useful, is not necessarily intuitive or consistent.  When
+testing lockfile's return value, shell script writers should consider
+carefully whether they want to use the
+.B \-!
+flag, simply reverse the test, or do a switch on the exact exitcode.
+In general, the
+.B \-!
+flag should only be used when lockfile is the conditional of a loop.
+.SH MISCELLANEOUS
+Lockfile is NFS-resistant and eight-bit clean.
+.SH NOTES
+Calling up lockfile with the \-h or \-? options will cause
+it to display a command-line help page.  Calling it up with the \-v
+option will cause it to display its version information.
+.PP
+Multiple
+.B \-!
+flags will toggle the return status.
+.PP
+Since flags can occur anywhere on the command line, any filename starting
+with a '-' has to be preceded by './'.
+.PP
+The number of
+.I retries
+will not be reset when any following file is being created (i.e., they are
+simply used up).  It can, however, be reset by specifying
+.RI \-r newretries
+after every file on the command line.
+.PP
+Although files with any name can be used as lockfiles, it is common practice
+to use the extension `.lock' to lock mailfolders (it is appended to the
+mailfolder name).  In case one does not want to have to worry about too long
+filenames and does not have to conform to any other lockfilename convention,
+then an excellent way to generate a lockfilename corresponding to some already
+existing file is by taking the prefix `lock.' and appending the i-node number
+of the file which is to be locked.
+.Sh SOURCE
+This program is part of the
+.I procmail mail-processing-package
+(v3.24) available at http://www.procmail.org/ or
+ftp.procmail.org in
+.BR pub/procmail/ .
+.Sh MAILINGLIST
+There exists a mailinglist for questions relating to any program in the
+procmail package:
+.RS
+<procmail-users@procmail.org>
+.RS
+for submitting questions/answers.
+.RE
+<procmail-users-request@procmail.org>
+.RS
+for subscription requests.
+.RE
+.PP
+.RE
+If you would like to stay informed about new versions and official patches send
+a subscription request to
+.RS
+procmail-announce-request@procmail.org
+.RE
+(this is a readonly list).
+.SH AUTHORS
+Stephen R. van den Berg
+.RS
+<srb@cuci.nl>
+.RE
+.\".if n .pl -(\n(.tu-1i)
+.rm SH
+.rn Sh SH
+.rm SS
+.rn Ss SS
+.rm TP
+.rn Tp TP
+.rm RS
+.rn Rs RS
+.rm RE
+.rn Re RE