halockrun(1)

1halockrun(1)                        hatools                       halockrun(1)
2
3
4

NAME

6       halockrun - Run command while holding exclusive lock on file.
7

SYNOPSIS

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

DESCRIPTION

13       Executes command with args while holding an exclusive lock on the  file
14       lockfile.   If  the  file  is locked by another process, halockrun will
15       wait until the lock becomes available and executes the command then.
16
17       halockrun is often used to avoid cron job overruns.
18
19       halockrun uses operating system locks (POSIX -- fcntl(2)) that makes it
20       very resistant to stale locks.
21
22
23       -a     Async mode.  Starts command in the background.  halockrun itself
24              exits immediately. The exitcode of the executed command is lost.
25
26       -c     Create mode. Creates the  lockfile  if  it  doesn't  exist.  The
27              default behavior is to exit with exitcode if the specified lock‐
28              file doesn't exist.
29
30       -e exitcode
31              Changes the exitcode returned by halockrun on fail  to  exitcode
32              The default value is 99.
33
34
35       -E nexitcode
36              Changes the "lock busy" exitcode returned by halockrun
37
38              The  default  value  for this option is exitcode in non-blocking
39              mode and 1 in testing-, and noop-mode.
40
41
42       -n     Non-blocking mode. Exits immediately with nexitcode if the lock‐
43              file is locked by another process.
44
45       -f     Fork  mode.  The normal behavior of halockrun is to get the lock
46              and call execvp(2) to execute the  command  specified.  If  fork
47              mode, halockrun will do a fork(2) and run the command in its own
48              process. In this case the  parent--halockrun  itself--holds  the
49              lock  on  lockfile.   The  split in two processes opens the risk
50              that the parent halockrun--that holds the lock--dies and  leaves
51              command  unprotected.   To minimize this risk, halockrun ignores
52              the following signals: TERM, HUP, INT,  PIPE,  QUIT,  USR1,  and
53              USR2.
54
55              This option is useful to make sure that the command does not see
56              any difference when running under protection of  halockrun.   In
57              other  words, the fork mode makes sure that the open file handle
58              to lockfile is not visible to command.
59
60              Fork mode has also influence on the -t switch, because that will
61              not  return  the  PID  of  command  but  of the parent halockrun
62              process.
63
64              This option is new  to  version  V0.99.08,  prior  this  version
65              halockrun has always fork(2)ed.  The default was changed because
66              reliability is more important than transparency--in that case.
67
68              If you are in doubt about this option: don't use it.
69
70       -t     Test mode.  Checks if lockfile is currently busy, and prints the
71              PID of the process that holds the lock--if any.  See also -N for
72              that purpose.  The exitcode is 0 if the lock is free  or  nexit‐
73              code  if  it  is  busy.  Any  other error--such as "lockfile not
74              found"--will result in exitcode.
75
76              Regardless of the lock status, halockrun will not run  any  com‐
77              mand.
78
79              When the -t flags is specified the flags -a, -n and -f are mean‐
80              ingless and will be ignored if they are specified.
81
82       -N     No-op mode.  The -N flag is semantically equivalent to:
83
84                 halockrun lockfile /bin/true
85
86              It supplements the -t switch because it blocks. It can  be  com‐
87              bined  with the -n option to change the blocking behavior.  How‐
88              ever, it doesn't print the PID of the the lock holder if  it  is
89              busy.
90
91              The  -N  switch  is more portable and used to synchronize with a
92              running process. The -t switch is used to obtain the PID of  the
93              running process.
94
95              When  the -N flag is specified, the -a and -f flags are meaning‐
96              less and will be ignored if they are specified.
97
98
99       -v[v]  Verbose mode and more verbose mode--almost debug mode.
100
101

RETURN VALUE

103       On success, if command was executed, halockrun returns the return value
104       of command.
105
106       If -t or -N was used, 0 is returned if the lock is not currently busy.
107
108       On  failure--if  lockfile  doesn't  exist  or  command  can't  be  exe‐
109       cuted--halockrun returns the value specified by the -e option.
110
111       On failure to obtain the lock in testing mode or in noop mode (  -t  or
112       -N ) the value specified by the -E option is returned or 1 per default.
113
114       On  failure  to  obtain the lock in non-blocking mode halockrun returns
115       the values specified by the -E option.
116
117

EXAMPLES

119       The most prominent use of halockrun is to protect from cron overrun.  A
120       typical 5 minutes cron job like that
121
122         */5 * * * * /path/script
123
124       would be transformed to
125
126         */5 * * * * halockrun -cn /path/lock /path/script
127
128       This  will  prevent multiple parallel instances of /path/script.  Addi‐
129       tionally, you might use hatimerun to kill script when it  takes  longer
130       then 5 minutes:
131
132         */5 * * * * hatimerun -t 5:00 halockrun -cn /path/lock /path/script
133
134       You can configure hatimerun for many different actions, please refer to
135       the hatimerun(1) manpage for the full documentation.
136
137

COMPATIBILITY

139       halockrun uses fcntl(2) advisory locking. Similar tools that use a dif‐
140       ferent  locking  appraoch like flock(2) of lockf(3) may or may not work
141       together.
142
143       For example, locks placed by flock(2) on  Linux  are  independend  from
144       locks  placed  by  fcntl(2)  on the same system. That means, if you mix
145       those two methods, they don't lock each other.
146

AUTHOR

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