man/sd_notify.3

   1 '\" t
   2 .\"     Title: sd_notify
   3 .\"    Author: Lennart Poettering <lennart@poettering.net>
   4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
   5 .\"      Date: 02/15/2012
   6 .\"    Manual: sd_notify
   7 .\"    Source: systemd
   8 .\"  Language: English
   9 .\"
  10 .TH "SD_NOTIFY" "3" "02/15/2012" "systemd" "sd_notify"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 sd_notify, sd_notifyf \- Notify init system about start\-up completion and other daemon status changes
  32 .SH "SYNOPSIS"
  33 .sp
  34 .ft B
  35 .nf
  36 #include <systemd/sd\-daemon\&.h>
  37 .fi
  38 .ft
  39 .HP \w'int\ sd_notify('u
  40 .BI "int sd_notify(int\ " "unset_environment" ", const\ char\ *" "state" ");"
  41 .HP \w'int\ sd_notifyf('u
  42 .BI "int sd_notifyf(int\ " "unset_environment" ", const\ char\ *" "format" ", \&.\&.\&.);"
  43 .SH "DESCRIPTION"
  44 .PP
  45 \fBsd_notify()\fR
  46 shall be called by a daemon to notify the init system about status changes\&. It can be used to send arbitrary information, encoded in an environment\-block\-like string\&. Most importantly it can be used for start\-up completion notification\&.
  47 .PP
  48 If the
  49 \fIunset_environment\fR
  50 parameter is non\-zero
  51 \fBsd_notify()\fR
  52 will unset the
  53 \fI$NOTIFY_SOCKET\fR
  54 environment variable before returning (regardless whether the function call itself succeeded or not)\&. Further calls to
  55 \fBsd_notify()\fR
  56 will then fail, but the variable is no longer inherited by child processes\&.
  57 .PP
  58 The
  59 \fIstate\fR
  60 parameter should contain an newline\-separated list of variable assignments, similar in style to an environment block\&. A trailing newline is implied if none is specified\&. The string may contain any kind of variable assignments, but the following shall be considered well\-known:
  61 .PP
  62 READY=1
  63 .RS 4
  64 Tells the init system that daemon startup is finished\&. This is only used by systemd if the service definition file has Type=notify set\&. The passed argument is a boolean "1" or "0"\&. Since there is little value in signalling non\-readiness, the only value daemons should send is "READY=1"\&.
  65 .RE
  66 .PP
  67 STATUS=\&.\&.\&.
  68 .RS 4
  69 Passes a single\-line status string back to the init system that describes the daemon state\&. This is free\-form and can be used for various purposes: general state feedback, fsck\-like programs could pass completion percentages and failing programs could pass a human readable error message\&. Example: "STATUS=Completed 66% of file system check\&.\&.\&."
  70 .RE
  71 .PP
  72 ERRNO=\&.\&.\&.
  73 .RS 4
  74 If a daemon fails, the errno\-style error code, formatted as string\&. Example: "ERRNO=2" for ENOENT\&.
  75 .RE
  76 .PP
  77 BUSERROR=\&.\&.\&.
  78 .RS 4
  79 If a daemon fails, the D\-Bus error\-style error code\&. Example: "BUSERROR=org\&.freedesktop\&.DBus\&.Error\&.TimedOut"
  80 .RE
  81 .PP
  82 MAINPID=\&.\&.\&.
  83 .RS 4
  84 The main pid of the daemon, in case the init system did not fork off the process itself\&. Example: "MAINPID=4711"
  85 .RE
  86 .PP
  87 WATCHDOG=1
  88 .RS 4
  89 Tells systemd to update the watchdog timestamp\&. Services using this feature should do this in regular intervals\&. A watchdog framework can use the timestamps to detect failed services\&.
  90 .RE
  91 .PP
  92 It is recommended to prefix variable names that are not shown in the list above with
  93 \fIX_\fR
  94 to avoid namespace clashes\&.
  95 .PP
  96 Note that systemd will accept status data sent from a daemon only if the
  97 \fINotifyAccess=\fR
  98 option is correctly set in the service definition file\&. See
  99 \fBsystemd.service\fR(5)
 100 for details\&.
 101 .PP
 102 \fBsd_notifyf()\fR
 103 is similar to
 104 \fBsd_notify()\fR
 105 but takes a
 106 \fBprintf()\fR\-like format string plus arguments\&.
 107 .SH "RETURN VALUE"
 108 .PP
 109 On failure, these calls return a negative errno\-style error code\&. If
 110 \fI$NOTIFY_SOCKET\fR
 111 was not set and hence no status data could be sent, 0 is returned\&. If the status was sent these functions return with a positive return value\&. In order to support both, init systems that implement this scheme and those which don\*(Aqt, it is generally recommended to ignore the return value of this call\&.
 112 .SH "NOTES"
 113 .PP
 114 These functions are provided by the reference implementation of APIs for new\-style daemons and distributed with the systemd package\&. The algorithms they implement are simple, and can easily be reimplemented in daemons if it is important to support this interface without using the reference implementation\&.
 115 .PP
 116 Internally, these functions send a single datagram with the state string as payload to the AF_UNIX socket referenced in the
 117 \fI$NOTIFY_SOCKET\fR
 118 environment variable\&. If the first character of
 119 \fI$NOTIFY_SOCKET\fR
 120 is @ the string is understood as Linux abstract namespace socket\&. The datagram is accompanied by the process credentials of the sending daemon, using SCM_CREDENTIALS\&.
 121 .PP
 122 For details about the algorithms check the liberally licensed reference implementation sources:
 123 \m[blue]\fB\%http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c\fR\m[]
 124 resp\&.
 125 \m[blue]\fB\%http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h\fR\m[]
 126 .PP
 127 \fBsd_notify()\fR
 128 and
 129 \fBsd_notifyf()\fR
 130 are implemented in the reference implementation\*(Aqs
 131 sd\-daemon\&.c
 132 and
 133 sd\-daemon\&.h
 134 files\&. These interfaces are available as shared library, which can be compiled and linked to with the
 135 libsystemd\-daemon
 136 \fBpkg-config\fR(1)
 137 file\&. Alternatively, applications consuming these APIs may copy the implementation into their source tree\&. For more details about the reference implementation see
 138 \fBsd_daemon\fR(7)\&.
 139 .PP
 140 If the reference implementation is used as drop\-in files and \-DDISABLE_SYSTEMD is set during compilation these functions will always return 0 and otherwise become a NOP\&.
 141 .SH "ENVIRONMENT"
 142 .PP
 143 \fI$NOTIFY_SOCKET\fR
 144 .RS 4
 145 Set by the init system for supervised processes for status and start\-up completion notification\&. This environment variable specifies the socket
 146 \fBsd_notify()\fR
 147 talks to\&. See above for details\&.
 148 .RE
 149 .SH "EXAMPLES"
 150 .PP
 151 \fBExample\ \&1.\ \&Start-up Notification\fR
 152 .PP
 153 When a daemon finished starting up, it might issue the following call to notify the init system:
 154 .sp
 155 .if n \{\
 156 .RS 4
 157 .\}
 158 .nf
 159 sd_notify(0, "READY=1");
 160 .fi
 161 .if n \{\
 162 .RE
 163 .\}
 164 .PP
 165 \fBExample\ \&2.\ \&Extended Start-up Notification\fR
 166 .PP
 167 A daemon could send the following after completing initialization:
 168 .sp
 169 .if n \{\
 170 .RS 4
 171 .\}
 172 .nf
 173 sd_notifyf(0, "READY=1\en"
 174               "STATUS=Processing requests\&.\&.\&.\en"
 175               "MAINPID=%lu",
 176               (unsigned long) getpid());
 177 .fi
 178 .if n \{\
 179 .RE
 180 .\}
 181 .PP
 182 \fBExample\ \&3.\ \&Error Cause Notification\fR
 183 .PP
 184 A daemon could send the following shortly before exiting, on failure
 185 .sp
 186 .if n \{\
 187 .RS 4
 188 .\}
 189 .nf
 190 sd_notifyf(0, "STATUS=Failed to start up: %s\en"
 191               "ERRNO=%i",
 192               strerror(errno),
 193               errno);
 194 .fi
 195 .if n \{\
 196 .RE
 197 .\}
 198 .SH "SEE ALSO"
 199 .PP
 200
 201 \fBsystemd\fR(1),
 202 \fBsd_daemon\fR(7),
 203 \fBdaemon\fR(7),
 204 \fBsystemd.service\fR(5)
 205 .SH "AUTHOR"
 206 .PP
 207 \fBLennart Poettering\fR <\&lennart@poettering\&.net\&>
 208 .RS 4
 209 Developer
 210 .RE