20.8. Init Script Functions

Each conforming init script shall execute the commands in the file /lib/lsb/init-functions in the current environment (see shell special built-in command dot). This file shall cause the following shell script commands to be defined in an unspecified manner.

Note: This can be done either by adding a directory to the PATH variable which defines these commands, or by defining shell aliases or functions.

Although the commands made available via this mechanism need not be conforming applications in their own right, applications that use them should only depend on features described in this specification.

Conforming scripts shall not specify the "exit on error" option (i.e. set -e) when sourcing this file, or calling any of the commands thus made available.

The start_daemon, killproc and pidofproc functions shall use the following algorithm for determining the status and the process identifiers of the specified program.

  1. If the -p pidfile option is specified, and the named pidfile exists, a single line at the start of the pidfile shall be read. If this line contains one or more numeric values, separated by spaces, these values shall be used. If the -p pidfile option is specified and the named pidfile does not exist, the functions shall assume that the daemon is not running.

  2. Otherwise, /var/run/basename.pid shall be read in a similar fashion. If this contains one or more numeric values on the first line, these values shall be used. Optionally, implementations may use unspecified additional methods to locate the process identifiers required.

The method used to determine the status is implementation defined, but should allow for non-binary programs.

Note: Commonly used methods check either for the existence of the /proc/pid directory or use /proc/pid/exe and /proc/pid/cmdline. Relying only on /proc/pid/exe is discouraged since this specification does not specify the existence of, or semantics for, /proc. Additionally, using /proc/pid/exe may result in a not-running status for daemons that are written in a script language.

Conforming implementations may use other mechanisms besides those based on pidfiles, unless the -p pidfile option has been used. Conforming applications should not rely on such mechanisms and should always use a pidfile. When a program is stopped, it should delete its pidfile. Multiple process identifiers shall be separated by a single space in the pidfile and in the output of pidofproc.

start_daemon [-f] [-n nicelevel] [-p pidfile] pathname [args...]

runs the specified program as a daemon. The start_daemon function shall check if the program is already running using the algorithm given above. If so, it shall not start another copy of the daemon unless the -f option is given. The -n option specifies a nice level. See nice. start_daemon shall return the LSB defined exit status codes. It shall return 0 if the program has been successfully started or is running and not 0 otherwise.

killproc [-p pidfile] pathname [signal]

The killproc function shall stop the specified program. The program is found using the algorithm given above. If a signal is specified, using the -signal_name or -signal_number syntaxes as specified by the kill command, the program is sent that signal. Otherwise, a SIGTERM followed by a SIGKILL after an unspecified number of seconds shall be sent. If a program has been terminated, the pidfile should be removed if the terminated process has not already done so. The killproc function shall return the LSB defined exit status codes. If called without a signal, it shall return 0 if the program has been stopped or is not running and not 0 otherwise. If a signal is given, it shall return 0 only if the program is running.

pidofproc [-p pidfile] pathname

The pidofproc function shall return one or more process identifiers for a particular daemon using the algorithm given above. Only process identifiers of running processes should be returned. Multiple process identifiers shall be separated by a single space.

Note: A process may exit between pidofproc discovering its identity and the caller of pidofproc being able to act on that identity. As a result, no test assertion can be made that the process identifiers returned by pidofproc shall be running processes.

The pidofproc function shall return the LSB defined exit status codes for "status". It shall return 0 if the program is running and not 0 otherwise.

log_success_msg message

The log_success_msg function shall cause the system to write a success message to an unspecified log file. The format of the message is unspecified. The log_success_msg function may also write a message to the standard output.

Note: The message should be relatively short; no more than 60 characters is highly desirable.

log_failure_msg message

The log_failure_msg function shall cause the system to write a failure message to an unspecified log file. The format of the message is unspecified. The log_failure_msg function may also write a message to the standard output.

Note: The message should be relatively short; no more than 60 characters is highly desirable.

log_warning_msg message

The log_warning_msg function shall cause the system to write a warning message to an unspecified log file. The format of the message is unspecified. The log_warning_msg function may also write a message to the standard output.

Note: The message should be relatively short; no more than 60 characters is highly desirable.