X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_listen_fds.xml;h=9b9705eb2ee5daaea1c3335a23a46d1b93275e04;hp=4377745634195611b0461d3878cf7cd20d5b98d5;hb=798d3a524ea57aaf40cb53858aaa45ec702f012d;hpb=35888b67f77fa7a5cae0973403cb97aa30cad70c diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index 437774563..9b9705eb2 100644 --- a/man/sd_listen_fds.xml +++ b/man/sd_listen_fds.xml @@ -1,6 +1,6 @@ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - - - sd_listen_fds - systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - - - - - sd_listen_fds - 3 - - - - sd_listen_fds - SD_LISTEN_FDS_START - Check for file descriptors passed by the system manager - - - - - #include <systemd/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 and $LISTEN_PID - environment variables before returning (regardless of - 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 unit file (see - systemd.socket5 - for details). 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 - recommended 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 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. - - If multiple socket units activate the same - service the order of the file descriptors passed to - its main process is undefined. If additional file - descriptors have been passed to the service manager - using - sd_pid_notify_with_fds3's - FDSTORE=1 messages, these file - descriptors are passed last, in arbitrary order, and - with duplicates removed. - - - - Return Value - - On failure, this call returns a negative - errno-style error code. If - $LISTEN_FDS/$LISTEN_PID - was not set or was not correctly set for this daemon and - hence no file descriptors were 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 - - - - 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. - - - - Environment - - - - $LISTEN_PID - $LISTEN_FDS - - Set by the init system - for supervised processes that use - socket-based activation. This - environment variable specifies the - data - sd_listen_fds() - parses. See above for - details. - - - - - - See Also - - - systemd1, - sd-daemon3, - sd_is_fifo3, - sd_is_socket3, - sd_is_socket_inet3, - sd_is_socket_unix3, - daemon7, - systemd.service5, - systemd.socket5 - - + xmlns:xi="http://www.w3.org/2001/XInclude"> + + + sd_listen_fds + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_listen_fds + 3 + + + + sd_listen_fds + SD_LISTEN_FDS_START + Check for file descriptors passed by the system manager + + + + + #include <systemd/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 and $LISTEN_PID + environment variables before returning (regardless of 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 unit file (see + systemd.socket5 + for details). 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 recommended + 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 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. + + If multiple socket units activate the same service the order + of the file descriptors passed to its main process is undefined. + If additional file descriptors have been passed to the service + manager using + sd_pid_notify_with_fds3's + FDSTORE=1 messages, these file descriptors are + passed last, in arbitrary order, and with duplicates + removed. + + + + Return Value + + On failure, this call returns a negative errno-style error + code. If + $LISTEN_FDS/$LISTEN_PID was + not set or was not correctly set for this daemon and hence no file + descriptors were 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 + + + + 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. + + + + Environment + + + + $LISTEN_PID + $LISTEN_FDS + + Set by the init system + for supervised processes that use + socket-based activation. This + environment variable specifies the + data + sd_listen_fds() + parses. See above for + details. + + + + + + See Also + + + systemd1, + sd-daemon3, + sd_is_fifo3, + sd_is_socket3, + sd_is_socket_inet3, + sd_is_socket_unix3, + daemon7, + systemd.service5, + systemd.socket5 + +