isrunning1

Usage

Overview

run runs program, creating a lock file and a write-lock (fcntl(2)) which is held for the lifetime of the process. This allows stop and isrunning to properly test if the program is already running. run does not allow multiple instances of program to be run - this is what it is really for. program can be a full path. You should not try to mix actions of different paths of a program with the same name: eg. /usr/sbin/program and /usr/bin/program. The path may contain only a limited set of characters [A-Za-z0-9./_-].

If run receives the signal SIGTERM it exits immediately disregarding program. If the --robust option is not used then the same behaviour results from SIGHUP, SIGINT, SIGQUIT or SIGPIPE.

If run is used on a program that is already runing, then it will return with the error:
lock failed: Resource temporarily unavailable.

stop stops program. If signal is specified, the signal is transmitted to program and run waits for program to exit. If signal is not specified, SIGTERM is transmitted to program and run waits for program to exit. stop will wait until run has exited before returning. --force forces run to exit immediately, without waiting for program to finish. A -0 means to not send a signal (only makes sense with --force).

killrunning sends a signal to program. If signal is specified, the signal is transmitted to program. run stays around and restarts program if it died as a reaction to the signal if --restart has been given as parameter to run. If signal is not specified, SIGTERM is transmitted to program. This is a dirty hack that should really be incorporated into stop.

isrunning prints out the process id of the instance of run that is the parent of program, as well as the pid of program itself. Also see RETURN VALUE below.

All error messages as well as informational messages are printed to stderr, except that the version is printed to stdout, and isrunning prints pid information to stdout.

These programs use System V IPC to communicate between each other, which must obviously be supported on your system. (All popular Linux distributions should be enabled by default.)

These programs have no idea about any other processes except the ones started by run.

Options

-h, --help

Print help.

-V, --version

Print version.

-r, --restart

Restart program indefinitely if it dies.

--max-restarts num

Maximum number of restarts before exiting, default is infinity. Use only with -r.

--daemon

Fork twice into the background, preventing future death in case of the death of the parent (calling shell). In this case, no errors will be apparent, nor an error resulting from the existing of an already running program.

--robust

Ignore the signals SIGHUP, SIGINT, SIGQUIT and SIGPIPE,

--null

Redirect input and all output to /dev/null.

-d

Same as --daemon, --robust, --null, --restart.

-q, --quiet

Suppress certain explanatory messages unless they are errors.

-i, --interval n.nnn

In the case of --restart minimum interval between restarts. Default is 0.1 seconds - i.e. a maximum of ten restarts per second.

-f, --force

Exit immediately. Do not wait for program to exit.

Examples

Examples:
    run -d pppd nodetach ...
        #(keeps pppd running always)
    stop -INT pppd
        #(stops pppd)
    echo $?
        #(prints the exit status of pppd)
    isrunning pppd
        #(checks if pppd is running)
    run -d netscape
        #(keeps one instance of netscape running for the current uid)

Return value

run returns 127 in the case of any failure, it reports the failure to stderr if it can. Otherwise is returns the return value of program.

isrunning value 0 (success) if program is running, and 1 (failure) otherwise.

stop has the same return value as program if program exited normally (See wait(2)), or 0 if the --force option was used. In case of error, it returns 127, and prints an appropriate message.

Files

/tmp/run/program.run-uid are the lock files, where uid is the uid of the caller. This directory is created with permissions rwx------ for security.