manpagez: man pages & more
man halockrun(1)
Home | html | info | man
halockrun(1)                        hatools                       halockrun(1)




NAME

       halockrun - Run command while holding exclusive lock on file.


SYNOPSIS

       halockrun [-ancfv] [-e exitcode] [-E nexitcode] lockfile command [args]
       halockrun -t|-N [-nc] [-e exitcode] [-E nexitcode] lockfile


DESCRIPTION

       Executes command with args while holding an exclusive lock on the  file
       lockfile.   If  the  file  is locked by another process, halockrun will
       wait until the lock becomes available and executes the command then.

       halockrun is often used to avoid cron job overruns.

       halockrun uses operating system locks (POSIX -- fcntl(2)) that makes it
       very resistant to stale locks.


       -a     Async mode.  Starts command in the background.  halockrun itself
              exits immediately. The exitcode of the executed command is lost.

       -c     Create  mode.  Creates  the  lockfile  if  it doesn't exist. The
              default behavior is to exit with exitcode if the specified lock-
              file doesn't exist.

       -e exitcode
              Changes  the  exitcode returned by halockrun on fail to exitcode
              The default value is 99.


       -E nexitcode
              Changes the "lock busy" exitcode returned by halockrun

              The default value for this option is  exitcode  in  non-blocking
              mode and 1 in testing-, and noop-mode.


       -n     Non-blocking mode. Exits immediately with nexitcode if the lock-
              file is locked by another process.

       -f     Fork mode.  The normal behavior of halockrun is to get the  lock
              and  call  execvp(2)  to  execute the command specified. If fork
              mode, halockrun will do a fork(2) and run the command in its own
              process.  In  this  case the parent--halockrun itself--holds the
              lock on lockfile.  The split in two  processes  opens  the  risk
              that  the parent halockrun--that holds the lock--dies and leaves
              command unprotected.  To minimize this risk,  halockrun  ignores
              the  following  signals:  TERM,  HUP, INT, PIPE, QUIT, USR1, and
              USR2.

              This option is useful to make sure that the command does not see
              any  difference  when running under protection of halockrun.  In
              other words, the fork mode makes sure that the open file  handle
              to lockfile is not visible to command.

              Fork mode has also influence on the -t switch, because that will
              not return the PID  of  command  but  of  the  parent  halockrun
              process.

              This  option  is  new  to  version  V0.99.08, prior this version
              halockrun has always fork(2)ed.  The default was changed because
              reliability is more important than transparency--in that case.

              If you are in doubt about this option: don't use it.

       -t     Test mode.  Checks if lockfile is currently busy, and prints the
              PID of the process that holds the lock--if any.  See also -N for
              that  purpose.   The exitcode is 0 if the lock is free or nexit-
              code if it is busy.  Any  other  error--such  as  "lockfile  not
              found"--will result in exitcode.

              Regardless  of  the lock status, halockrun will not run any com-
              mand.

              When the -t flags is specified the flags -a, -n and -f are mean-
              ingless and will be ignored if they are specified.

       -N     No-op mode.  The -N flag is semantically equivalent to:

                 halockrun lockfile /bin/true

              It  supplements  the -t switch because it blocks. It can be com-
              bined with the -n option to change the blocking behavior.   How-
              ever,  it  doesn't print the PID of the the lock holder if it is
              busy.

              The -N switch is more portable and used to  synchronize  with  a
              running  process. The -t switch is used to obtain the PID of the
              running process.

              When the -N flag is specified, the -a and -f flags are  meaning-
              less and will be ignored if they are specified.


       -v[v]  Verbose mode and more verbose mode--almost debug mode.



RETURN VALUE

       On success, if command was executed, halockrun returns the return value
       of command.

       If -t or -N was used, 0 is returned if the lock is not currently  busy.

       On  failure--if  lockfile  doesn't  exist  or  command  can't  be  exe-
       cuted--halockrun returns the value specified by the -e option.

       On failure to obtain the lock in testing mode or in noop mode (  -t  or
       -N ) the value specified by the -E option is returned or 1 per default.

       On failure to obtain the lock in non-blocking  mode  halockrun  returns
       the values specified by the -E option.



EXAMPLES

       The  most prominent use of halockrun is to protect from cron overrun. A
       typical 5 minutes cron job like that

         */5 * * * * /path/script

       would be transformed to

         */5 * * * * halockrun -cn /path/lock /path/script

       This will prevent multiple parallel instances of  /path/script.   Addi-
       tionally,  you  might use hatimerun to kill script when it takes longer
       then 5 minutes:

         */5 * * * * hatimerun -t 5:00 halockrun -cn /path/lock /path/script

       You can configure hatimerun for many different actions, please refer to
       the hatimerun(1) manpage for the full documentation.



COMPATIBILITY

       halockrun uses fcntl(2) advisory locking. Similar tools that use a dif-
       ferent locking appraoch like flock(2) of lockf(3) may or may  not  work
       together.

       For  example,  locks  placed  by flock(2) on Linux are independend from
       locks placed by fcntl(2) on the same system. That  means,  if  you  mix
       those two methods, they don't lock each other.


AUTHOR

       Copyright (c) 2001,2003,2005-2010 by Markus Winand <mws@fatalmind.com>


SEE ALSO

       hatimerun(1)

       http://www.fatalmind.com/software/hatools/



V2.14                             2010-03-16                      halockrun(1)

hatools 2.14 - Generated Tue Mar 16 09:15:16 CDT 2010
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.