From f9378423b9758861850748aeb49ae0d3300e56e6 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 23 Jun 2010 00:31:54 +0200 Subject: [PATCH] man: document sd-daemon.[ch] --- .gitignore | 4 + Makefile.am | 36 +++++- man/sd-daemon.xml | 162 ++++++++++++++++++++++++ man/sd_booted.xml | 122 +++++++++++++++++++ man/sd_is_fifo.xml | 199 ++++++++++++++++++++++++++++++ man/sd_listen_fds.xml | 178 +++++++++++++++++++++++++++ man/sd_notify.xml | 277 ++++++++++++++++++++++++++++++++++++++++++ src/sd-daemon.h | 9 +- 8 files changed, 980 insertions(+), 7 deletions(-) create mode 100644 man/sd-daemon.xml create mode 100644 man/sd_booted.xml create mode 100644 man/sd_is_fifo.xml create mode 100644 man/sd_listen_fds.xml create mode 100644 man/sd_notify.xml diff --git a/.gitignore b/.gitignore index ed881d78..7e44eaa1 100644 --- a/.gitignore +++ b/.gitignore @@ -16,8 +16,10 @@ systemd-logger systemctl systemadm .dirstamp +*.3 *.5 *.7 +*.8 *.html *~ *.tar.gz @@ -45,4 +47,6 @@ stamp-* Makefile ltmain.sh *.tar.bz2 +*.tar.gz +*.tar.xz libtool diff --git a/Makefile.am b/Makefile.am index f1bc0369..0f9ef8ea 100644 --- a/Makefile.am +++ b/Makefile.am @@ -307,7 +307,13 @@ EXTRA_DIST += \ dist_man_MANS = \ man/systemd.unit.5 \ man/systemd.service.5 \ - man/daemon.7 + man/daemon.7 \ + man/systemd.8 \ + man/sd_notify.3 \ + man/sd_booted.3 \ + man/sd_listen_fds.3 \ + man/sd_is_fifo.3 \ + man/sd-daemon.7 nodist_man_MANS = \ man/systemd.special.7 @@ -315,7 +321,13 @@ nodist_man_MANS = \ dist_noinst_DATA = \ man/systemd.unit.html \ man/systemd.service.html \ - man/daemon.html + man/daemon.html \ + man/systemd.html \ + man/sd_notify.html \ + man/sd_booted.html \ + man/sd_listen_fds.html \ + man/sd_is_fifo.html \ + man/sd-daemon.html nodist_noinst_DATA = \ man/systemd.special.html @@ -326,7 +338,13 @@ EXTRA_DIST += \ man/systemd.special.xml.in \ man/systemd.special.7.in \ man/systemd.special.html.in \ - man/daemon.xml + man/daemon.xml \ + man/systemd.xml \ + man/sd_notify.xml \ + man/sd_booted.xml \ + man/sd_listen_fds.xml \ + man/sd_is_fifo.xml \ + man/sd-daemon.xml systemd_SOURCES = \ src/main.c @@ -570,6 +588,12 @@ XSLTPROC_PROCESS_HTML_IN = \ $(XSLTPROC) -o ${@:.in=} --nonet http://docbook.sourceforge.net/release/xsl/current/xhtml-1_1/docbook.xsl $< && \ mv ${@:.in=} $@ +man/%.3: man/%.xml + $(XSLTPROC_PROCESS_MAN) + +man/%.3.in: man/%.xml.in + $(XSLTPROC_PROCESS_MAN) + man/%.5: man/%.xml $(XSLTPROC_PROCESS_MAN) @@ -582,6 +606,12 @@ man/%.7: man/%.xml man/%.7.in: man/%.xml.in $(XSLTPROC_PROCESS_MAN_IN) +man/%.8: man/%.xml + $(XSLTPROC_PROCESS_MAN) + +man/%.8.in: man/%.xml.in + $(XSLTPROC_PROCESS_MAN_IN) + man/%.html: man/%.xml $(XSLTPROC_PROCESS_HTML) diff --git a/man/sd-daemon.xml b/man/sd-daemon.xml new file mode 100644 index 00000000..2acc0210 --- /dev/null +++ b/man/sd-daemon.xml @@ -0,0 +1,162 @@ + + + + + + + + + sd-daemon + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd-daemon + 7 + + + + sd-daemon + Reference implementation of APIs for + new-style daemons + + + + + #include "sd-daemon.h" + + + + + Description + + sd-daemon.c and + sd-daemon.h provide a reference + implementation of various APIs for new-style daemons, + as implemented by the + systemd8 + init system. + + See + sd_listen_fds3, + sd_notify3, + sd_booted3, + sd_is_fifo3 + for more information about the functions + implemented. In addition to these functions a couple + of logging prefixes are defined as macros: + + #define SD_EMERG "<0>" /* system is unusable */ +#define SD_ALERT "<1>" /* action must be taken immediately */ +#define SD_CRIT "<2>" /* critical conditions */ +#define SD_ERR "<3>" /* error conditions */ +#define SD_WARNING "<4>" /* warning conditions */ +#define SD_NOTICE "<5>" /* normal but significant condition */ +#define SD_INFO "<6>" /* informational */ +#define SD_DEBUG "<7>" /* debug-level messages */ + + These prefixes are intended to be used in + conjunction with STDERR-based logging as implemented + by systemd. If a systemd service definition file is + configured with StandardError=syslog + or StandardError=kmsg these + prefixes can be used to encode a log level in lines + printed. This is similar to the kernel + printk()-style logging. See + klogctl2 + for more information. + + The log levels are identical to + syslog3's + log level system. To use these prefixes simply prefix + every line with one of these strings. A line that is + not prefixed will be logged at the default log level + SD_INFO. + + + Hello World + + A daemon may log with the log level + NOTICE by issuing this call: + + fprintf(stderr, SD_NOTICE "Hello World!\n"); + + + + + Notes + + These interfaces are provided by the reference + implementation of APIs for new-style daemons and + distributed with the systemd package. The algorithms + they implement are simple, and can easily be + reimplemented in daemons if it is important to support + this interface without using the reference + implementation. See the respective function man pages + for details. + + In addition, for details about the algorithms + check the liberally licensed reference implementation + sources: + + resp. + + These APIs are implemented in the reference + implementation's drop-in + sd-daemon.c and + sd-daemon.h files. It is + recommended that applications consuming these APIs copy + the implementation into their source tree, either + verbatim or in excerpts. These interfaces are + currently not available in a dynamic library. + + The functions directly related to new-style + daemons become NOPs when -DDISABLE_SYSTEMD is set + during compilation. In addition, if + sd-daemon.c is compiled on + non-Linux systems they become NOPs, too. + + + + See Also + + sd_listen_fds3, + sd_notify3, + sd_booted3, + sd_is_fifo3, + daemon7, + systemd8, + systemd.service5, + systemd.socket5, + fprintf3 + + + + diff --git a/man/sd_booted.xml b/man/sd_booted.xml new file mode 100644 index 00000000..6129a777 --- /dev/null +++ b/man/sd_booted.xml @@ -0,0 +1,122 @@ + + + + + + + + + sd_booted + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_booted + 3 + + + + sd_booted + Test whether the system is running the systemd init system. + + + + + #include "sd-daemon.h" + + + int sd_booted + void + + + + + + Description + sd_booted() checks whether + the system was booted up using the systemd init system. + + + + Return Value + + On failure, this call returns a negative + errno-style error code. If the system was booted up + with systemd as init system this call returns a + postive return value, zero otherwise. + + + + Notes + + This function is provided by the reference + implementation of APIs for new-style daemons and + distributed with the systemd package. The algorithm it + implements is simple, and can easily be reimplemented + in daemons if it is important to support this + interface without using the reference + implementation. + + Internally, this function checks whether the + /cgroup/systemd virtual file + system is mounted, by comparing the st_dev value of + the stat() data of + /cgroup and + /cgroup/systemd. + + For details about the algorithm check the + liberally licensed reference implementation sources: + + resp. + + sd_booted() is implemented + in the reference implementation's drop-in + sd-daemon.c and + sd-daemon.h files. It is + recommended that applications consuming these APIs + copy the implementation into their source tree. For + more details about the reference implementation see + sd_daemon7 + + If -DDISABLE_SYSTEMD is set during compilation + this function will always return 0 and otherwise + become a NOP. + + + + See Also + + sd_daemon7, + systemd8 + + + + diff --git a/man/sd_is_fifo.xml b/man/sd_is_fifo.xml new file mode 100644 index 00000000..23895461 --- /dev/null +++ b/man/sd_is_fifo.xml @@ -0,0 +1,199 @@ + + + + + + + + + sd_is_fifo + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_is_fifo + 3 + + + + sd_is_fifo + sd_is_socket + sd_is_socket_inet + sd_is_socket_unix + Check the type of a file descriptor + + + + + #include "sd-daemon.h" + + + int sd_is_fifo + int fd + const char *path + + + + int sd_is_socket + int fd + int family + int type + int listening + + + + int sd_is_socket_inet + int fd + int family + int type + int listening + uint16_t port + + + + int sd_is_socket_unix + int fd + int type + int listening + const char* path + size_t length + + + + + + + Description + + sd_is_fifo() may be called + to check whether the specified file descriptor refers + to a FIFO or pipe. It the path + parameter is not NULL it is checked whether the FIFO + is bound to the specified file system path. + + sd_is_socket() may be + called to check whether the specified file descriptor + refers to a socket. It the + family parameter is not + AF_UNSPEC it is checked whether the socket is of the + specified family (AF_UNIX, AF_INET, ...). If the + type parameter is not 0 it is + checked whether the socket is of the specified type + (SOCK_STREAM, SOCK_DGRAM, ...). If the + listening parameter is positive + it is checked whether the socket is in accepting mode, + i.e. listen() has been called for + it. If listening is 0, it is + checked whether the socket is not in this mode. If the + parameter is negative, no such check is made. The + listening parameter should only + be used for stream sockets and should be set to a + negative value otherwise. + + sd_is_socket_inet() is + similar to sd_is_socket(), but + optionally checks the IPv4 or IPv6 port number the + socket is bound to, unless port + is zero. For this call family + must be passed as either AF_UNSPEC, AF_INET or + AF_INET6. + + sd_is_socket_unix() is + similar to sd_is_socket(), but + optionally checks the AF_UNIX path the socket is bound + to, unless the path parameter + is NULL. For normal file system AF_UNIX sockets set + the length parameter to 0. For + Linux abstract namespace sockets set the + length to the size of the + address, including the initial 0 byte and set + path to the initial 0 byte of + the socket address. + + + + Return Value + + On failure, these calls return a negative + errno-style error code. If the file descriptor is of + the specified type and bound to the specified address + a positive return value is returned, otherwise + zero. + + + + Notes + + These functions are provided by the reference + implementation of APIs for new-style daemons and + distributed with the systemd package. The algorithms + they implement are simple, and can easily be + reimplemented in daemons if it is important to support + this interface without using the reference + implementation. + + Internally, these function use a combination of + fstat() and + getsockname() to check the file + descriptor type and where it is bound to. + + For details about the algorithm check the + liberally licensed reference implementation sources: + + resp. + + sd_is_fifo() and the + related functions are implemented in the reference + implementation's drop-in + sd-daemon.c and + sd-daemon.h files. It is + recommended that applications consuming these APIs + copy the implementation into their source tree. For + more details about the reference implementation see + sd_daemon7 + + These functions continue to work as described, + even if -DDISABLE_SYSTEMD is set during + compilation. + + + + See Also + + sd_daemon7, + sd_listen_fds3, + systemd8, + systemd.service5, + systemd.socket5 + + + + diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml new file mode 100644 index 00000000..10ea57c9 --- /dev/null +++ b/man/sd_listen_fds.xml @@ -0,0 +1,178 @@ + + + + + + + + + sd_listen_fds + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_listen_fds + 3 + + + + sd_listen_fds + Check for file descriptors passed by the init system. + + + + + #include "sd-daemon.h" + + #define SD_LISTEN_FDS_START 3 + + + int sd_listen_fds + int unset_environment + + + + + + Description + + sd_listen_fds() shall be + called by a daemon to check for file descriptors + passed by the init system as part of the socket-based + activation logic. + + If the unset_environment + parameter is non-zero + sd_listen_fds() will unset the + $LISTEN_FDS/$LISTEN_PID + environment variables before returning (regardless + whether the function call itself succeeded or + not). Further calls to + sd_listen_fds() will then fail, + but the variables are no longer inherited by child + processes. + + If a daemon receives more than one file + descriptor, they will be passed in the same order as + configured in the systemd socket definition + file. Nonetheless it is recommended to verify the + correct socket types before using them. To simplify + this checking the functions + sd_is_fifo3, + sd_is_socket3, + sd_is_socket_inet3, + sd_is_socket_unix3 + are provided. In order to maximize flexibility it is + recommened to make these checks as loose as possible + without allowing incorrect setups. i.e. often the + actual port number a socket is bound to matters little + for the service to work, hence it should not be + verified. On the other hand, whether a socket is a + datagram or stream socket matters a lot for the most + common program logics and should hence be + checked. + + This function call will set the FD_CLOEXEC flag + for all passed file descriptors to avoid further + inheritance to children of the calling process. + + + + Return Value + + On failure, this call returns a negative + errno-style error code. If + $LISTEN_FDS/$LISTEN_PID + was not set or not correctly set for this daemon and + hence no file descriptors received 0 is + returned. Otherwise the number of file descriptors + passed is returned, the application may find them + starting with file descriptor SD_LISTEN_FDS_START, + i.e. file descriptor 3. + + + + Notes + + This function is provided by the reference + implementation of APIs for new-style daemons and + distributed with the systemd package. The algorithm it + implements is simple, and can easily be reimplemented + in daemons if it is important to support this + interface without using the reference + implementation. + + Internally, this function checks whether the + $LISTEN_PID environment variable + equals the daemon PID. If not, it returns + immediately. Otherwise it parses the number passed in + the $LISTEN_FDS environment + variable, then sets the FD_CLOEXEC flag for the parsed + number of file descriptors starting from + SD_LISTEN_FDS_START. Finally it returns the parsed + number. + + For details about the algorithm check the + liberally licensed reference implementation sources: + + resp. + + sd_listen_fds() is + implemented in the reference implementation's drop-in + sd-daemon.c and + sd-daemon.h files. It is + recommended that applications consuming these APIs + copy the implementation into their source tree. For + more details about the reference implementation see + sd_daemon7 + + If -DDISABLE_SYSTEMD is set during compilation + this function will always return 0 and otherwise + become a NOP. + + + + See Also + + + sd_daemon7, + sd_is_fifo3, + sd_is_socket3, + sd_is_socket_inet3, + sd_is_socket_unix3, + daemon7, + systemd8, + systemd.service5, + systemd.socket5 + + + + diff --git a/man/sd_notify.xml b/man/sd_notify.xml new file mode 100644 index 00000000..140e7959 --- /dev/null +++ b/man/sd_notify.xml @@ -0,0 +1,277 @@ + + + + + + + + + sd_notify + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_notify + 3 + + + + sd_notify + sd_notifyf + Notify init system about start-up completion and other daemon status changes + + + + + #include "sd-daemon.h" + + + int sd_notify + int unset_environment + const char *state + + + + int sd_notifyf + int unset_environment + const char *format + ... + + + + + + Description + sd_notify() shall be called + by a daemon to notify the init system about status + changes. It can be used to send arbitrary information, + encoded in an environment-block-like string. Most + importantly it can be used for start-up completion + notification. + + If the unset_environment + parameter is non-zero sd_notify() + will unset the $NOTIFY_SOCKET + environment variable before returning (regardless + whether the function call itself succeeded or + not). Further calls to + sd_notify() will then fail, but + the variable is no longer inherited by child + processes. + + The state parameter + should contain an newline-seperated list of variable + assignments, similar in style to an environment + block. A trailing newline is implied if none is + specified. The string may contain any kind of variable + assignments, but the following shall be considered + well-known: + + + + READY=1 + + Tells the init system + that daemon startup is finished. This + is only used by systemd if the service + definition file has Type=notify + set. The passed argument is a boolean + "1" or "0". Since there is little + value in signalling non-readiness the + only value daemons should send is + "READY=1". + + + + STATUS=... + + Passes a single-line + status string back to the init system + that describes the daemon state. This + is free-from and can be used for + various purposes: general state + feedback, fsck-like programs could + pass completion percentages and + failing programs could pass a human + readable error message. Example: + "STATUS=Completed 66% of file system + check..." + + + + ERRNO=... + + If a daemon fails, the + errno-style error code, formatted as + string. Example: "ERRNO=2" for + ENOENT. + + + + BUSERROR=... + + If a daemon fails, the + D-Bus error-style error code. Example: + "BUSERROR=org.freedesktop.DBus.Error.TimedOut" + + + + MAINPID=... + + The main pid of the + daemon, in case the init system did + not fork off the process + itself. Example: + "MAINPID=4711" + + + + It is recommened to prefix variable names that + are not shown in the list above with + X_ to avoid namespace + clashes. + + Note that systemd will accept status data sent + from a daemon only if the + NotifyAccess= option is correctly + set in the service definition file. See + systemd.service5 + for details. + + sd_notifyf() is similar to + sd_notifyf() but takes a + printf()-like format string plus + arguments. + + + + Return Value + + On failure, these calls return a negative + errno-style error code. If + $NOTIFY_SOCKET was not set and + hence no status data could be sent 0 is returned. If + the status was sent these functions return with a + positive return value. In order to support both init + systems that implement this scheme and those which + don't it is generally recommended to ignore the return + value of this call. + + + + Notes + + These functions are provided by the reference + implementation of APIs for new-style daemons and + distributed with the systemd package. The algorithms + they implement are simple, and can easily be + reimplemented in daemons if it is important to support + this interface without using the reference + implementation. + + Internally, these functions send a single + datagram with the state string as payload to the + AF_UNIX socket referenced in the + $NOTIFY_SOCKET environment + variable. If the first character of + $NOTIFY_SOCKET is @ the string is + understood as Linux abstract namespace socket. The + datagram is accompanied by the process credentials of + the sending daemon, using SCM_CREDENTIALS. + + For details about the algorithm check the + liberally licensed reference implementation sources: + + resp. + + sd_notify() and + sd_notifyf() are implemented in + the reference implementation's drop-in + sd-daemon.c and + sd-daemon.h files. It is + recommended that applications consuming these APIs + copy the implementation into their source tree. For + more details about the reference implementation see + sd_daemon7 + + If -DDISABLE_SYSTEMD is set during compilation + this function will always return 0 and otherwise + become a NOP. + + + + Examples + + + Start-up Notification + + When a daemon finished starting up, it + might issue the following call call to notify + the init system: + + sd_notify(0, "READY=1"); + + + + Extended Start-up Notification + + A daemon could send the following after + completing initialization: + + sd_notifyf(0, "READY=1\n" + "STATUS=Processing requests...\n" + "MAINPID=%lu", + (unsigned long) getpid()); + + + + Error Cause Notification + + A daemon could send the following shortly before exiting, on failure + + sd_notifyf(0, "STATUS=Failed to start up: %s\n" + "ERRNO=%i", + strerror(errno), + errno); + + + + + See Also + + sd_daemon7, + daemon7, + systemd8, + systemd.service5 + + + + diff --git a/src/sd-daemon.h b/src/sd-daemon.h index dc18f42e..56fec98a 100644 --- a/src/sd-daemon.h +++ b/src/sd-daemon.h @@ -76,7 +76,7 @@ extern "C" { /* Log levels for usage on stderr: - fprintf(stderr, SD_NOTICE "Hello World!"); + fprintf(stderr, SD_NOTICE "Hello World!\n"); This is similar to printk() usage in the kernel. */ @@ -158,9 +158,9 @@ int sd_is_socket_inet(int fd, int family, int type, int listening, uint16_t port int sd_is_socket_unix(int fd, int type, int listening, const char *path, size_t length) _sd_hidden_; /* - Informs systemd about changed daemon state. This takes a numeber of + Informs systemd about changed daemon state. This takes a number of newline seperated environment-style variable assignments in a - string. The following strings are known: + string. The following variables are known: READY=1 Tells systemd that daemon startup is finished (only relevant for services of Type=notify). The passed @@ -185,7 +185,8 @@ int sd_is_socket_unix(int fd, int type, int listening, const char *path, size_t MAINPID=... The main pid of a daemon, in case systemd did not fork off the process itself. Example: "MAINPID=4711" - Daemons can choose to send additional variables. + Daemons can choose to send additional variables. However, it is + recommened to prefix variable names not listed above with X_. Returns a negative errno-style error code on failure. Returns > 0 if systemd could be notified, 0 if it couldn't possibly because -- 2.39.5