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)