From f9378423b9758861850748aeb49ae0d3300e56e6 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 23 Jun 2010 00:31:54 +0200 Subject: man: document sd-daemon.[ch] --- man/sd_listen_fds.xml | 178 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 man/sd_listen_fds.xml (limited to 'man/sd_listen_fds.xml') diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml new file mode 100644 index 0000000000..10ea57c972 --- /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 + + + + -- cgit v1.2.3-54-g00ecf