4d7859d173282e16bb75254c2b4ec14a915ef30bKay Sievers This file is part of systemd.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Copyright 2013 Lennart Poettering
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering systemd is free software; you can redistribute it and/or modify it
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering under the terms of the GNU Lesser General Public License as published by
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering the Free Software Foundation; either version 2.1 of the License, or
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering (at your option) any later version.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering systemd is distributed in the hope that it will be useful, but
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Lesser General Public License for more details.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering You should have received a copy of the GNU Lesser General Public License
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
3f6fd1ba65f962702753c4ad284b588e59689a23Lennart Poettering The following functionality is provided:
3ffd4af22052963e7a29431721ee204e634bea75Lennart Poettering - Support for logging with log levels on stderr
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar - File descriptor passing for socket-based activation
7568345034f2890af745747783c5abfbf6eccf0fLennart Poettering - Daemon startup and status notification
3f6fd1ba65f962702753c4ad284b588e59689a23Lennart Poettering - Detection of systemd boots
3f6fd1ba65f962702753c4ad284b588e59689a23Lennart Poettering See sd-daemon(3) for more information.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Log levels for usage on stderr:
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering fprintf(stderr, SD_NOTICE "Hello World!\n");
7085053a437456ab87d726f3697002dd811fdf7aDaniel Wallace This is similar to printk() usage in the kernel.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering#define SD_EMERG "<0>" /* system is unusable */
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering#define SD_ALERT "<1>" /* action must be taken immediately */
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering#define SD_CRIT "<2>" /* critical conditions */
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering#define SD_ERR "<3>" /* error conditions */
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering#define SD_WARNING "<4>" /* warning conditions */
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering#define SD_NOTICE "<5>" /* normal but significant condition */
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering#define SD_DEBUG "<7>" /* debug-level messages */
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering/* The first passed file descriptor is fd 3 */
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Returns how many file descriptors have been passed, or a negative
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering errno code on failure. Optionally, removes the $LISTEN_FDS and
46e65dcc3a522b5e992e165b5e61d14254026859Lennart Poettering $LISTEN_PID file descriptors from the environment (recommended, but
46e65dcc3a522b5e992e165b5e61d14254026859Lennart Poettering problematic in threaded environments). If r is the return value of
46e65dcc3a522b5e992e165b5e61d14254026859Lennart Poettering this function you'll find the file descriptors passed as fds
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering SD_LISTEN_FDS_START to SD_LISTEN_FDS_START+r-1. Returns a negative
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering errno style error code on failure. This function call ensures that
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering the FD_CLOEXEC flag is set for the passed file descriptors, to make
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering sure they are not passed on to child processes. If FD_CLOEXEC shall
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering not be set, the caller needs to unset it after this call for all file
e7e55dbdc38f929805ab2407fbd50886043a9e7cDavid Herrmann descriptors that are used.
e7e55dbdc38f929805ab2407fbd50886043a9e7cDavid Herrmann See sd_listen_fds(3) for more information.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poetteringint sd_listen_fds_with_names(int unset_environment, char ***names);
e7e55dbdc38f929805ab2407fbd50886043a9e7cDavid Herrmann Helper call for identifying a passed file descriptor. Returns 1 if
e7e55dbdc38f929805ab2407fbd50886043a9e7cDavid Herrmann the file descriptor is a FIFO in the file system stored under the
e7e55dbdc38f929805ab2407fbd50886043a9e7cDavid Herrmann specified path, 0 otherwise. If path is NULL a path name check will
e7e55dbdc38f929805ab2407fbd50886043a9e7cDavid Herrmann not be done and the call only verifies if the file descriptor
e7e55dbdc38f929805ab2407fbd50886043a9e7cDavid Herrmann refers to a FIFO. Returns a negative errno style error code on
e7e55dbdc38f929805ab2407fbd50886043a9e7cDavid Herrmann See sd_is_fifo(3) for more information.
ff9b60f38bf68eba4a47cabff14547d92e083214Torstein Husebø Helper call for identifying a passed file descriptor. Returns 1 if
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar the file descriptor is a special character device on the file
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar system stored under the specified path, 0 otherwise.
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar If path is NULL a path name check will not be done and the call
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar only verifies if the file descriptor refers to a special character.
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar Returns a negative errno style error code on failure.
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar See sd_is_special(3) for more information.
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar Helper call for identifying a passed file descriptor. Returns 1 if
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar the file descriptor is a socket of the specified family (AF_INET,
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar ...) and type (SOCK_DGRAM, SOCK_STREAM, ...), 0 otherwise. If
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar family is 0 a socket family check will not be done. If type is 0 a
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar socket type check will not be done and the call only verifies if
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar the file descriptor refers to a socket. If listening is > 0 it is
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar verified that the socket is in listening mode. (i.e. listen() has
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar been called) If listening is == 0 it is verified that the socket is
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar not in listening mode. If listening is < 0 no listening mode check
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar is done. Returns a negative errno style error code on failure.
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar See sd_is_socket(3) for more information.
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletarint sd_is_socket(int fd, int family, int type, int listening);
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar Helper call for identifying a passed file descriptor. Returns 1 if
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar the file descriptor is an Internet socket, of the specified family
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar (either AF_INET or AF_INET6) and the specified type (SOCK_DGRAM,
63229aa1abdb98aa69fda9819ed2f40c8082762bLennart Poettering SOCK_STREAM, ...), 0 otherwise. If version is 0 a protocol version
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar check is not done. If type is 0 a socket type check will not be
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar done. If port is 0 a socket port check will not be done. The
b344bcbbfda8fbe14dadc5aa4b5dfb3ced6d76e2Lennart Poettering listening flag is used the same way as in sd_is_socket(). Returns a
ff49bc3212cb07d850dcfd59940539773a0be26fMichal Schmidt negative errno style error code on failure.
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar See sd_is_socket_inet(3) for more information.
ff49bc3212cb07d850dcfd59940539773a0be26fMichal Schmidtint sd_is_socket_inet(int fd, int family, int type, int listening, uint16_t port);
63229aa1abdb98aa69fda9819ed2f40c8082762bLennart Poettering Helper call for identifying a passed file descriptor. Returns 1 if
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar the file descriptor is an AF_UNIX socket of the specified type
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar (SOCK_DGRAM, SOCK_STREAM, ...) and path, 0 otherwise. If type is 0
a34286684ebb78dd3db0d7f34feb2c121c9d00ccMichal Sekletar a socket type check will not be done. If path is NULL a socket path
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering check will not be done. For normal AF_UNIX sockets set length to
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering 0. For abstract namespace sockets set length to the length of the
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering socket name (including the initial 0 byte), and pass the full
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering socket path in path (including the initial 0 byte). The listening
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering flag is used the same way as in sd_is_socket(). Returns a negative
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering errno style error code on failure.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering See sd_is_socket_unix(3) for more information.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poetteringint sd_is_socket_unix(int fd, int type, int listening, const char *path, size_t length);
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Helper call for identifying a passed file descriptor. Returns 1 if
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering the file descriptor is a POSIX Message Queue of the specified name,
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering 0 otherwise. If path is NULL a message queue name check is not
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering done. Returns a negative errno style error code on failure.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering See sd_is_mq(3) for more information.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Informs systemd about changed daemon state. This takes a number of
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering newline separated environment-style variable assignments in a
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering string. The following variables are known:
4d7859d173282e16bb75254c2b4ec14a915ef30bKay Sievers READY=1 Tells systemd that daemon startup is finished (only
e7e55dbdc38f929805ab2407fbd50886043a9e7cDavid Herrmann relevant for services of Type=notify). The passed
9f6eb1cd58f2ddf2eb6ba0e4de056e13d938af75Kay Sievers argument is a boolean "1" or "0". Since there is
9f6eb1cd58f2ddf2eb6ba0e4de056e13d938af75Kay Sievers little value in signaling non-readiness the only
9f6eb1cd58f2ddf2eb6ba0e4de056e13d938af75Kay Sievers value daemons should send is "READY=1".
9f6eb1cd58f2ddf2eb6ba0e4de056e13d938af75Kay Sievers STATUS=... Passes a single-line status string back to systemd
9f6eb1cd58f2ddf2eb6ba0e4de056e13d938af75Kay Sievers that describes the daemon state. This is free-form
9f6eb1cd58f2ddf2eb6ba0e4de056e13d938af75Kay Sievers and can be used for various purposes: general state
9f6eb1cd58f2ddf2eb6ba0e4de056e13d938af75Kay Sievers feedback, fsck-like programs could pass completion
9f6eb1cd58f2ddf2eb6ba0e4de056e13d938af75Kay Sievers percentages and failing programs could pass a human
ffc06c3513d9a0693c7f810d03b20705127ba55aKay Sievers readable error message. Example: "STATUS=Completed
ffc06c3513d9a0693c7f810d03b20705127ba55aKay Sievers 66% of file system check..."
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering ERRNO=... If a daemon fails, the errno-style error code,
ffc06c3513d9a0693c7f810d03b20705127ba55aKay Sievers formatted as string. Example: "ERRNO=2" for ENOENT.
ffc06c3513d9a0693c7f810d03b20705127ba55aKay Sievers BUSERROR=... If a daemon fails, the D-Bus error-style error
ffc06c3513d9a0693c7f810d03b20705127ba55aKay Sievers code. Example: "BUSERROR=org.freedesktop.DBus.Error.TimedOut"
9f6eb1cd58f2ddf2eb6ba0e4de056e13d938af75Kay Sievers MAINPID=... The main pid of a daemon, in case systemd did not
9f6eb1cd58f2ddf2eb6ba0e4de056e13d938af75Kay Sievers fork off the process itself. Example: "MAINPID=4711"
e7e55dbdc38f929805ab2407fbd50886043a9e7cDavid Herrmann WATCHDOG=1 Tells systemd to update the watchdog timestamp.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Services using this feature should do this in
ff9b60f38bf68eba4a47cabff14547d92e083214Torstein Husebø regular intervals. A watchdog framework can use the
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering timestamps to detect failed services. Also see
4d7859d173282e16bb75254c2b4ec14a915ef30bKay Sievers sd_watchdog_enabled() below.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering FDSTORE=1 Store the file descriptors passed along with the
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering message in the per-service file descriptor store,
4d7859d173282e16bb75254c2b4ec14a915ef30bKay Sievers and pass them to the main process again on next
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering invocation. This variable is only supported with
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering sd_pid_notify_with_fds().
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Daemons can choose to send additional variables. However, it is
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering recommended to prefix variable names not listed above with X_.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Returns a negative errno-style error code on failure. Returns > 0
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering if systemd could be notified, 0 if it couldn't possibly because
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering systemd is not running.
151b9b9662a90455262ce575a8a8ae74bf4ff336Lennart Poettering Example: When a daemon finished starting up, it could issue this
151b9b9662a90455262ce575a8a8ae74bf4ff336Lennart Poettering call to notify systemd about it:
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering sd_notify(0, "READY=1");
151b9b9662a90455262ce575a8a8ae74bf4ff336Lennart Poettering See sd_notifyf() for more complete examples.
94676f3e9352cbf1f72e0a512ee0d2ed83ff676dLennart Poettering See sd_notify(3) for more information.
4d7859d173282e16bb75254c2b4ec14a915ef30bKay Sieversint sd_notify(int unset_environment, const char *state);
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Similar to sd_notify() but takes a format string.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Example 1: A daemon could send the following after initialization:
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering sd_notifyf(0, "READY=1\n"
c49b30a23583ff39daaa26696bcab478d2fee0bbLennart Poettering "STATUS=Processing requests...\n"
4d7859d173282e16bb75254c2b4ec14a915ef30bKay Sievers "MAINPID=%lu",
e1636421f46db6d06fbd028ef20a3113fa3e11f8Lennart Poettering (unsigned long) getpid());
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Example 2: A daemon could send the following shortly before
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering exiting, on failure:
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering sd_notifyf(0, "STATUS=Failed to start up: %s\n"
4d7859d173282e16bb75254c2b4ec14a915ef30bKay Sievers strerror(errno),
17d33cecaa762f7e43200307328af5e9135e2091Giovanni Campagna See sd_notifyf(3) for more information.
17d33cecaa762f7e43200307328af5e9135e2091Giovanni Campagnaint sd_notifyf(int unset_environment, const char *format, ...) _sd_printf_(2,3);
f647962d64e844689f3e2acfce6102fc47e76df2Michal Schmidt Similar to sd_notify(), but send the message on behalf of another
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering process, if the appropriate permissions are available.
7c2d80944afb4196f2eff614e8da1450dffcbeaaThomas Hindoe Paaboel Andersenint sd_pid_notify(pid_t pid, int unset_environment, const char *state);
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Similar to sd_notifyf(), but send the message on behalf of another
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering process, if the appropriate permissions are available.
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poetteringint sd_pid_notifyf(pid_t pid, int unset_environment, const char *format, ...) _sd_printf_(3,4);
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Similar to sd_pid_notify(), but also passes the specified fd array
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering to the service manager for storage. This is particularly useful for
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering FDSTORE=1 messages.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poetteringint sd_pid_notify_with_fds(pid_t pid, int unset_environment, const char *state, const int *fds, unsigned n_fds);
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering Returns > 0 if the system was booted with systemd. Returns < 0 on
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering error. Returns 0 if the system was not booted with systemd. Note
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering that all of the functions above handle non-systemd boots just
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering fine. You should NOT protect them with a call to this function. Also
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering note that this function checks whether the system, not the user
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering session is controlled by systemd. However the functions above work
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering for both user and system services.
e1636421f46db6d06fbd028ef20a3113fa3e11f8Lennart Poettering See sd_booted(3) for more information.
4d7859d173282e16bb75254c2b4ec14a915ef30bKay Sievers Returns > 0 if the service manager expects watchdog keep-alive
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering events to be sent regularly via sd_notify(0, "WATCHDOG=1"). Returns
4d7859d173282e16bb75254c2b4ec14a915ef30bKay Sievers 0 if it does not expect this. If the usec argument is non-NULL
e1636421f46db6d06fbd028ef20a3113fa3e11f8Lennart Poettering returns the watchdog timeout in µs after which the service manager
e1636421f46db6d06fbd028ef20a3113fa3e11f8Lennart Poettering will act on a process that has not sent a watchdog keep alive
e1636421f46db6d06fbd028ef20a3113fa3e11f8Lennart Poettering message. This function is useful to implement services that
e1636421f46db6d06fbd028ef20a3113fa3e11f8Lennart Poettering recognize automatically if they are being run under supervision of
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering systemd with WatchdogSec= set. It is recommended for clients to
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering generate keep-alive pings via sd_notify(0, "WATCHDOG=1") every half
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering of the returned time.
2087a7aff26ea5d1bc2c7c29add3275328f36baaLennart Poettering See sd_watchdog_enabled(3) for more information.