1SD_NOTIFY(3) sd_notify SD_NOTIFY(3)
2
6 sd_notify, sd_notifyf, sd_pid_notify, sd_pid_notifyf,
7 sd_pid_notify_with_fds - Notify service manager about start-up
8 completion and other service status changes
9
11 #include <systemd/sd-daemon.h>
12 int sd_notify(int unset_environment, const char *state);
14 int sd_notifyf(int unset_environment, const char *format, ...);
16 int sd_pid_notify(pid_t pid, int unset_environment, const char *state);
18 int sd_pid_notifyf(pid_t pid, int unset_environment,
20 const char *format, ...);
21 int sd_pid_notify_with_fds(pid_t pid, int unset_environment,
23 const char *state, const int *fds,
24 unsigned n_fds);
25
27 sd_notify() may be called by a service to notify the service manager
28 about state changes. It can be used to send arbitrary information,
29 encoded in an environment-block-like string. Most importantly it can be
30 used for start-up completion notification.
31 If the unset_environment parameter is non-zero, sd_notify() will unset
33 the $NOTIFY_SOCKET environment variable before returning (regardless of
34 whether the function call itself succeeded or not). Further calls to
35 sd_notify() will then fail, but the variable is no longer inherited by
36 child processes.
37 The state parameter should contain a newline-separated list of variable
39 assignments, similar in style to an environment block. A trailing
40 newline is implied if none is specified. The string may contain any
41 kind of variable assignments, but the following shall be considered
42 well-known:
43 READY=1
45 Tells the service manager that service startup is finished. This is
46 only used by systemd if the service definition file has Type=notify
47 set. Since there is little value in signaling non-readiness, the
48 only value services should send is "READY=1" (i.e. "READY=0" is
49 not defined).
50 RELOADING=1
52 Tells the service manager that the service is reloading its
53 configuration. This is useful to allow the service manager to track
54 the service's internal state, and present it to the user. Note that
55 a service that sends this notification must also send a "READY=1"
56 notification when it completed reloading its configuration.
57 STOPPING=1
59 Tells the service manager that the service is beginning its
60 shutdown. This is useful to allow the service manager to track the
61 service's internal state, and present it to the user.
62 STATUS=...
64 Passes a single-line UTF-8 status string back to the service
65 manager that describes the service state. This is free-form and can
66 be used for various purposes: general state feedback, fsck-like
67 programs could pass completion percentages and failing programs
68 could pass a human readable error message. Example:
69 "STATUS=Completed 66% of file system check..."
70 ERRNO=...
72 If a service fails, the errno-style error code, formatted as
73 string. Example: "ERRNO=2" for ENOENT.
74 BUSERROR=...
76 If a service fails, the D-Bus error-style error code. Example:
77 "BUSERROR=org.freedesktop.DBus.Error.TimedOut"
78 MAINPID=...
80 The main process ID (PID) of the service, in case the service
81 manager did not fork off the process itself. Example:
82 "MAINPID=4711"
83 WATCHDOG=1
85 Tells the service manager to update the watchdog timestamp. This is
86 the keep-alive ping that services need to issue in regular
87 intervals if WatchdogSec= is enabled for it. See systemd.service(5)
88 for information how to enable this functionality and
89 sd_watchdog_enabled(3) for the details of how the service can check
90 if the the watchdog is enabled.
91 FDSTORE=1
93 Stores additional file descriptors in the service manager. File
94 descriptors sent this way will be maintained per-service by the
95 service manager and be passed again using the usual file descriptor
96 passing logic on the next invocation of the service (see
97 sd_listen_fds(3)). This is useful for implementing service restart
98 schemes where services serialize their state to /run, push their
99 file descriptors to the system manager, and are then restarted,
100 retrieving their state again via socket passing and /run. Note that
101 the service manager will accept messages for a service only if
102 FileDescriptorStoreMax= is set to non-zero for it (defaults to
103 zero). See systemd.service(5) for details. Multiple arrays of file
104 descriptors may be sent in separate messages, in which case the
105 arrays are combined. Note that the service manager removes
106 duplicate file descriptors before passing them to the service. Use
107 sd_pid_notify_with_fds() to send messages with "FDSTORE=1", see
108 below.
109 It is recommended to prefix variable names that are not listed above
111 with X_ to avoid namespace clashes.
112 Note that systemd will accept status data sent from a service only if
114 the NotifyAccess= option is correctly set in the service definition
115 file. See systemd.service(5) for details.
116 sd_notifyf() is similar to sd_notify() but takes a printf()-like format
118 string plus arguments.
119 sd_pid_notify() and sd_pid_notifyf() are similar to sd_notify() and
121 sd_notifyf() but take a process ID (PID) to use as originating PID for
122 the message as first argument. This is useful to send notification
123 messages on behalf of other processes, provided the appropriate
124 privileges are available. If the PID argument is specified as 0 the
125 process ID of the calling process is used, in which case the calls are
126 fully equivalent to sd_notify() and sd_notifyf().
127 sd_pid_notify_with_fds() is similar to sd_pid_notify() but takes an
129 additional array of file descriptors. These file descriptors are sent
130 along the notification message to the service manager. This is
131 particularly useful for sending "FDSTORE=1" messages, as described
132 above. The additional arguments are a pointer to the file descriptor
133 array plus the number of file descriptors in the array. If the number
134 of file descriptors is passed as 0, the call is fully equivalent to
135 sd_pid_notify(), i.e. no file descriptors are passed. Note that sending
136 file descriptors to the service manager on messages that do not expect
137 them (i.e. without "FDSTORE=1") they are immediately closed on
138 reception.
139
141 On failure, these calls return a negative errno-style error code. If
142 $NOTIFY_SOCKET was not set and hence no status data could be sent, 0 is
143 returned. If the status was sent, these functions return with a
144 positive return value. In order to support both, init systems that
145 implement this scheme and those which do not, it is generally
146 recommended to ignore the return value of this call.
147
149 These APIs are implemented as a shared library, which can be compiled
150 and linked to with the libsystemd pkg-config(1) file.
151 Internally, these functions send a single datagram with the state
153 string as payload to the AF_UNIX socket referenced in the
154 $NOTIFY_SOCKET environment variable. If the first character of
155 $NOTIFY_SOCKET is "@", the string is understood as Linux abstract
156 namespace socket. The datagram is accompanied by the process
157 credentials of the sending service, using SCM_CREDENTIALS.
158
160 $NOTIFY_SOCKET
161 Set by the service manager for supervised processes for status and
162 start-up completion notification. This environment variable
163 specifies the socket sd_notify() talks to. See above for details.
164
166 Example 1. Start-up Notification
167 When a service finished starting up, it might issue the following call
169 to notify the service manager:
170 sd_notify(0, "READY=1");
172 Example 2. Extended Start-up Notification
174 A service could send the following after completing initialization:
176 sd_notifyf(0, "READY=1\n"
178 "STATUS=Processing requests...\n"
179 "MAINPID=%lu",
180 (unsigned long) getpid());
181 Example 3. Error Cause Notification
183 A service could send the following shortly before exiting, on failure:
185 sd_notifyf(0, "STATUS=Failed to start up: %s\n"
187 "ERRNO=%i",
188 strerror(errno),
189 errno);
190 Example 4. Store a File Descriptor in the Service Manager
192 To store an open file descriptor in the service manager, in order to
194 continue operation after a service restart without losing state use
195 "FDSTORE=1":
196 sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);
198
200 systemd(1), sd-daemon(3), daemon(7), systemd.service(5),
201 sd_watchdog_enabled(3)
202systemd 219 SD_NOTIFY(3)