]>
Commit | Line | Data |
---|---|---|
53e1b683 | 1 | /* SPDX-License-Identifier: LGPL-2.1+ */ |
abbbea81 LP |
2 | #ifndef foosddaemonhfoo |
3 | #define foosddaemonhfoo | |
4 | ||
5 | /*** | |
952d1536 KS |
6 | systemd is free software; you can redistribute it and/or modify it |
7 | under the terms of the GNU Lesser General Public License as published by | |
8 | the Free Software Foundation; either version 2.1 of the License, or | |
9 | (at your option) any later version. | |
10 | ||
11 | systemd is distributed in the hope that it will be useful, but | |
12 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
14 | Lesser General Public License for more details. | |
15 | ||
16 | You should have received a copy of the GNU Lesser General Public License | |
17 | along with systemd; If not, see <http://www.gnu.org/licenses/>. | |
abbbea81 LP |
18 | ***/ |
19 | ||
7c394faa | 20 | #include <inttypes.h> |
71d35b6b | 21 | #include <sys/types.h> |
f6f372d2 | 22 | #include <sys/socket.h> |
7c394faa | 23 | |
0ebee881 | 24 | #include "_sd-common.h" |
8c47c732 | 25 | |
0ebee881 | 26 | _SD_BEGIN_DECLARATIONS; |
40473a70 | 27 | |
0ebee881 | 28 | /* |
40473a70 LP |
29 | The following functionality is provided: |
30 | ||
31 | - Support for logging with log levels on stderr | |
32 | - File descriptor passing for socket-based activation | |
33 | - Daemon startup and status notification | |
34 | - Detection of systemd boots | |
35 | ||
cb07866b | 36 | See sd-daemon(3) for more information. |
40473a70 LP |
37 | */ |
38 | ||
abbbea81 LP |
39 | /* |
40 | Log levels for usage on stderr: | |
41 | ||
f9378423 | 42 | fprintf(stderr, SD_NOTICE "Hello World!\n"); |
abbbea81 LP |
43 | |
44 | This is similar to printk() usage in the kernel. | |
45 | */ | |
abbbea81 LP |
46 | #define SD_EMERG "<0>" /* system is unusable */ |
47 | #define SD_ALERT "<1>" /* action must be taken immediately */ | |
48 | #define SD_CRIT "<2>" /* critical conditions */ | |
49 | #define SD_ERR "<3>" /* error conditions */ | |
50 | #define SD_WARNING "<4>" /* warning conditions */ | |
51 | #define SD_NOTICE "<5>" /* normal but significant condition */ | |
52 | #define SD_INFO "<6>" /* informational */ | |
53 | #define SD_DEBUG "<7>" /* debug-level messages */ | |
54 | ||
55 | /* The first passed file descriptor is fd 3 */ | |
56 | #define SD_LISTEN_FDS_START 3 | |
57 | ||
40473a70 LP |
58 | /* |
59 | Returns how many file descriptors have been passed, or a negative | |
60 | errno code on failure. Optionally, removes the $LISTEN_FDS and | |
61 | $LISTEN_PID file descriptors from the environment (recommended, but | |
62 | problematic in threaded environments). If r is the return value of | |
63 | this function you'll find the file descriptors passed as fds | |
64 | SD_LISTEN_FDS_START to SD_LISTEN_FDS_START+r-1. Returns a negative | |
65 | errno style error code on failure. This function call ensures that | |
66 | the FD_CLOEXEC flag is set for the passed file descriptors, to make | |
67 | sure they are not passed on to child processes. If FD_CLOEXEC shall | |
68 | not be set, the caller needs to unset it after this call for all file | |
69 | descriptors that are used. | |
daaa7e5a LP |
70 | |
71 | See sd_listen_fds(3) for more information. | |
40473a70 | 72 | */ |
b136daf5 | 73 | int sd_listen_fds(int unset_environment); |
40473a70 | 74 | |
8dd4c05b LP |
75 | int sd_listen_fds_with_names(int unset_environment, char ***names); |
76 | ||
40473a70 LP |
77 | /* |
78 | Helper call for identifying a passed file descriptor. Returns 1 if | |
79 | the file descriptor is a FIFO in the file system stored under the | |
80 | specified path, 0 otherwise. If path is NULL a path name check will | |
81 | not be done and the call only verifies if the file descriptor | |
82 | refers to a FIFO. Returns a negative errno style error code on | |
83 | failure. | |
daaa7e5a LP |
84 | |
85 | See sd_is_fifo(3) for more information. | |
40473a70 | 86 | */ |
b136daf5 | 87 | int sd_is_fifo(int fd, const char *path); |
40473a70 | 88 | |
4160ec67 WD |
89 | /* |
90 | Helper call for identifying a passed file descriptor. Returns 1 if | |
91 | the file descriptor is a special character device on the file | |
92 | system stored under the specified path, 0 otherwise. | |
93 | If path is NULL a path name check will not be done and the call | |
94 | only verifies if the file descriptor refers to a special character. | |
95 | Returns a negative errno style error code on failure. | |
96 | ||
97 | See sd_is_special(3) for more information. | |
98 | */ | |
99 | int sd_is_special(int fd, const char *path); | |
100 | ||
40473a70 LP |
101 | /* |
102 | Helper call for identifying a passed file descriptor. Returns 1 if | |
103 | the file descriptor is a socket of the specified family (AF_INET, | |
104 | ...) and type (SOCK_DGRAM, SOCK_STREAM, ...), 0 otherwise. If | |
105 | family is 0 a socket family check will not be done. If type is 0 a | |
106 | socket type check will not be done and the call only verifies if | |
107 | the file descriptor refers to a socket. If listening is > 0 it is | |
108 | verified that the socket is in listening mode. (i.e. listen() has | |
109 | been called) If listening is == 0 it is verified that the socket is | |
110 | not in listening mode. If listening is < 0 no listening mode check | |
111 | is done. Returns a negative errno style error code on failure. | |
daaa7e5a LP |
112 | |
113 | See sd_is_socket(3) for more information. | |
40473a70 | 114 | */ |
b136daf5 | 115 | int sd_is_socket(int fd, int family, int type, int listening); |
40473a70 LP |
116 | |
117 | /* | |
118 | Helper call for identifying a passed file descriptor. Returns 1 if | |
119 | the file descriptor is an Internet socket, of the specified family | |
120 | (either AF_INET or AF_INET6) and the specified type (SOCK_DGRAM, | |
121 | SOCK_STREAM, ...), 0 otherwise. If version is 0 a protocol version | |
122 | check is not done. If type is 0 a socket type check will not be | |
123 | done. If port is 0 a socket port check will not be done. The | |
124 | listening flag is used the same way as in sd_is_socket(). Returns a | |
125 | negative errno style error code on failure. | |
daaa7e5a LP |
126 | |
127 | See sd_is_socket_inet(3) for more information. | |
40473a70 | 128 | */ |
b136daf5 | 129 | int sd_is_socket_inet(int fd, int family, int type, int listening, uint16_t port); |
40473a70 | 130 | |
f6f372d2 ZJS |
131 | /* |
132 | Helper call for identifying a passed file descriptor. Returns 1 if the | |
133 | file descriptor is an Internet socket of the specified type | |
134 | (SOCK_DGRAM, SOCK_STREAM, ...), and if the address of the socket is | |
135 | the same as the address specified by addr. The listening flag is used | |
136 | the same way as in sd_is_socket(). Returns a negative errno style | |
137 | error code on failure. | |
138 | ||
139 | See sd_is_socket_sockaddr(3) for more information. | |
140 | */ | |
141 | int sd_is_socket_sockaddr(int fd, int type, const struct sockaddr* addr, unsigned addr_len, int listening); | |
142 | ||
40473a70 LP |
143 | /* |
144 | Helper call for identifying a passed file descriptor. Returns 1 if | |
145 | the file descriptor is an AF_UNIX socket of the specified type | |
146 | (SOCK_DGRAM, SOCK_STREAM, ...) and path, 0 otherwise. If type is 0 | |
147 | a socket type check will not be done. If path is NULL a socket path | |
148 | check will not be done. For normal AF_UNIX sockets set length to | |
149 | 0. For abstract namespace sockets set length to the length of the | |
150 | socket name (including the initial 0 byte), and pass the full | |
151 | socket path in path (including the initial 0 byte). The listening | |
152 | flag is used the same way as in sd_is_socket(). Returns a negative | |
153 | errno style error code on failure. | |
daaa7e5a LP |
154 | |
155 | See sd_is_socket_unix(3) for more information. | |
40473a70 | 156 | */ |
b136daf5 | 157 | int sd_is_socket_unix(int fd, int type, int listening, const char *path, size_t length); |
40473a70 | 158 | |
916abb21 LP |
159 | /* |
160 | Helper call for identifying a passed file descriptor. Returns 1 if | |
161 | the file descriptor is a POSIX Message Queue of the specified name, | |
162 | 0 otherwise. If path is NULL a message queue name check is not | |
163 | done. Returns a negative errno style error code on failure. | |
09812eb7 LP |
164 | |
165 | See sd_is_mq(3) for more information. | |
916abb21 | 166 | */ |
b136daf5 | 167 | int sd_is_mq(int fd, const char *path); |
916abb21 | 168 | |
40473a70 | 169 | /* |
f9378423 | 170 | Informs systemd about changed daemon state. This takes a number of |
96d4ce01 | 171 | newline separated environment-style variable assignments in a |
f9378423 | 172 | string. The following variables are known: |
40473a70 | 173 | |
cc2b7b11 LP |
174 | MAINPID=... The main PID of a daemon, in case systemd did not |
175 | fork off the process itself. Example: "MAINPID=4711" | |
176 | ||
177 | READY=1 Tells systemd that daemon startup or daemon reload | |
178 | is finished (only relevant for services of Type=notify). | |
179 | The passed argument is a boolean "1" or "0". Since there | |
180 | is little value in signaling non-readiness the only | |
40473a70 LP |
181 | value daemons should send is "READY=1". |
182 | ||
cc2b7b11 LP |
183 | RELOADING=1 Tell systemd that the daemon began reloading its |
184 | configuration. When the configuration has been | |
185 | reloaded completely, READY=1 should be sent to inform | |
186 | systemd about this. | |
187 | ||
188 | STOPPING=1 Tells systemd that the daemon is about to go down. | |
189 | ||
40473a70 | 190 | STATUS=... Passes a single-line status string back to systemd |
4a6970c5 | 191 | that describes the daemon state. This is free-form |
40473a70 LP |
192 | and can be used for various purposes: general state |
193 | feedback, fsck-like programs could pass completion | |
194 | percentages and failing programs could pass a human | |
195 | readable error message. Example: "STATUS=Completed | |
196 | 66% of file system check..." | |
197 | ||
198 | ERRNO=... If a daemon fails, the errno-style error code, | |
199 | formatted as string. Example: "ERRNO=2" for ENOENT. | |
200 | ||
201 | BUSERROR=... If a daemon fails, the D-Bus error-style error | |
202 | code. Example: "BUSERROR=org.freedesktop.DBus.Error.TimedOut" | |
203 | ||
a6927d7f MO |
204 | WATCHDOG=1 Tells systemd to update the watchdog timestamp. |
205 | Services using this feature should do this in | |
206 | regular intervals. A watchdog framework can use the | |
09812eb7 LP |
207 | timestamps to detect failed services. Also see |
208 | sd_watchdog_enabled() below. | |
a6927d7f | 209 | |
c45d11cb LP |
210 | WATCHDOG_USEC=... |
211 | Reset watchdog_usec value during runtime. | |
212 | To reset watchdog_usec value, start the service again. | |
213 | Example: "WATCHDOG_USEC=20000000" | |
214 | ||
a354329f LP |
215 | FDSTORE=1 Store the file descriptors passed along with the |
216 | message in the per-service file descriptor store, | |
217 | and pass them to the main process again on next | |
218 | invocation. This variable is only supported with | |
219 | sd_pid_notify_with_fds(). | |
220 | ||
e78ee06d LP |
221 | FDSTOREREMOVE=1 |
222 | Remove one or more file descriptors from the file | |
223 | descriptor store, identified by the name specified | |
224 | in FDNAME=, see below. | |
225 | ||
226 | FDNAME= A name to assign to new file descriptors stored in the | |
227 | file descriptor store, or the name of the file descriptors | |
228 | to remove in case of FDSTOREREMOVE=1. | |
229 | ||
f9378423 | 230 | Daemons can choose to send additional variables. However, it is |
35b8ca3a | 231 | recommended to prefix variable names not listed above with X_. |
40473a70 LP |
232 | |
233 | Returns a negative errno-style error code on failure. Returns > 0 | |
234 | if systemd could be notified, 0 if it couldn't possibly because | |
235 | systemd is not running. | |
236 | ||
237 | Example: When a daemon finished starting up, it could issue this | |
238 | call to notify systemd about it: | |
239 | ||
240 | sd_notify(0, "READY=1"); | |
241 | ||
242 | See sd_notifyf() for more complete examples. | |
daaa7e5a LP |
243 | |
244 | See sd_notify(3) for more information. | |
40473a70 | 245 | */ |
b136daf5 | 246 | int sd_notify(int unset_environment, const char *state); |
40473a70 LP |
247 | |
248 | /* | |
249 | Similar to sd_notify() but takes a format string. | |
250 | ||
251 | Example 1: A daemon could send the following after initialization: | |
252 | ||
253 | sd_notifyf(0, "READY=1\n" | |
254 | "STATUS=Processing requests...\n" | |
255 | "MAINPID=%lu", | |
256 | (unsigned long) getpid()); | |
257 | ||
258 | Example 2: A daemon could send the following shortly before | |
259 | exiting, on failure: | |
260 | ||
261 | sd_notifyf(0, "STATUS=Failed to start up: %s\n" | |
262 | "ERRNO=%i", | |
42603849 | 263 | strerror(errno), |
40473a70 | 264 | errno); |
daaa7e5a LP |
265 | |
266 | See sd_notifyf(3) for more information. | |
40473a70 | 267 | */ |
0ebee881 | 268 | int sd_notifyf(int unset_environment, const char *format, ...) _sd_printf_(2,3); |
40473a70 | 269 | |
be8f4e9e LP |
270 | /* |
271 | Similar to sd_notify(), but send the message on behalf of another | |
272 | process, if the appropriate permissions are available. | |
273 | */ | |
274 | int sd_pid_notify(pid_t pid, int unset_environment, const char *state); | |
275 | ||
276 | /* | |
277 | Similar to sd_notifyf(), but send the message on behalf of another | |
278 | process, if the appropriate permissions are available. | |
279 | */ | |
280 | int sd_pid_notifyf(pid_t pid, int unset_environment, const char *format, ...) _sd_printf_(3,4); | |
281 | ||
a354329f LP |
282 | /* |
283 | Similar to sd_pid_notify(), but also passes the specified fd array | |
284 | to the service manager for storage. This is particularly useful for | |
285 | FDSTORE=1 messages. | |
286 | */ | |
287 | int sd_pid_notify_with_fds(pid_t pid, int unset_environment, const char *state, const int *fds, unsigned n_fds); | |
288 | ||
40473a70 LP |
289 | /* |
290 | Returns > 0 if the system was booted with systemd. Returns < 0 on | |
291 | error. Returns 0 if the system was not booted with systemd. Note | |
292 | that all of the functions above handle non-systemd boots just | |
293 | fine. You should NOT protect them with a call to this function. Also | |
294 | note that this function checks whether the system, not the user | |
295 | session is controlled by systemd. However the functions above work | |
af2d49f7 | 296 | for both user and system services. |
daaa7e5a LP |
297 | |
298 | See sd_booted(3) for more information. | |
40473a70 | 299 | */ |
b136daf5 | 300 | int sd_booted(void); |
8c47c732 | 301 | |
09812eb7 LP |
302 | /* |
303 | Returns > 0 if the service manager expects watchdog keep-alive | |
304 | events to be sent regularly via sd_notify(0, "WATCHDOG=1"). Returns | |
305 | 0 if it does not expect this. If the usec argument is non-NULL | |
306 | returns the watchdog timeout in µs after which the service manager | |
307 | will act on a process that has not sent a watchdog keep alive | |
308 | message. This function is useful to implement services that | |
309 | recognize automatically if they are being run under supervision of | |
310 | systemd with WatchdogSec= set. It is recommended for clients to | |
311 | generate keep-alive pings via sd_notify(0, "WATCHDOG=1") every half | |
312 | of the returned time. | |
313 | ||
314 | See sd_watchdog_enabled(3) for more information. | |
315 | */ | |
316 | int sd_watchdog_enabled(int unset_environment, uint64_t *usec); | |
317 | ||
0ebee881 | 318 | _SD_END_DECLARATIONS; |
8c47c732 | 319 | |
abbbea81 | 320 | #endif |