X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_listen_fds.xml;h=0d3479efbb7507f1d9e00a0e3a30b5dbc4f3e0f6;hb=76cc80f42e53215b9039ca99dd35687c7518880a;hp=5e906870c759c27598e0261d189b292b6057ad89;hpb=976c46f84f896782fa1e839904ab74cc4460c7b0;p=elogind.git diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index 5e906870c..0d3479efb 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 init system. - - - - - #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/$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 - 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. - - - - 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 - - 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 - sd-daemon.c and - sd-daemon.h files. These - interfaces are available as shared library, which can - be compiled and linked to with the - libsystemd-daemon - pkg-config1 - file. Alternatively, applications consuming these APIs - may copy the implementation into their source - tree. For more details about the reference - implementation see - sd-daemon3. - - If the reference implementation is used as - drop-in files and -DDISABLE_SYSTEMD is set during - compilation this function will always return 0 and - otherwise become a NOP. - - - - 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 - - + + + + sd_listen_fds + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_listen_fds + 3 + + + + sd_listen_fds + sd_listen_fds_with_names + 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 + + + + int sd_listen_fds_with_names + int unset_environment + char*** names + + + + + + Description + + sd_listen_fds() may be invoked by a + daemon to check for file descriptors passed by the service manager as + part of the socket-based activation logic. It returns the number + of received file descriptors. If no file descriptors have been + received, zero is returned. The first file descriptor may be found + at file descriptor number 3 + (i.e. SD_LISTEN_FDS_START), the remaining + descriptors follow at 4, 5, 6, …, if any. + + 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. + + If the unset_environment parameter is + non-zero, sd_listen_fds() will unset the + $LISTEN_FDS, $LISTEN_PID and + $LISTEN_FDNAMES environment variables before + returning (regardless of whether the function call itself + succeeded or not). Further calls to + sd_listen_fds() will then return zero, but the + variables are no longer inherited by child processes. + + sd_listen_fds_with_names() is like + sd_listen_fds(), but optionally also returns + an array of strings with identification names for the passed file + descriptors, if that is available and the + names parameter is non-NULL. This + information is read from the $LISTEN_FDNAMES + variable, which may contain a colon-separated list of names. For + socket-activated services, these names may be configured with the + FileDescriptorName= setting in socket unit + files, see + systemd.socket5 + for details. For file descriptors pushed into the file descriptor + store (see above), the name is set via the + FDNAME= field transmitted via + sd_pid_notify_with_fds(). The primary usecase + for these names are services which accept a variety of file + descriptors which are not recognizable with functions like + sd_is_socket() alone, and thus require + identification via a name. It is recommended to rely on named file + descriptors only if identification via + sd_is_socket() and related calls is not + sufficient. Note that the names used are not unique in any + way. The returned array of strings has as many entries as file + descriptors have been received, plus a final NULL pointer + terminating the array. The caller needs to free the array itself + and each of its elements with libc's free() + call after use. If the names parameter is + NULL, the call is entirely equivalent to + sd_listen_fds(). + + Under specific conditions, the following automatic file + descriptor names are returned: + + + + <command>Special names</command> + + + + + + Name + Description + + + + + unknown + The process received no name for the specific file descriptor from the service manager. + + + + stored + The file descriptor originates in the service manager's per-service file descriptor store, and the FDNAME= field was absent when the file descriptor was submitted to the service manager. + + + + connection + The service was activated in per-connection style using Accept=yes in the socket unit file, and the file descriptor is the connection socket. + + + +
+ + + + + Return Value + + On failure, these calls 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, sd_listen_fds() 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. sd_listen_fds_with_names() does the + same but also parses $LISTEN_FDNAMES if + set. + + + + Environment + + + + $LISTEN_PID + $LISTEN_FDS + $LISTEN_FDNAMES + + Set by the service manager for supervised + processes that use socket-based activation. This environment + variable specifies the data + sd_listen_fds() and + sd_listen_fds_with_names() parses. See + above for details. + + + + + + See Also + + + systemd1, + sd-daemon3, + sd_is_fifo3, + sd_is_socket3, + sd_is_socket_inet3, + sd_is_socket_unix3, + sd_pid_notify_with_fds3, + daemon7, + systemd.service5, + systemd.socket5 + +