.TH POSTPONE 1 "June 9th 2007"
.SH NAME
postpone \- schedules a command to be executed later when a lockfile disappears
.SH SYNOPSIS
.B "\fBpostpone\fP [\fB\-dfv\fP] [\fB\-lwLoO\fP \fIFILE\fP] \fIcommand args ...\fP"
.SH DESCRIPTION
.B Postpone
schedules a command to be executed later when a lockfile disappears. Intended
usage is when a command is executed possibly multiple times, but running once
is sufficient. This happens in maintainer scripts of Debian packages, for
example, the menu system will need to run \fBupdate\-menus\fP every time a menu
file is installed or removed, but if several packages are processed at once, a
single update\-menus run at the end is sufficient. In fact, \fBpostpone\fP is a
generalization of similar code found in update\-menus that is already able to
postpone itself. Another prominent use case are TeX packages that need to
rebuild several indices.
.PP
On startup, \fBpostpone\fP will look if any of the lock files given with
\fB\-\-wait\fP exists. If not, it will run \fIcommand\fP immediately in
foreground. Otherwise, it will fork to background, waiting for the lock file(s)
to disappear. At the same time, the \fB\-\-lock\fP file is created to indicate
to other \fBpostpone\fP instances that \fIcommand\fP is already scheduled for
execution; the other instances will exit without further action.
.PP
Additionally, \fB\-\-extra\-lock\fP will be acquired just before the execution
of \fIcommand\fP, this allows the serialization of several (different)
background jobs.
.PP
All lockfiles are optional. See below for examples.
.SH OPTIONS
.IP "\-w \fIFILE\fP or \-\-wait \fIFILE\fP"
Wait for \fIFILE\fP before running \fIcommand\fP. Can be given several times.
This activates the main feature of
.B postpone
-- delay execution until some other task has exited (specifically, released its
fcntl() lock).
.IP "\-l \fIFILE\fP or \-\-lock \fIFILE\fP"
Creates lockfile \fIFILE\fP. If
.B postpone
is called again with the same \fIFILE\fP, it will exit, assuming the task is
already postponed. Make sure that the (effects of the) commands are the same
for the same lockfile.
.IP "\-L \fIFILE\fP or \-\-extra\-lock \fIFILE\fP"
Before running \fIcommand\fP, acquire lock on \fIFILE\fP. Use this to serialize
several (most likely different) postponed commands.
.IP "\-d or \-\-debian"
Equivalent to \fB\-\-wait /var/lib/dpkg/lock \-\-extra\-lock
/var/lib/dpkg/postpone.lock\fP. Meant for use in maintainer scripts of Debian
packages, will wait for dpkg and apt-get to exit and serialize the postponed
commands.
.IP "\-o \fIFILE\fP or \-\-output \fIFILE\fP"
Redirect stdout and stderr output to \fIFILE\fP when running in background.
(Discarded otherwise.) If \fIFILE\fP ends with "XXXXXX", mkstemp is used.
.IP "\-O \fIFILE\fP or \-\-all\-output \fIFILE\fP"
Like \fB\-\-output\fP, but always redirect stdout and stderr output to
\fIFILE\fP.
.IP "\-f or \-\-foreground"
Do not detach while waiting for locks.
.IP "\-v or \-\-verbose"
Verbose output. Repeat for debugging output.
.IP "\-\-help"
Print options summary and exit.
.IP "\-\-version"
Print version information and exit.
.IP "\-\-version\-string"
Print version information in machine readable form and exit.
.SH EXAMPLES
Example usage in a texlive postinst maintainer script:

    if [ \-x /usr/bin/postpone ] ; then
        postpone \-\-verbose \-\-lock /var/run/updmap\-sys.lock \-\-debian \\
            \-\-all\-output /tmp/updmap.XXXXXXXX \\
            updmap\-sys
    else
        updmap\-sys
    fi
.SH FILES
.IP /var/lib/dpkg/lock
Dpkg's default lockfile.
.IP /var/lib/dpkg/postpone.lock
Default extra lockfile when running with \fB\-\-debian\fP.
.SH BUGS
.B Postpone
currently only uses fcntl() to acquire locks on \fB\-\-wait\fP, usage with
applications using flock() will fail gracefully. (The command will run
immediately.) \fB\-\-lock\fP and \fB\-\-extra\-lock\fP use flock().
.SH COMPATIBILITY
For compatibility, using unknown options does not abort the program.
Applications can use \fB\-\-version\-string\fP if they need to compare the
\fBpostpone\fP version number.
.SH "SEE ALSO"
update\-menus(1),
fcntl(2),
flock(2),
mkstemp(3),
dpkg(1).
.SH COPYRIGHT
Copyright (C) 2007  Christoph Berg
.PP
Based on code from:
.br
Debian menu system -- update\-menus
.br
update\-menus/update\-menus.cc
.PP
Copyright (C) 1996-2003  Joost Witteveen
.br
Copyright (C) 2002-2004  Bill Allombert and Morten Brix Pedersen
.PP
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.
.PP
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.