diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/sd_listen_fds.xml | 133 | ||||
| -rw-r--r-- | man/sd_notify.xml | 31 | ||||
| -rw-r--r-- | man/systemd-activate.xml | 13 | ||||
| -rw-r--r-- | man/systemd-analyze.xml | 6 | ||||
| -rw-r--r-- | man/systemd.socket.xml | 23 | ||||
| -rw-r--r-- | man/systemd.xml | 1 |
6 files changed, 174 insertions, 33 deletions
diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index 9b9705eb2e..ea55671e4f 100644 --- a/man/sd_listen_fds.xml +++ b/man/sd_listen_fds.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -45,6 +45,7 @@ <refnamediv> <refname>sd_listen_fds</refname> + <refname>sd_listen_fds_with_names</refname> <refname>SD_LISTEN_FDS_START</refname> <refpurpose>Check for file descriptors passed by the system manager</refpurpose> </refnamediv> @@ -59,23 +60,26 @@ <funcdef>int <function>sd_listen_fds</function></funcdef> <paramdef>int <parameter>unset_environment</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_listen_fds_with_names</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>char*** <parameter>names</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><function>sd_listen_fds()</function> 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. <constant>SD_LISTEN_FDS_START</constant>), the remaining + descriptors follow at 4, 5, 6, ..., if any.</para> <para>If a daemon receives more than one file descriptor, they will be passed in the same order as configured in the systemd @@ -108,12 +112,86 @@ <literal>FDSTORE=1</literal> messages, these file descriptors are passed last, in arbitrary order, and with duplicates removed.</para> + + <para>If the <parameter>unset_environment</parameter> parameter is + non-zero, <function>sd_listen_fds()</function> will unset the + <varname>$LISTEN_FDS</varname>, <varname>$LISTEN_PID</varname> and + <varname>$LISTEN_FDNAMES</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 return zero, but the + variables are no longer inherited by child processes.</para> + + <para><function>sd_listen_fds_with_names()</function> is like + <function>sd_listen_fds()</function> but optionally also returns + an array of strings with identification names for the passed file + descriptors, if that is available, and the + <parameter>names</parameter> parameter is non-NULL. This + information is read from the <varname>$LISTEN_FDNAMES</varname> + variable, which may contain a colon-separated list of names. For + socket-activated services, these names may be configured with the + <varname>FileDescriptorName=</varname> setting in socket unit + files, see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. For file descriptors pushed into the file descriptor + store (see above) the name is set via the + <varname>FDNAME=</varname> field transmitted via + <function>sd_pid_notify_with_fds()</function>. The primary usecase + for these names are services which accept a variety of file + descriptors which are not recognizable with functions like + <function>sd_is_socket()</function> alone, and thus require + identification via a name. It is recommended to rely on named file + descriptors only if identification via + <function>sd_is_socket()</function> 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 has 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 <varname>free()</varname> + call after use. If the <parameter>names</parameter> parameter is + NULL the call is entirely equivalent to + <function>sd_listen_fds()</function>.</para> + + <para>Under specific conditions the following automatic file + descriptor names are returned: + + <table> + <title> + <command>Special names</command> + </title> + + <tgroup cols='2'> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>unknown</literal></entry> + <entry>The process received no name for the specific file descriptor from the service manager.</entry> + </row> + + <row> + <entry><literal>stored</literal></entry> + <entry>The file descriptor originates in the service manager's per-service file descriptor store, and the <varname>FDNAME=</varname> field was absent when the file descriptor was submitted to the service manager.</entry> + </row> + + <row> + <entry><literal>connection</literal></entry> + <entry>The service was activated in per-connection style using <varname>Accept=yes</varname> in the socket unit file, and the file descriptor is the connection socket.</entry> + </row> + </tbody> + </tgroup> + </table> + </para> </refsect1> <refsect1> <title>Return Value</title> - <para>On failure, this call returns a negative errno-style error + <para>On failure, these calls 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 @@ -128,13 +206,16 @@ <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> + <para>Internally, <function>sd_listen_fds()</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> + Finally, it returns the parsed + number. <function>sd_listen_fds_with_names()</function> does the + same but also parses <varname>$LISTEN_FDNAMES</varname> if + set.</para> </refsect1> <refsect1> @@ -144,15 +225,14 @@ <varlistentry> <term><varname>$LISTEN_PID</varname></term> <term><varname>$LISTEN_FDS</varname></term> + <term><varname>$LISTEN_FDNAMES</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> + <listitem><para>Set by the service manager for supervised + processes that use socket-based activation. This environment + variable specifies the data + <function>sd_listen_fds()</function> and + <function>sd_listen_fds_with_names()</function> parses. See + above for details.</para></listitem> </varlistentry> </variablelist> </refsect1> @@ -167,6 +247,7 @@ <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>sd_pid_notify_with_fds</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> diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 14030f56b1..2d73c27f62 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -229,6 +229,27 @@ below.</para></listitem> </varlistentry> + <varlistentry> + <term>FDNAME=...</term> + + <listitem><para>When used in combination with + <varname>FDSTORE=1</varname> specifies a name for the + submitted file descriptors. This name is passed to the service + during activation, and may be queried using + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File + descriptors submitted without this field set, will implicitly + get the name <literal>stored</literal> assigned. Note that if + multiple file descriptors are submitted at once the specified + name will be assigned to all of them. In order to assign + different names to submitted file descriptors, submit them in + seperate invocations of + <function>sd_pid_notify_with_fds()</function>. The name may + consist of any ASCII characters, but must not contain control + characters or <literal>:</literal>. It may not be longer than + 255 characters. If a submitted name does not follow these + restrictions it is ignored.</para></listitem> + </varlistentry> + </variablelist> <para>It is recommended to prefix variable names that are not @@ -358,7 +379,7 @@ in order to continue operation after a service restart without losing state use <literal>FDSTORE=1</literal>:</para> - <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);</programlisting> + <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting> </example> </refsect1> @@ -367,9 +388,11 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd-activate.xml b/man/systemd-activate.xml index 3b854fd8ec..90e974c991 100644 --- a/man/systemd-activate.xml +++ b/man/systemd-activate.xml @@ -115,6 +115,16 @@ </para></listitem> </varlistentry> + <varlistentry> + <term><option>--fdname=</option><replaceable>NAME</replaceable></term> + + <listitem><para>Specify a name for the activation file + descriptors. This is equivalent to setting + <varname>FileDescriptorName=</varname> in socket unit files, and + enables use of + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -126,6 +136,7 @@ <varlistentry> <term><varname>$LISTEN_FDS</varname></term> <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> <listitem><para>See <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> @@ -165,6 +176,8 @@ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>cat</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml index 632e6363f6..d2db265f58 100644 --- a/man/systemd-analyze.xml +++ b/man/systemd-analyze.xml @@ -98,6 +98,12 @@ <cmdsynopsis> <command>systemd-analyze</command> <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">set-log-target</arg> + <arg choice="plain"><replaceable>TARGET</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain">verify</arg> <arg choice="opt" rep="repeat"><replaceable>FILES</replaceable></arg> </cmdsynopsis> diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 212764075d..46a47b2d95 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -748,6 +748,22 @@ list.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>FileDescriptorName=</varname></term> + <listitem><para>Assigns a name to all file descriptors this + socket unit encapsulates. This is useful to help activated + services to identify specific file descriptors, if multiple + are passed. Services may use the + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call to acquire the names configured for the received file + descriptors. Names may contain any ASCII character, but must + exclude control characters or <literal>:</literal>, and must + be at most 255 characters in length. If this setting is not + used the file descriptor name defaults to the name of the + socket unit, including its <filename>.socket</filename> + suffix.</para></listitem> + </varlistentry> + </variablelist> <para>Check @@ -768,9 +784,10 @@ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> - <para> For more extensive descriptions see the "systemd for Developers" series: <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>, diff --git a/man/systemd.xml b/man/systemd.xml index 9e927c3204..391333bfb4 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -835,6 +835,7 @@ <varlistentry> <term><varname>$LISTEN_PID</varname></term> <term><varname>$LISTEN_FDS</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> <listitem><para>Set by systemd for supervised processes during socket-based activation. See |