NAME

       postpone - schedules a command to be executed later when a lockfile disappears

SYNOPSIS

       postpone [-dfv] [-lwLoO FILE] command args ...

DESCRIPTION

       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 update-menus 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, postpone 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.

       On startup, postpone will look if any of the lock files given with --wait exists. If  not,
       it  will  run  command  immediately  in foreground. Otherwise, it will fork to background,
       waiting for the lock file(s) to disappear. At the same time, the --lock file is created to
       indicate  to other postpone instances that command is already scheduled for execution; the
       other instances will exit without further action.

       Additionally, --extra-lock will be acquired just before the  execution  of  command,  this
       allows the serialization of several (different) background jobs.

       All lockfiles are optional. See below for examples.

OPTIONS

       -w FILE or --wait FILE
              Wait  for  FILE before running command. Can be given several times.  This activates
              the main feature of postpone -- delay execution until some other  task  has  exited
              (specifically, released its fcntl() lock).

       -l FILE or --lock FILE
              Creates  lockfile  FILE.  If  postpone  is called again with the same FILE, it will
              exit, assuming the task is already postponed. Make sure that the (effects  of  the)
              commands are the same for the same lockfile.

       -L FILE or --extra-lock FILE
              Before  running  command, acquire lock on FILE. Use this to serialize several (most
              likely different) postponed commands.

       -d or --debian
              Equivalent to --wait /var/lib/dpkg/lock  --extra-lock  /var/lib/dpkg/postpone.lock.
              Meant for use in maintainer scripts of Debian packages, will wait for dpkg and apt-
              get to exit and serialize the postponed commands.

       -o FILE or --output FILE
              Redirect stdout and stderr output to FILE when running in  background.   (Discarded
              otherwise.) If FILE ends with "XXXXXX", mkstemp is used.

       -O FILE or --all-output FILE
              Like --output, but always redirect stdout and stderr output to FILE.

       -f or --foreground
              Do not detach while waiting for locks.

       -v or --verbose
              Verbose output. Repeat for debugging output.

       --help Print options summary and exit.

       --version
              Print version information and exit.

       --version-string
              Print version information in machine readable form and exit.

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

FILES

       /var/lib/dpkg/lock
              Dpkg's default lockfile.

       /var/lib/dpkg/postpone.lock
              Default extra lockfile when running with --debian.

BUGS

       Postpone  currently  only uses fcntl() to acquire locks on --wait, usage with applications
       using flock() will fail  gracefully.  (The  command  will  run  immediately.)  --lock  and
       --extra-lock use flock().

COMPATIBILITY

       For compatibility, using unknown options does not abort the program.  Applications can use
       --version-string if they need to compare the postpone version number.

SEE ALSO

       update-menus(1), fcntl(2), flock(2), mkstemp(3), dpkg(1).

COPYRIGHT

       Copyright (C) 2007  Christoph Berg

       Based on code from:
       Debian menu system -- update-menus
       update-menus/update-menus.cc

       Copyright (C) 1996-2003  Joost Witteveen
       Copyright (C) 2002-2004  Bill Allombert and Morten Brix Pedersen

       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.

                                          June 9th 2007                               POSTPONE(1)