]>
Commit | Line | Data |
---|---|---|
03467c88 | 1 | /*-*- Mode: C; c-basic-offset: 8; indent-tabs-mode: nil -*-*/ |
abbbea81 LP |
2 | |
3 | #ifndef foosddaemonhfoo | |
4 | #define foosddaemonhfoo | |
5 | ||
6 | /*** | |
7 | Copyright 2010 Lennart Poettering | |
8 | ||
9 | Permission is hereby granted, free of charge, to any person | |
10 | obtaining a copy of this software and associated documentation files | |
11 | (the "Software"), to deal in the Software without restriction, | |
12 | including without limitation the rights to use, copy, modify, merge, | |
13 | publish, distribute, sublicense, and/or sell copies of the Software, | |
14 | and to permit persons to whom the Software is furnished to do so, | |
15 | subject to the following conditions: | |
16 | ||
17 | The above copyright notice and this permission notice shall be | |
18 | included in all copies or substantial portions of the Software. | |
19 | ||
20 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, | |
21 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF | |
22 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND | |
23 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS | |
24 | BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN | |
25 | ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN | |
26 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
27 | SOFTWARE. | |
28 | ***/ | |
29 | ||
8c47c732 | 30 | #include <sys/types.h> |
7c394faa LP |
31 | #include <inttypes.h> |
32 | ||
8c47c732 LP |
33 | #ifdef __cplusplus |
34 | extern "C" { | |
35 | #endif | |
36 | ||
40473a70 LP |
37 | /* |
38 | Reference implementation of a few systemd related interfaces for | |
39 | writing daemons. These interfaces are trivial to implement. To | |
40 | simplify porting we provide this reference implementation. | |
41 | Applications are welcome to reimplement the algorithms described | |
42 | here if they do not want to include these two source files. | |
43 | ||
44 | The following functionality is provided: | |
45 | ||
46 | - Support for logging with log levels on stderr | |
47 | - File descriptor passing for socket-based activation | |
48 | - Daemon startup and status notification | |
49 | - Detection of systemd boots | |
50 | ||
51 | You may compile this with -DDISABLE_SYSTEMD to disable systemd | |
1d0ae74a | 52 | support. This makes all those calls NOPs that are directly related to |
40473a70 LP |
53 | systemd (i.e. only sd_is_xxx() will stay useful). |
54 | ||
55 | Since this is drop-in code we don't want any of our symbols to be | |
56 | exported in any case. Hence we declare hidden visibility for all of | |
57 | them. | |
58 | ||
59 | You may find an up-to-date version of these source files online: | |
60 | ||
8ab49c12 | 61 | http://cgit.freedesktop.org/systemd/plain/src/systemd/sd-daemon.h |
40473a70 LP |
62 | http://cgit.freedesktop.org/systemd/plain/src/sd-daemon.c |
63 | ||
64 | This should compile on non-Linux systems, too, but with the | |
65 | exception of the sd_is_xxx() calls all functions will become NOPs. | |
daaa7e5a LP |
66 | |
67 | See sd-daemon(7) for more information. | |
40473a70 LP |
68 | */ |
69 | ||
d0b48809 | 70 | #ifndef _sd_printf_attr_ |
e702c2c0 | 71 | #if __GNUC__ >= 4 |
706243a2 LP |
72 | #define _sd_printf_attr_(a,b) __attribute__ ((format (printf, a, b))) |
73 | #else | |
74 | #define _sd_printf_attr_(a,b) | |
e702c2c0 | 75 | #endif |
d0b48809 | 76 | #endif |
e702c2c0 | 77 | |
abbbea81 LP |
78 | /* |
79 | Log levels for usage on stderr: | |
80 | ||
f9378423 | 81 | fprintf(stderr, SD_NOTICE "Hello World!\n"); |
abbbea81 LP |
82 | |
83 | This is similar to printk() usage in the kernel. | |
84 | */ | |
abbbea81 LP |
85 | #define SD_EMERG "<0>" /* system is unusable */ |
86 | #define SD_ALERT "<1>" /* action must be taken immediately */ | |
87 | #define SD_CRIT "<2>" /* critical conditions */ | |
88 | #define SD_ERR "<3>" /* error conditions */ | |
89 | #define SD_WARNING "<4>" /* warning conditions */ | |
90 | #define SD_NOTICE "<5>" /* normal but significant condition */ | |
91 | #define SD_INFO "<6>" /* informational */ | |
92 | #define SD_DEBUG "<7>" /* debug-level messages */ | |
93 | ||
94 | /* The first passed file descriptor is fd 3 */ | |
95 | #define SD_LISTEN_FDS_START 3 | |
96 | ||
40473a70 LP |
97 | /* |
98 | Returns how many file descriptors have been passed, or a negative | |
99 | errno code on failure. Optionally, removes the $LISTEN_FDS and | |
100 | $LISTEN_PID file descriptors from the environment (recommended, but | |
101 | problematic in threaded environments). If r is the return value of | |
102 | this function you'll find the file descriptors passed as fds | |
103 | SD_LISTEN_FDS_START to SD_LISTEN_FDS_START+r-1. Returns a negative | |
104 | errno style error code on failure. This function call ensures that | |
105 | the FD_CLOEXEC flag is set for the passed file descriptors, to make | |
106 | sure they are not passed on to child processes. If FD_CLOEXEC shall | |
107 | not be set, the caller needs to unset it after this call for all file | |
108 | descriptors that are used. | |
daaa7e5a LP |
109 | |
110 | See sd_listen_fds(3) for more information. | |
40473a70 | 111 | */ |
b136daf5 | 112 | int sd_listen_fds(int unset_environment); |
40473a70 LP |
113 | |
114 | /* | |
115 | Helper call for identifying a passed file descriptor. Returns 1 if | |
116 | the file descriptor is a FIFO in the file system stored under the | |
117 | specified path, 0 otherwise. If path is NULL a path name check will | |
118 | not be done and the call only verifies if the file descriptor | |
119 | refers to a FIFO. Returns a negative errno style error code on | |
120 | failure. | |
daaa7e5a LP |
121 | |
122 | See sd_is_fifo(3) for more information. | |
40473a70 | 123 | */ |
b136daf5 | 124 | int sd_is_fifo(int fd, const char *path); |
40473a70 | 125 | |
4160ec67 WD |
126 | /* |
127 | Helper call for identifying a passed file descriptor. Returns 1 if | |
128 | the file descriptor is a special character device on the file | |
129 | system stored under the specified path, 0 otherwise. | |
130 | If path is NULL a path name check will not be done and the call | |
131 | only verifies if the file descriptor refers to a special character. | |
132 | Returns a negative errno style error code on failure. | |
133 | ||
134 | See sd_is_special(3) for more information. | |
135 | */ | |
136 | int sd_is_special(int fd, const char *path); | |
137 | ||
40473a70 LP |
138 | /* |
139 | Helper call for identifying a passed file descriptor. Returns 1 if | |
140 | the file descriptor is a socket of the specified family (AF_INET, | |
141 | ...) and type (SOCK_DGRAM, SOCK_STREAM, ...), 0 otherwise. If | |
142 | family is 0 a socket family check will not be done. If type is 0 a | |
143 | socket type check will not be done and the call only verifies if | |
144 | the file descriptor refers to a socket. If listening is > 0 it is | |
145 | verified that the socket is in listening mode. (i.e. listen() has | |
146 | been called) If listening is == 0 it is verified that the socket is | |
147 | not in listening mode. If listening is < 0 no listening mode check | |
148 | is done. Returns a negative errno style error code on failure. | |
daaa7e5a LP |
149 | |
150 | See sd_is_socket(3) for more information. | |
40473a70 | 151 | */ |
b136daf5 | 152 | int sd_is_socket(int fd, int family, int type, int listening); |
40473a70 LP |
153 | |
154 | /* | |
155 | Helper call for identifying a passed file descriptor. Returns 1 if | |
156 | the file descriptor is an Internet socket, of the specified family | |
157 | (either AF_INET or AF_INET6) and the specified type (SOCK_DGRAM, | |
158 | SOCK_STREAM, ...), 0 otherwise. If version is 0 a protocol version | |
159 | check is not done. If type is 0 a socket type check will not be | |
160 | done. If port is 0 a socket port check will not be done. The | |
161 | listening flag is used the same way as in sd_is_socket(). Returns a | |
162 | negative errno style error code on failure. | |
daaa7e5a LP |
163 | |
164 | See sd_is_socket_inet(3) for more information. | |
40473a70 | 165 | */ |
b136daf5 | 166 | int sd_is_socket_inet(int fd, int family, int type, int listening, uint16_t port); |
40473a70 LP |
167 | |
168 | /* | |
169 | Helper call for identifying a passed file descriptor. Returns 1 if | |
170 | the file descriptor is an AF_UNIX socket of the specified type | |
171 | (SOCK_DGRAM, SOCK_STREAM, ...) and path, 0 otherwise. If type is 0 | |
172 | a socket type check will not be done. If path is NULL a socket path | |
173 | check will not be done. For normal AF_UNIX sockets set length to | |
174 | 0. For abstract namespace sockets set length to the length of the | |
175 | socket name (including the initial 0 byte), and pass the full | |
176 | socket path in path (including the initial 0 byte). The listening | |
177 | flag is used the same way as in sd_is_socket(). Returns a negative | |
178 | errno style error code on failure. | |
daaa7e5a LP |
179 | |
180 | See sd_is_socket_unix(3) for more information. | |
40473a70 | 181 | */ |
b136daf5 | 182 | int sd_is_socket_unix(int fd, int type, int listening, const char *path, size_t length); |
40473a70 | 183 | |
916abb21 LP |
184 | /* |
185 | Helper call for identifying a passed file descriptor. Returns 1 if | |
186 | the file descriptor is a POSIX Message Queue of the specified name, | |
187 | 0 otherwise. If path is NULL a message queue name check is not | |
188 | done. Returns a negative errno style error code on failure. | |
189 | */ | |
b136daf5 | 190 | int sd_is_mq(int fd, const char *path); |
916abb21 | 191 | |
40473a70 | 192 | /* |
f9378423 | 193 | Informs systemd about changed daemon state. This takes a number of |
96d4ce01 | 194 | newline separated environment-style variable assignments in a |
f9378423 | 195 | string. The following variables are known: |
40473a70 LP |
196 | |
197 | READY=1 Tells systemd that daemon startup is finished (only | |
198 | relevant for services of Type=notify). The passed | |
199 | argument is a boolean "1" or "0". Since there is | |
35b8ca3a | 200 | little value in signaling non-readiness the only |
40473a70 LP |
201 | value daemons should send is "READY=1". |
202 | ||
203 | STATUS=... Passes a single-line status string back to systemd | |
204 | that describes the daemon state. This is free-from | |
205 | and can be used for various purposes: general state | |
206 | feedback, fsck-like programs could pass completion | |
207 | percentages and failing programs could pass a human | |
208 | readable error message. Example: "STATUS=Completed | |
209 | 66% of file system check..." | |
210 | ||
211 | ERRNO=... If a daemon fails, the errno-style error code, | |
212 | formatted as string. Example: "ERRNO=2" for ENOENT. | |
213 | ||
214 | BUSERROR=... If a daemon fails, the D-Bus error-style error | |
215 | code. Example: "BUSERROR=org.freedesktop.DBus.Error.TimedOut" | |
216 | ||
217 | MAINPID=... The main pid of a daemon, in case systemd did not | |
218 | fork off the process itself. Example: "MAINPID=4711" | |
219 | ||
f9378423 | 220 | Daemons can choose to send additional variables. However, it is |
35b8ca3a | 221 | recommended to prefix variable names not listed above with X_. |
40473a70 LP |
222 | |
223 | Returns a negative errno-style error code on failure. Returns > 0 | |
224 | if systemd could be notified, 0 if it couldn't possibly because | |
225 | systemd is not running. | |
226 | ||
227 | Example: When a daemon finished starting up, it could issue this | |
228 | call to notify systemd about it: | |
229 | ||
230 | sd_notify(0, "READY=1"); | |
231 | ||
232 | See sd_notifyf() for more complete examples. | |
daaa7e5a LP |
233 | |
234 | See sd_notify(3) for more information. | |
40473a70 | 235 | */ |
b136daf5 | 236 | int sd_notify(int unset_environment, const char *state); |
40473a70 LP |
237 | |
238 | /* | |
239 | Similar to sd_notify() but takes a format string. | |
240 | ||
241 | Example 1: A daemon could send the following after initialization: | |
242 | ||
243 | sd_notifyf(0, "READY=1\n" | |
244 | "STATUS=Processing requests...\n" | |
245 | "MAINPID=%lu", | |
246 | (unsigned long) getpid()); | |
247 | ||
248 | Example 2: A daemon could send the following shortly before | |
249 | exiting, on failure: | |
250 | ||
251 | sd_notifyf(0, "STATUS=Failed to start up: %s\n" | |
252 | "ERRNO=%i", | |
253 | strerror(errno), | |
254 | errno); | |
daaa7e5a LP |
255 | |
256 | See sd_notifyf(3) for more information. | |
40473a70 | 257 | */ |
b136daf5 | 258 | int sd_notifyf(int unset_environment, const char *format, ...) _sd_printf_attr_(2,3); |
40473a70 LP |
259 | |
260 | /* | |
261 | Returns > 0 if the system was booted with systemd. Returns < 0 on | |
262 | error. Returns 0 if the system was not booted with systemd. Note | |
263 | that all of the functions above handle non-systemd boots just | |
264 | fine. You should NOT protect them with a call to this function. Also | |
265 | note that this function checks whether the system, not the user | |
266 | session is controlled by systemd. However the functions above work | |
af2d49f7 | 267 | for both user and system services. |
daaa7e5a LP |
268 | |
269 | See sd_booted(3) for more information. | |
40473a70 | 270 | */ |
b136daf5 | 271 | int sd_booted(void); |
8c47c732 LP |
272 | |
273 | #ifdef __cplusplus | |
274 | } | |
275 | #endif | |
276 | ||
abbbea81 | 277 | #endif |