debian/lsb-base.README.Debian

   1 lsb-base for Debian
   2 -------------------
   3
   4 The Debian lsb-base package provides a series of logging functions to
   5 permit simplified logging of init script actions.  These functions are
   6 specific to Debian and (in some cases) other derived distributions.
   7
   8   - log_daemon_msg "Starting/stopping long daemon name" "daemond"
   9
  10     Log starting/stopping of daemons.  On Debian, outputs:
  11
  12     "Starting/stopping long daemon name: daemond"
  13
  14     and leaves the cursor at the end of the line.
  15
  16   - log_progress_msg "daemon2d"
  17
  18     Log startup of a second daemon (e.g. sysklogd, nfs init scripts).
  19     On Debian, outputs " daemon2d" and leaves the cursor at the EOL.
  20
  21   - log_end_msg 0/1
  22
  23     Log successful startup.  On Debian, outputs "." followed by newline.
  24     A non-zero code may also be specified, which indicates failure;
  25     currently implemented as outputting "failed!" (in red on a color
  26     TTY) followed by newline.
  27
  28     Unsucessful startup will cause the specified failure code to be
  29     returned by this function; unless trapped, this may end your init
  30     script depending on whether or not set -e is used.
  31
  32   - log_action_msg "Setting VARIABLE to VALUE"
  33
  34     Log an atomic action by your init script.  Typically, this is the
  35     setting of a kernel variable, but it might be something else that is
  36     not expected to take any time (or fail).
  37
  38     On Debian, a trailing period will be added to the message,
  39     followed by a newline.
  40
  41   - log_action_begin_msg "Configuring network interfaces"
  42
  43     Log the start of an action that is expected to take some time.  On
  44     Debian, an elipsis (...) will follow the message, and the cursor will
  45     stay at EOL.
  46
  47   - log_action_cont_msg "flushing ARP cache"
  48
  49     Log an action as part of a process started by log_action_start_msg().
  50     On Debian, this message will receive a trailing elipsis, and the cursor
  51     will stay at EOL.
  52
  53   - log_action_end_msg {0|1} ["message"]
  54
  55     Log the end of the action started by log_action_start_msg().  If one
  56     argument is supplied, either "done." (0) or "failed." (1) will be output,
  57     followed by a newline.  If a second argument is supplied, the message
  58     will appear as follows:
  59
  60     "done (your message here)." --- if first argument is 0
  61     "failed (your message here)." --- if first argument is 1
  62
  63     This argument must be quoted, or otherwise only the first word will
  64     be output.
  65
  66     On color TTYs, the failure messages will be red.
  67
  68     Note that unlike log_end_msg(), this function does not return the
  69     first argument as its exit code.
  70
  71 A deprecated function, log_start_msg, is also provided for
  72 compatibility with a few older packages and a derived distribution.
  73 This may eventually disappear.
  74
  75 To use these functions, source /lib/lsb/init-functions at the
  76 beginning of your (Bourne sh or compatible) init script.
  77
  78 Please depend on lsb-base (>= 3.0-6) to ensure all of these
  79 functions are available for your init scripts.
  80
  81 LSB LOGGING FUNCTIONS
  82
  83 This package also includes the LSB-specified logging functions:
  84
  85 log_success_msg message
  86 log_failure_msg message
  87 log_warning_msg message
  88
  89 These functions *do not* comply with Debian policy and should only be used
  90 by LSB packages.
  91
  92 OTHER LSB FUNCTIONALITY
  93
  94 start_daemon [-f] [-n nicelevel] [-p pidfile] pathname [args...]
  95   Start "pathname" as a daemon.  We call Debian's start-stop-daemon to
  96   implement this functionality.
  97
  98 killproc [-p pidfile] pathname [signal]
  99   Stops "pathname" (using "pidfile", if specified, to find the process
 100   ID).  This is implemented using start-stop-daemon as well.
 101
 102 pidofproc [-p pidfile] pathname
 103   Find the process ID of pathname.  If the pidfile is specified, we use the
 104   first space-delimited word; otherwise, /bin/pidof is used from the
 105   sysvinit package, if available.
 106
 107 For full documentation, please refer to:
 108
 109 http://refspecs.freestandards.org/LSB_3.1.0/LSB-Core-generic/LSB-Core-generic/iniscrptfunc.html
 110
 111 Note: Debian packages probably should use start-stop-daemon directly;
 112 however, these functions may be useful in porting init scripts from
 113 other distributions.  Also, if you are developing software for wider
 114 use, you should not expect these functions to be implemented
 115 identically on other LSB-conforming distributions; the only guaranteed
 116 behaviors are those in the specification above.
 117
 118 CUSTOMIZING LOGGING OUTPUT
 119
 120 If it exists, /etc/lsb-base-logging.sh will be sourced by
 121 /lib/lsb/init-functions.  You may override any of the log_* functions
 122 in this file.  The intent is for this file to be supplied as a
 123 conffile by derived distributions wishing to log init script events in
 124 a different way; this may also be useful on systems where the console
 125 log is not visible during startup.
 126
 127 If supplied, this script fragment should be compatible with any Debian
 128 /bin/sh, as init scripts sourcing this file may be running under any
 129 Bourne-style shell permitted by Debian policy (i.e. not just bash).
 130
 131 "Fancy output" can be overriden by setting FANCYTTY=0 in this file.
 132
 133 From lsb-base 3.2-14, you can use the following hook functions which
 134 are called by the appropriate functions, instead of supplying your own
 135 logging functions:
 136
 137 log_daemon_msg_pre
 138 log_daemon_msg_post
 139 log_end_msg_pre
 140 log_end_msg_post
 141 log_action_end_msg_post
 142 log_action_end_msg_post
 143
 144 Each function receives all of the arguments sent to the parent
 145 function; the "pre" functions operate before any output, while the
 146 "post" functions operate after the output is produced.
 147
 148  -- Chris Lawrence <lawrencc@debian.org>, Mon, 14 Jul 2008 11:34:48 -0500