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