diff options
author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2015-02-03 21:14:13 -0500 |
---|---|---|
committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2015-02-03 23:11:35 -0500 |
commit | 798d3a524ea57aaf40cb53858aaa45ec702f012d (patch) | |
tree | f9251ab7878a180d464780d514f3ea8d4599fe6e /man/sd_listen_fds.xml | |
parent | 35888b67f77fa7a5cae0973403cb97aa30cad70c (diff) |
Reindent man pages to 2ch
Diffstat (limited to 'man/sd_listen_fds.xml')
-rw-r--r-- | man/sd_listen_fds.xml | 311 |
1 files changed, 151 insertions, 160 deletions
diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index 4377745634..9b9705eb2e 100644 --- a/man/sd_listen_fds.xml +++ b/man/sd_listen_fds.xml @@ -1,6 +1,6 @@ <?xml version='1.0'?> <!--*-nxml-*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,164 +22,155 @@ --> <refentry id="sd_listen_fds" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_listen_fds</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_listen_fds</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_listen_fds</refname> - <refname>SD_LISTEN_FDS_START</refname> - <refpurpose>Check for file descriptors passed by the system manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> - - <funcsynopsisinfo>#define SD_LISTEN_FDS_START 3</funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_listen_fds</function></funcdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_listen_fds()</function> shall be - called by a daemon to check for file descriptors - passed by the init system as part of the socket-based - activation logic.</para> - - <para>If the <parameter>unset_environment</parameter> - parameter is non-zero, - <function>sd_listen_fds()</function> will unset the - <varname>$LISTEN_FDS</varname> and <varname>$LISTEN_PID</varname> - environment variables before returning (regardless of - whether the function call itself succeeded or - not). Further calls to - <function>sd_listen_fds()</function> will then fail, - but the variables are no longer inherited by child - processes.</para> - - <para>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 - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). Nonetheless, it is recommended to verify - the correct socket types before using them. To - simplify this checking, the functions - <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry> - 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.</para> - - <para>This function call will set the FD_CLOEXEC flag - for all passed file descriptors to avoid further - inheritance to children of the calling process.</para> - - <para>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 - <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s - <literal>FDSTORE=1</literal> messages, these file - descriptors are passed last, in arbitrary order, and - with duplicates removed.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On failure, this call returns a negative - errno-style error code. If - <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> - 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.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - - <para>Internally, this function checks whether the - <varname>$LISTEN_PID</varname> environment variable - equals the daemon PID. If not, it returns - immediately. Otherwise, it parses the number passed in - the <varname>$LISTEN_FDS</varname> 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.</para> - </refsect1> - - <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$LISTEN_PID</varname></term> - <term><varname>$LISTEN_FDS</varname></term> - - <listitem><para>Set by the init system - for supervised processes that use - socket-based activation. This - environment variable specifies the - data - <function>sd_listen_fds()</function> - parses. See above for - details.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_listen_fds</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_listen_fds</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_listen_fds</refname> + <refname>SD_LISTEN_FDS_START</refname> + <refpurpose>Check for file descriptors passed by the system manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcsynopsisinfo>#define SD_LISTEN_FDS_START 3</funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_listen_fds</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_listen_fds()</function> shall be called by a + daemon to check for file descriptors passed by the init system as + part of the socket-based activation logic.</para> + + <para>If the <parameter>unset_environment</parameter> parameter is + non-zero, <function>sd_listen_fds()</function> will unset the + <varname>$LISTEN_FDS</varname> and <varname>$LISTEN_PID</varname> + environment variables before returning (regardless of whether the + function call itself succeeded or not). Further calls to + <function>sd_listen_fds()</function> will then fail, but the + variables are no longer inherited by child processes.</para> + + <para>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 + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Nonetheless, it is recommended to verify the correct + socket types before using them. To simplify this checking, the + functions + <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry> + 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.</para> + + <para>This function call will set the FD_CLOEXEC flag for all + passed file descriptors to avoid further inheritance to children + of the calling process.</para> + + <para>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 + <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s + <literal>FDSTORE=1</literal> messages, these file descriptors are + passed last, in arbitrary order, and with duplicates + removed.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, this call returns a negative errno-style error + code. If + <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> 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.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + + <para>Internally, this function checks whether the + <varname>$LISTEN_PID</varname> environment variable equals the + daemon PID. If not, it returns immediately. Otherwise, it parses + the number passed in the <varname>$LISTEN_FDS</varname> + 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.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDS</varname></term> + + <listitem><para>Set by the init system + for supervised processes that use + socket-based activation. This + environment variable specifies the + data + <function>sd_listen_fds()</function> + parses. See above for + details.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> |