Line data Source code
1 : /*-*- Mode: C; c-basic-offset: 8; indent-tabs-mode: nil -*-*/
2 :
3 : #pragma once
4 :
5 : /***
6 : This file is part of systemd.
7 :
8 : Copyright 2013 Lennart Poettering
9 :
10 : systemd is free software; you can redistribute it and/or modify it
11 : under the terms of the GNU Lesser General Public License as published by
12 : the Free Software Foundation; either version 2.1 of the License, or
13 : (at your option) any later version.
14 :
15 : systemd is distributed in the hope that it will be useful, but
16 : WITHOUT ANY WARRANTY; without even the implied warranty of
17 : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 : Lesser General Public License for more details.
19 :
20 : You should have received a copy of the GNU Lesser General Public License
21 : along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 : ***/
23 :
24 : #include <sys/types.h>
25 : #include <inttypes.h>
26 :
27 : /*
28 : The following functionality is provided:
29 :
30 : - Support for logging with log levels on stderr
31 : - File descriptor passing for socket-based activation
32 : - Daemon startup and status notification
33 : - Detection of systemd boots
34 :
35 : See sd-daemon(3) for more information.
36 : */
37 :
38 : /*
39 : Log levels for usage on stderr:
40 :
41 : fprintf(stderr, SD_NOTICE "Hello World!\n");
42 :
43 : This is similar to printk() usage in the kernel.
44 : */
45 : #define SD_EMERG "<0>" /* system is unusable */
46 : #define SD_ALERT "<1>" /* action must be taken immediately */
47 : #define SD_CRIT "<2>" /* critical conditions */
48 : #define SD_ERR "<3>" /* error conditions */
49 : #define SD_WARNING "<4>" /* warning conditions */
50 : #define SD_NOTICE "<5>" /* normal but significant condition */
51 : #define SD_INFO "<6>" /* informational */
52 : #define SD_DEBUG "<7>" /* debug-level messages */
53 :
54 : /* The first passed file descriptor is fd 3 */
55 : #define SD_LISTEN_FDS_START 3
56 :
57 : /*
58 : Returns how many file descriptors have been passed, or a negative
59 : errno code on failure. Optionally, removes the $LISTEN_FDS and
60 : $LISTEN_PID file descriptors from the environment (recommended, but
61 : problematic in threaded environments). If r is the return value of
62 : this function you'll find the file descriptors passed as fds
63 : SD_LISTEN_FDS_START to SD_LISTEN_FDS_START+r-1. Returns a negative
64 : errno style error code on failure. This function call ensures that
65 : the FD_CLOEXEC flag is set for the passed file descriptors, to make
66 : sure they are not passed on to child processes. If FD_CLOEXEC shall
67 : not be set, the caller needs to unset it after this call for all file
68 : descriptors that are used.
69 :
70 : See sd_listen_fds(3) for more information.
71 : */
72 : int sd_listen_fds(int unset_environment);
73 : int sd_listen_fds_with_names(int unset_environment, char ***names);
74 :
75 : /*
76 : Helper call for identifying a passed file descriptor. Returns 1 if
77 : the file descriptor is a FIFO in the file system stored under the
78 : specified path, 0 otherwise. If path is NULL a path name check will
79 : not be done and the call only verifies if the file descriptor
80 : refers to a FIFO. Returns a negative errno style error code on
81 : failure.
82 :
83 : See sd_is_fifo(3) for more information.
84 : */
85 : int sd_is_fifo(int fd, const char *path);
86 :
87 : /*
88 : Helper call for identifying a passed file descriptor. Returns 1 if
89 : the file descriptor is a special character device on the file
90 : system stored under the specified path, 0 otherwise.
91 : If path is NULL a path name check will not be done and the call
92 : only verifies if the file descriptor refers to a special character.
93 : Returns a negative errno style error code on failure.
94 :
95 : See sd_is_special(3) for more information.
96 : */
97 : int sd_is_special(int fd, const char *path);
98 :
99 : /*
100 : Helper call for identifying a passed file descriptor. Returns 1 if
101 : the file descriptor is a socket of the specified family (AF_INET,
102 : ...) and type (SOCK_DGRAM, SOCK_STREAM, ...), 0 otherwise. If
103 : family is 0 a socket family check will not be done. If type is 0 a
104 : socket type check will not be done and the call only verifies if
105 : the file descriptor refers to a socket. If listening is > 0 it is
106 : verified that the socket is in listening mode. (i.e. listen() has
107 : been called) If listening is == 0 it is verified that the socket is
108 : not in listening mode. If listening is < 0 no listening mode check
109 : is done. Returns a negative errno style error code on failure.
110 :
111 : See sd_is_socket(3) for more information.
112 : */
113 : int sd_is_socket(int fd, int family, int type, int listening);
114 :
115 : /*
116 : Helper call for identifying a passed file descriptor. Returns 1 if
117 : the file descriptor is an Internet socket, of the specified family
118 : (either AF_INET or AF_INET6) and the specified type (SOCK_DGRAM,
119 : SOCK_STREAM, ...), 0 otherwise. If version is 0 a protocol version
120 : check is not done. If type is 0 a socket type check will not be
121 : done. If port is 0 a socket port check will not be done. The
122 : listening flag is used the same way as in sd_is_socket(). Returns a
123 : negative errno style error code on failure.
124 :
125 : See sd_is_socket_inet(3) for more information.
126 : */
127 : int sd_is_socket_inet(int fd, int family, int type, int listening, uint16_t port);
128 :
129 : /*
130 : Helper call for identifying a passed file descriptor. Returns 1 if
131 : the file descriptor is an AF_UNIX socket of the specified type
132 : (SOCK_DGRAM, SOCK_STREAM, ...) and path, 0 otherwise. If type is 0
133 : a socket type check will not be done. If path is NULL a socket path
134 : check will not be done. For normal AF_UNIX sockets set length to
135 : 0. For abstract namespace sockets set length to the length of the
136 : socket name (including the initial 0 byte), and pass the full
137 : socket path in path (including the initial 0 byte). The listening
138 : flag is used the same way as in sd_is_socket(). Returns a negative
139 : errno style error code on failure.
140 :
141 : See sd_is_socket_unix(3) for more information.
142 : */
143 : int sd_is_socket_unix(int fd, int type, int listening, const char *path, size_t length);
144 :
145 : /*
146 : Helper call for identifying a passed file descriptor. Returns 1 if
147 : the file descriptor is a POSIX Message Queue of the specified name,
148 : 0 otherwise. If path is NULL a message queue name check is not
149 : done. Returns a negative errno style error code on failure.
150 :
151 : See sd_is_mq(3) for more information.
152 : */
153 : int sd_is_mq(int fd, const char *path);
154 :
155 : /*
156 : Informs systemd about changed daemon state. This takes a number of
157 : newline separated environment-style variable assignments in a
158 : string. The following variables are known:
159 :
160 : READY=1 Tells systemd that daemon startup is finished (only
161 : relevant for services of Type=notify). The passed
162 : argument is a boolean "1" or "0". Since there is
163 : little value in signaling non-readiness the only
164 : value daemons should send is "READY=1".
165 :
166 : STATUS=... Passes a single-line status string back to systemd
167 : that describes the daemon state. This is free-from
168 : and can be used for various purposes: general state
169 : feedback, fsck-like programs could pass completion
170 : percentages and failing programs could pass a human
171 : readable error message. Example: "STATUS=Completed
172 : 66% of file system check..."
173 :
174 : ERRNO=... If a daemon fails, the errno-style error code,
175 : formatted as string. Example: "ERRNO=2" for ENOENT.
176 :
177 : BUSERROR=... If a daemon fails, the D-Bus error-style error
178 : code. Example: "BUSERROR=org.freedesktop.DBus.Error.TimedOut"
179 :
180 : MAINPID=... The main pid of a daemon, in case systemd did not
181 : fork off the process itself. Example: "MAINPID=4711"
182 :
183 : WATCHDOG=1 Tells systemd to update the watchdog timestamp.
184 : Services using this feature should do this in
185 : regular intervals. A watchdog framework can use the
186 : timestamps to detect failed services. Also see
187 : sd_watchdog_enabled() below.
188 :
189 : Daemons can choose to send additional variables. However, it is
190 : recommended to prefix variable names not listed above with X_.
191 :
192 : Returns a negative errno-style error code on failure. Returns > 0
193 : if systemd could be notified, 0 if it couldn't possibly because
194 : systemd is not running.
195 :
196 : Example: When a daemon finished starting up, it could issue this
197 : call to notify systemd about it:
198 :
199 : sd_notify(0, "READY=1");
200 :
201 : See sd_notifyf() for more complete examples.
202 :
203 : See sd_notify(3) for more information.
204 : */
205 : int sd_notify(int unset_environment, const char *state);
206 :
207 : /*
208 : Similar to sd_notify() but takes a format string.
209 :
210 : Example 1: A daemon could send the following after initialization:
211 :
212 : sd_notifyf(0, "READY=1\n"
213 : "STATUS=Processing requests...\n"
214 : "MAINPID=%lu",
215 : (unsigned long) getpid());
216 :
217 : Example 2: A daemon could send the following shortly before
218 : exiting, on failure:
219 :
220 : sd_notifyf(0, "STATUS=Failed to start up: %s\n"
221 : "ERRNO=%i",
222 : strerror(errno),
223 : errno);
224 :
225 : See sd_notifyf(3) for more information.
226 : */
227 : int sd_notifyf(int unset_environment, const char *format, ...)
228 : __attribute__((format(printf, 2, 3)));
229 :
230 : /*
231 : Returns > 0 if the system was booted with systemd. Returns < 0 on
232 : error. Returns 0 if the system was not booted with systemd. Note
233 : that all of the functions above handle non-systemd boots just
234 : fine. You should NOT protect them with a call to this function. Also
235 : note that this function checks whether the system, not the user
236 : session is controlled by systemd. However the functions above work
237 : for both user and system services.
238 :
239 : See sd_booted(3) for more information.
240 : */
241 : int sd_booted(void);
242 :
243 : /*
244 : Returns > 0 if the service manager expects watchdog keep-alive
245 : events to be sent regularly via sd_notify(0, "WATCHDOG=1"). Returns
246 : 0 if it does not expect this. If the usec argument is non-NULL
247 : returns the watchdog timeout in µs after which the service manager
248 : will act on a process that has not sent a watchdog keep alive
249 : message. This function is useful to implement services that
250 : recognize automatically if they are being run under supervision of
251 : systemd with WatchdogSec= set. It is recommended for clients to
252 : generate keep-alive pings via sd_notify(0, "WATCHDOG=1") every half
253 : of the returned time.
254 :
255 : See sd_watchdog_enabled(3) for more information.
256 : */
257 : int sd_watchdog_enabled(int unset_environment, uint64_t *usec);
258 :
259 :
260 0 : static inline void strv_free(char **p)
261 : {
262 0 : if (p) {
263 0 : free(p[0]);
264 0 : free(p);
265 : }
266 0 : }
|
