diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/sd-bus.xml | 51 | ||||
| -rw-r--r-- | man/sd_bus_creds_new_from_pid.xml | 4 | ||||
| -rw-r--r-- | man/sd_bus_track_add_name.xml | 261 | ||||
| -rw-r--r-- | man/sd_bus_track_new.xml | 263 | ||||
| -rw-r--r-- | man/systemctl.xml | 12 | ||||
| -rw-r--r-- | man/systemd-run.xml | 165 | ||||
| -rw-r--r-- | man/systemd.mount.xml | 13 |
7 files changed, 637 insertions, 132 deletions
diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 336dd33ea0..66b1c96c15 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -44,7 +44,7 @@ <refnamediv> <refname>sd-bus</refname> - <refpurpose>A lightweight D-Bus and kdbus client library</refpurpose> + <refpurpose>A lightweight D-Bus IPC client library</refpurpose> </refnamediv> <refsynopsisdiv> @@ -61,49 +61,40 @@ <refsect1> <title>Description</title> - <para><filename>sd-bus.h</filename> provides an implementation - of a D-Bus client. It can interoperate both with the traditional - <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - and with kdbus. See + <para><filename>sd-bus.h</filename> provides an implementation of a D-Bus IPC client. See <ulink url="http://www.freedesktop.org/software/dbus/" /> - for more information about the big picture. + for more information about D-Bus IPC. </para> - <important> - <para>Interfaces described here have not been declared stable yet, - and are not accessible from <filename>libsystemd.so</filename>. - This documentation is provided in hope it might be useful for - developers, without any guarantees of availability or stability. - </para> - </important> - <para>See + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append_string_memfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append_strv</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_cookie</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_negotiate_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry> <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_negotiate_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, for more information about the functions available.</para> </refsect1> @@ -114,9 +105,9 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <ulink url="https://developer.gnome.org/gio/stable/gdbus.html">gdbus</ulink> + <citerefentry project='man-pages'><refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_bus_creds_new_from_pid.xml b/man/sd_bus_creds_new_from_pid.xml index 082f7b67db..b4d7d61d0f 100644 --- a/man/sd_bus_creds_new_from_pid.xml +++ b/man/sd_bus_creds_new_from_pid.xml @@ -66,12 +66,12 @@ <funcprototype> <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef> - <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> </funcprototype> <funcprototype> <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef> - <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> </funcprototype> <funcprototype> diff --git a/man/sd_bus_track_add_name.xml b/man/sd_bus_track_add_name.xml new file mode 100644 index 0000000000..6a5e344cb1 --- /dev/null +++ b/man/sd_bus_track_add_name.xml @@ -0,0 +1,261 @@ +<?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"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_track_add_name"> + + <refentryinfo> + <title>sd_bus_track_add_name</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_bus_track_add_name</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_track_add_name</refname> + <refname>sd_bus_track_add_sender</refname> + <refname>sd_bus_track_remove_name</refname> + <refname>sd_bus_track_remove_sender</refname> + <refname>sd_bus_track_count</refname> + <refname>sd_bus_track_count_sender</refname> + <refname>sd_bus_track_count_name</refname> + <refname>sd_bus_track_contains</refname> + <refname>sd_bus_track_first</refname> + <refname>sd_bus_track_next</refname> + + <refpurpose>Add, remove and retrieve bus peers tracked in a bus peer tracking object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_track_add_name</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_add_sender</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>sd_bus_message* <parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_remove_name</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_remove_sender</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>sd_bus_message* <parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>unsigned <function>sd_bus_track_count</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_count_name</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_count_sender</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>sd_bus_message* <parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_contains</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char* <function>sd_bus_track_first</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char* <function>sd_bus_track_next</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_track_add_name()</function> adds a peer to track to a bus peer tracking object. The first + argument should refer to a bus peer tracking object created with + <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, the second + name should refer to a D-Bus peer name to track, either in unique or well-known service format. If the name is not + tracked yet it will be added to the list of names to track. If it already is being tracked and non-recursive mode + is enabled, no operation is executed by this call. If recursive mode is enabled a per-name counter is increased by + one each time this call is invoked, and <function>sd_bus_track_remove_name()</function> has to be called as many + times as <function>sd_bus_track_add_name()</function> was invoked before in order to stop tracking of the name. Use + <citerefentry><refentrytitle>sd_bus_track_set_recursive</refentrytitle><manvolnum>3</manvolnum></citerefentry> to + switch from the default non-recursive mode to recursive mode, or back. Note that the specified name is tracked as + it is, well-known names are not resolved to unique names by this call. Note that multiple bus peer tracking objects + may track the same name.</para> + + <para><function>sd_bus_track_remove_name()</function> undoes the effect of + <function>sd_bus_track_add_name()</function> and removes a bus peer name from the list of peers to watch. Depending + on whether non-recursive or recursive mode is enabled for the bus peer tracking object this call will either remove + the name fully from the tracking object, or will simply decrement the per-name counter by one, removing the name + only when the counter reaches zero (see above). Note that a bus peer disconnecting from the bus will implicitly + remove its names fully from the bus peer tracking object, regardless of the current per-name counter.</para> + + <para><function>sd_bus_track_add_sender()</function> and <function>sd_bus_track_remove_sender()</function> are + similar to <function>sd_bus_track_add_name()</function> and <function>sd_bus_track_remove_name()</function> but + take a bus message as argument. The sender of this bus message is determined and added to/removed from the bus peer + tracking object. As messages always originate from unique names, and never from well-known names this means that + this call will effectively only add unique names to the bus peer tracking object.</para> + + <para><function>sd_bus_track_count()</function> returns the number of names currently being tracked by the + specified bus peer tracking object. Note that this function always returns the actual number of names tracked, and + hence if <function>sd_bus_track_add_name()</function> has been invoked multiple times for the same name it is only + counted as one, regardless if recursive mode is used or not.</para> + + <para><function>sd_bus_track_count_name()</function> returns the current per-name counter for the specified + name. If non-recursive mode is used this returns either 1 or 0, depending on whether the specified name has been + added to the tracking object before, or not. If recursive mode has been enabled, values larger than 1 may be + returned too, in case <function>sd_bus_track_add_name()</function> has been called multiple times for the same + name.</para> + + <para><function>sd_bus_track_count_sender()</function> is similar to + <function>sd_bus_track_count_name()</function>, but takes a bus message object and returns the per-name counter + matching the sender of the message.</para> + + <para><function>sd_bus_track_contains()</function> may be used to determine whether the specified name has been + added at least once to the specified bus peer tracking object.</para> + + <para><function>sd_bus_track_first()</function> and <function>sd_bus_track_next()</function> may be used to + enumerate all names currently being tracked by the passed bus peer tracking + object. <function>sd_bus_track_first()</function> returns the first entry in the object, and resets an internally + maintained read index. Each subsequent invocation of <function>sd_bus_track_next()</function> returns the next name + contained in the bus object. If the end is reached <constant>NULL</constant> is returned. If no names have been + added to the object yet <function>sd_bus_track_first()</function> will return <constant>NULL</constant> + immediately. The order in which names are returned is undefined; in particular which name is considered the first + returned is not defined. If recursive mode is enabled and the same name has been added multiple times to the bus + peer tracking object it is only returned once by this enumeration. If new names are added to or existing names + removed from the bus peer tracking object while it is being enumerated the enumeration ends on the next invocation + of <function>sd_bus_track_next()</function> as <constant>NULL</constant> is returned.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_track_add_name()</function> and <function>sd_bus_track_add_sender()</function> + return 0 if the specified name has already been added to the bus peer tracking object before and positive if it + hasn't. On failure, they return a negative errno-style error code.</para> + + <para><function>sd_bus_track_remove_name()</function> and <function>sd_bus_track_remove_sender()</function> return + positive if the specified name was previously tracked by the bus peer tracking object and has now been removed. In + non-recursive mode, 0 is returned if the specified name was not being tracked yet. In recursive mode + <constant>-EUNATCH</constant> is returned in this case. On failure, they return a negative errno-style error + code.</para> + + <para><function>sd_bus_track_count()</function> returns the number of names currently being tracked, or 0 on + failure.</para> + + <para><function>sd_bus_track_count_name()</function> and <function>sd_bus_track_count_sender()</function> return + the current per-name counter for the specified name or the sender of the specified message. Zero is returned for + names that are not being tracked yet, a positive value for names added at least once. Larger values than 1 are only + returned in recursive mode. On failure, a negative errno-style error code is returned.</para> + + <para><function>sd_bus_track_contains()</function> returns the passed name if it exists in the bus peer tracking + object. On failure, and if the name has not been added yet <constant>NULL</constant> is returned.</para> + + <para><function>sd_bus_track_first()</function> and <function>sd_bus_track_next()</function> return the first/next + name contained in the bus peer tracking object, and <constant>NULL</constant> if the end of the enumeration is + reached and on error.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EUNATCH</constant></term> + + <listitem><para><function>sd_bus_track_remove_name()</function> or + <function>sd_bus_track_remove_sender()</function> have been invoked for a name not previously added to the bus + peer object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified parameter is invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_track_add_name()</function> and the other calls described here are available as a shared library, + which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_track_new.xml b/man/sd_bus_track_new.xml new file mode 100644 index 0000000000..60e2e77f75 --- /dev/null +++ b/man/sd_bus_track_new.xml @@ -0,0 +1,263 @@ +<?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"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_track_new"> + + <refentryinfo> + <title>sd_bus_track_new</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_bus_track_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_track_new</refname> + <refname>sd_bus_track_ref</refname> + <refname>sd_bus_track_unref</refname> + <refname>sd_bus_track_unrefp</refname> + <refname>sd_bus_track_set_recursive</refname> + <refname>sd_bus_track_get_recursive</refname> + <refname>sd_bus_track_get_bus</refname> + <refname>sd_bus_track_get_userdata</refname> + <refname>sd_bus_track_set_userdata</refname> + + <refpurpose>Track bus peers</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_track_new</function></funcdef> + <paramdef>sd_bus* <parameter>bus</parameter></paramdef> + <paramdef>sd_bus_track** <parameter>ret</parameter></paramdef> + <paramdef>sd_bus_track_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void* <parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_track *<function>sd_bus_track_ref</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_track *<function>sd_bus_track_unref</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_track_unrefp</function></funcdef> + <paramdef>sd_bus_track **<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_get_recursive</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_set_recursive</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus* <function>sd_bus_track_get_bus</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void* <function>sd_bus_track_get_userdata</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void* <function>sd_bus_track_set_userdata</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + <paramdef>void *userdata</paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_track_new()</function> creates a new bus peer tracking object. The object is allocated for + the specified bus, and returned in the <parameter>*ret</parameter> parameter. After use, the object should be freed + again by dropping the acquired reference with <function>sd_bus_track_unref()</function> (see below). A bus peer + tracking object may be used to keep track of peers on a specific IPC bus, for cases where peers are making use of + one or more local objects, in order to control the lifecycle of the local objects and ensure they stay around as + long as the peers needing them are around, and unreferenced (and possibly destroyed) as soon as all relevant peers + have vanished. Each bus peer tracking object may be used to track zero, one or more peers add a time. References to + specific bus peers are added via + <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> or + <function>sd_bus_track_add_sender()</function>. They may be dropped again via + <function>sd_bus_track_remove_name()</function> and + <function>sd_bus_track_remove_sender()</function>. Alternatively, references on peers are removed automatically + when they disconnect from the bus. If non-NULL the <parameter>handler</parameter> may specify a function that is + invoked whenever the last reference is dropped, regardless whether the reference is dropped explicitly via + <function>sd_bus_track_remove_name()</function> or implicitly because the peer disconnected from the bus. The final + argument <parameter>userdata</parameter> may be used to attach a generic user data pointer to the object. This + pointer is passed to the handler callback when it is invoked.</para> + + <para><function>sd_bus_track_ref()</function> creates a new reference to a bus peer tracking object. This object + will not be destroyed until <function>sd_bus_track_unref()</function> has been called as many times plus once + more. Once the reference count has dropped to zero, the specified object cannot be used anymore, further calls to + <function>sd_bus_track_ref()</function> or <function>sd_bus_track_unref()</function> on the same object are + illegal.</para> + + <para><function>sd_bus_track_unref()</function> destroys a reference to a bus peer tracking object.</para> + + <para><function>sd_bus_track_unrefp()</function> is similar to <function>sd_bus_track_unref()</function> but takes + a pointer to a pointer to an <type>sd_bus_track</type> object. This call is useful in conjunction with GCC's and + LLVM's <ulink url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up Variable + Attribute</ulink>. Note that this function is defined as inline function.</para> + + <para><function>sd_bus_track_ref()</function>, <function>sd_bus_track_unref()</function> and + <function>sd_bus_track_unrefp()</function> execute no operation if the passed in bus peer tracking object is + <constant>NULL</constant>.</para> + + <para>Bus peer tracking objects may exist in two modes: by default they operate in non-recursive mode, but may + optionally be switched into recursive mode. If operating in the default non-recursive mode a peer is either tracked + or not tracked. In this mode invoking <function>sd_bus_track_add_name()</function> multiple times in a row for the + same peer is fully equivalent to calling it just once, as the call adds the peer to the set of tracked peers if + necessary, and executes no operation if the peer is already being tracked. A single invocation of + <function>sd_bus_track_remove_name()</function> removes the reference on the peer again, regardless how many times + <function>sd_bus_track_add_name()</function> was called before. If operating in recursive mode, the number of times + <function>sd_bus_track_add_name()</function> is invoked for the same peer name is counted and + <function>sd_bus_track_remove_name()</function> must be called the same number of times before the peer is not + tracked anymore, with the exception when the tracked peer vanishes from the bus, in which case the count is + irrelevant and the tracking of the specific peer is immediately + removed. <function>sd_bus_track_get_recursive()</function> may be used to determine whether the bus peer tracking + object is operating in recursive mode. <function>sd_bus_track_set_recursive()</function> may be used to enable or + disable recursive mode. By default a bus peer tracking object operates in non-recursive mode, and + <function>sd_bus_track_get_recursive()</function> for a newly allocated object hence returns a value equal to + zero. Use <function>sd_bus_track_set_recursive()</function> to enable recursive mode, right after allocation. It + takes a boolean argument to enable or disable recursive mode. Note that tracking objects for which + <function>sd_bus_track_add_name()</function> was already invoked at least once (and which hence track already one + or more peers) may not be switched from recursive to non-recursive mode anymore.</para> + + <para><function>sd_bus_track_get_bus()</function> returns the bus object the bus peer tracking object belongs + to. It returns the bus object initially passed to <function>sd_bus_track_new()</function> when the object was + allocated.</para> + + <para><function>sd_bus_track_get_userdata()</function> returns the generic user data pointer set on the bus peer + tracking object at the time of creation using <function>sd_bus_track_new()</function> or at a later time, using + <function>sd_bus_track_set_userdata()</function>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_track_new()</function> and <function>sd_bus_track_set_recursive()</function> + return 0 or a positive integer. On failure, they return a negative errno-style error code.</para> + + <para><function>sd_bus_track_ref()</function> always returns the argument.</para> + + <para><function>sd_bus_track_unref()</function> always returns <constant>NULL</constant>.</para> + + <para><function>sd_bus_track_get_recursive()</function> returns 0 if non-recursive mode is selected (default), and + greater than 0 if recursive mode is selected. On failure a negative errno-style error code is returned.</para> + + <para><function>sd_bus_track_get_bus()</function> returns the bus object associated to the bus peer tracking + object.</para> + + <para><function>sd_bus_track_get_userdata()</function> returns the generic user data pointer associated with the + bus peer tracking object. <function>sd_bus_track_set_userdata()</function> returns the previous user data pointer + set.</para> + + </refsect1> + + <refsect1> + <title>Reference ownership</title> + + <para>The <function>sd_bus_track_new()</function> function creates a new object and the caller owns the sole + reference. When not needed anymore, this reference should be destroyed with + <function>sd_bus_track_unref()</function>. + </para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EBUSY</constant></term> + + <listitem><para>Bus peers have already been added to the bus peer tracking object and + <function>sd_bus_track_set_recursive()</function> was called to change tracking mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified parameter is invalid + (<constant>NULL</constant> in case of output + parameters).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_track_new()</function> and the other calls described here are available as a shared library, + which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemctl.xml b/man/systemctl.xml index fde4f4f3bb..7e0ac9613a 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -642,13 +642,13 @@ <term><command>list-units <optional><replaceable>PATTERN</replaceable>...</optional></command></term> <listitem> - <para>List units that <command>systemd</command> has loaded. This includes units that - are either referenced directly or through a dependency, or units that were active in the - past and have failed. By default only units which are active, have pending jobs, or have + <para>List units that <command>systemd</command> has loaded. This includes units that are either referenced + directly or through a dependency, units that are pinned by applications programmatically, or units that + were active in the past and have failed. By default only units which are active, have pending jobs, or have failed are shown; this can be changed with option <option>--all</option>. If one or more - <replaceable>PATTERN</replaceable>s are specified, only units matching one of them are - shown. The units that are shown are additionally filtered by <option>--type=</option> - and <option>--state=</option> if those options are specified.</para> + <replaceable>PATTERN</replaceable>s are specified, only units matching one of them are shown. The units + that are shown are additionally filtered by <option>--type=</option> and <option>--state=</option> if those + options are specified.</para> <para>This is the default command.</para> </listitem> diff --git a/man/systemd-run.xml b/man/systemd-run.xml index 56d585cdf9..15f9119e54 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -68,42 +68,30 @@ <refsect1> <title>Description</title> - <para><command>systemd-run</command> may be used to create and - start a transient <filename>.service</filename> or - <filename>.scope</filename> unit and run the specified - <replaceable>COMMAND</replaceable> in it. It may also be used to - create and start transient <filename>.timer</filename> - units.</para> - - <para>If a command is run as transient service unit, it will be - started and managed by the service manager like any other service, - and thus shows up in the output of <command>systemctl - list-units</command> like any other unit. It will run in a clean - and detached execution environment, with the service manager as - its parent process. In this mode, <command>systemd-run</command> - will start the service asynchronously in the background and return - after the command has begun execution.</para> - - <para>If a command is run as transient scope unit, it will be - started by <command>systemd-run</command> itself as parent process - and will thus inherit the execution environment of the - caller. However, the processes of the command are managed by the - service manager similar to normal services, and will show up in - the output of <command>systemctl list-units</command>. Execution - in this case is synchronous, and will return only when the command - finishes. This mode is enabled via the <option>--scope</option> - switch (see below). </para> - - <para>If a command is run with timer options such as - <option>--on-calendar=</option> (see below), a transient timer - unit is created alongside the service unit for the specified - command. Only the transient timer unit is started immediately, the - transient service unit will be started when the transient timer - elapses. If the <option>--unit=</option> is specified, the - <replaceable>COMMAND</replaceable> may be omitted. In this case, - <command>systemd-run</command> only creates a - <filename>.timer</filename> unit that invokes the specified unit - when elapsing.</para> + <para><command>systemd-run</command> may be used to create and start a transient <filename>.service</filename> or + <filename>.scope</filename> unit and run the specified <replaceable>COMMAND</replaceable> in it. It may also be + used to create and start a transient <filename>.timer</filename> unit, that activates a + <filename>.service</filename> unit when elapsing.</para> + + <para>If a command is run as transient service unit, it will be started and managed by the service manager like any + other service, and thus shows up in the output of <command>systemctl list-units</command> like any other unit. It + will run in a clean and detached execution environment, with the service manager as its parent process. In this + mode, <command>systemd-run</command> will start the service asynchronously in the background and return after the + command has begun execution (unless <option>--no-block</option> or <option>--watch</option> are specified, see + below).</para> + + <para>If a command is run as transient scope unit, it will be executed by <command>systemd-run</command> itself as + parent process and will thus inherit the execution environment of the caller. However, the processes of the command + are managed by the service manager similar to normal services, and will show up in the output of <command>systemctl + list-units</command>. Execution in this case is synchronous, and will return only when the command finishes. This + mode is enabled via the <option>--scope</option> switch (see below). </para> + + <para>If a command is run with timer options such as <option>--on-calendar=</option> (see below), a transient timer + unit is created alongside the service unit for the specified command. Only the transient timer unit is started + immediately, the transient service unit will be started when the timer elapses. If the <option>--unit=</option> + option is specified, the <replaceable>COMMAND</replaceable> may be omitted. In this case, + <command>systemd-run</command> creates only a <filename>.timer</filename> unit that invokes the specified unit when + elapsing.</para> </refsect1> <refsect1> @@ -123,8 +111,8 @@ <term><option>--scope</option></term> <listitem> - <para>Create a transient <filename>.scope</filename> unit instead of - the default transient <filename>.service</filename> unit. + <para>Create a transient <filename>.scope</filename> unit instead of the default transient + <filename>.service</filename> unit (see above). </para> </listitem> </varlistentry> @@ -140,9 +128,8 @@ <term><option>--property=</option></term> <term><option>-p</option></term> - <listitem><para>Sets a unit property for the scope or service - unit that is created. This takes an assignment in the same - format as + <listitem><para>Sets a property on the scope or service unit that is created. This option takes an assignment + in the same format as <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s <command>set-property</command> command.</para> </listitem> @@ -151,9 +138,8 @@ <varlistentry> <term><option>--description=</option></term> - <listitem><para>Provide a description for the service or scope - unit. If not specified, the command itself will be used as a - description. See <varname>Description=</varname> in + <listitem><para>Provide a description for the service, scope or timer unit. If not specified, the command + itself will be used as a description. See <varname>Description=</varname> in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para></listitem> </varlistentry> @@ -161,19 +147,16 @@ <varlistentry> <term><option>--slice=</option></term> - <listitem><para>Make the new <filename>.service</filename> or - <filename>.scope</filename> unit part of the specified slice, - instead of the <filename>system.slice</filename>.</para> + <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part of the + specified slice, instead of <filename>system.slice</filename>.</para> </listitem> </varlistentry> <varlistentry> <term><option>--remain-after-exit</option></term> - <listitem><para>After the service or scope process has - terminated, keep the service around until it is explicitly - stopped. This is useful to collect runtime information about - the service after it finished running. Also see + <listitem><para>After the service process has terminated, keep the service around until it is explicitly + stopped. This is useful to collect runtime information about the service after it finished running. Also see <varname>RemainAfterExit=</varname> in <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> @@ -183,10 +166,8 @@ <varlistentry> <term><option>--send-sighup</option></term> - <listitem><para>When terminating the scope or service unit, - send a SIGHUP immediately after SIGTERM. This is useful to - indicate to shells and shell-like processes that the - connection has been severed. Also see + <listitem><para>When terminating the scope or service unit, send a SIGHUP immediately after SIGTERM. This is + useful to indicate to shells and shell-like processes that the connection has been severed. Also see <varname>SendSIGHUP=</varname> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> @@ -209,9 +190,8 @@ <term><option>--uid=</option></term> <term><option>--gid=</option></term> - <listitem><para>Runs the service process under the UNIX user - and group. Also see <varname>User=</varname> and - <varname>Group=</varname> in + <listitem><para>Runs the service process under the specified UNIX user and group. Also see + <varname>User=</varname> and <varname>Group=</varname> in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> @@ -239,11 +219,9 @@ <term><option>--pty</option></term> <term><option>-t</option></term> - <listitem><para>When invoking a command, the service connects - its standard input and output to the invoking tty via a - pseudo TTY device. This allows invoking binaries as services - that expect interactive user input, such as interactive - command shells.</para></listitem> + <listitem><para>When invoking the command, the transient service connects its standard input and output to the + terminal <command>systemd-run</command> is invoked on, via a pseudo TTY device. This allows running binaries + that expect interactive user input as services, such as interactive command shells.</para></listitem> </varlistentry> <varlistentry> @@ -263,44 +241,32 @@ <term><option>--on-unit-active=</option></term> <term><option>--on-unit-inactive=</option></term> - <listitem><para>Defines monotonic timers relative to different - starting points. Also see <varname>OnActiveSec=</varname>, - <varname>OnBootSec=</varname>, - <varname>OnStartupSec=</varname>, - <varname>OnUnitActiveSec=</varname> and - <varname>OnUnitInactiveSec=</varname> in - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This - options have no effect in conjunction with - <option>--scope</option>.</para> + <listitem><para>Defines a monotonic timer relative to different starting points for starting the specified + command. See <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>, + <varname>OnUnitActiveSec=</varname> and <varname>OnUnitInactiveSec=</varname> in + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details. These options may not be combined with <option>--scope</option>.</para> </listitem> </varlistentry> <varlistentry> <term><option>--on-calendar=</option></term> - <listitem><para>Defines realtime (i.e. wallclock) timers with - calendar event expressions. Also see - <varname>OnCalendar=</varname> in - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This - option has no effect in conjunction with - <option>--scope</option>.</para> + <listitem><para>Defines a calendar timer for starting the specified command. See <varname>OnCalendar=</varname> + in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This + option may not be combined with <option>--scope</option>.</para> </listitem> </varlistentry> <varlistentry> <term><option>--timer-property=</option></term> - <listitem><para>Sets a timer unit property for the timer unit - that is created. It is similar with - <option>--property</option> but only for created timer - unit. This option only has effect in conjunction with - <option>--on-active=</option>, <option>--on-boot=</option>, - <option>--on-startup=</option>, - <option>--on-unit-active=</option>, - <option>--on-unit-inactive=</option>, - <option>--on-calendar=</option>. This takes an assignment in - the same format as - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <listitem><para>Sets a property on the timer unit that is created. This option is similar to + <option>--property=</option> but applies to the transient timer unit rather than the transient service unit + created. This option only has an effect in conjunction with <option>--on-active=</option>, + <option>--on-boot=</option>, <option>--on-startup=</option>, <option>--on-unit-active=</option>, + <option>--on-unit-inactive=</option> or <option>--on-calendar=</option>. This option takes an assignment in the + same format as <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s <command>set-property</command> command.</para> </listitem> </varlistentry> @@ -308,14 +274,25 @@ <term><option>--no-block</option></term> <listitem> - <para>Do not synchronously wait for the requested operation - to finish. If this is not specified, the job will be - verified, enqueued and <command>systemd-run</command> will - wait until the unit's start-up is completed. By passing this - argument, it is only verified and enqueued.</para> + <para>Do not synchronously wait for the unit start operation to finish. If this option is not specified, the + start request for the transient unit will be verified, enqueued and <command>systemd-run</command> will wait + until the unit's start-up is completed. By passing this argument, it is only verified and enqueued. This + option may not be combined with <option>--wait</option>.</para> </listitem> </varlistentry> + <varlistentry> + <term><option>--wait</option></term> + + <listitem><para>Synchronously wait for the transient service to terminate. If this option is specified, the + start request for the transient unit is verified, enqueued, and waited for. Subsequently the invoked unit is + monitored, and it is waited until it is deactivated again (most likely because the specified command + completed). On exit, terse information about the unit's runtime is shown, including total runtime (as well as + CPU usage, if <option>--property=CPUAccounting=1</option> was set) and the exit code and status of the main + process. This output may be suppressed with <option>--quiet</option>. This option may not be combined with + <option>--no-block</option>, <option>--scope</option> or the various timer options.</para></listitem> + </varlistentry> + <xi:include href="user-system-options.xml" xpointer="user" /> <xi:include href="user-system-options.xml" xpointer="system" /> <xi:include href="user-system-options.xml" xpointer="host" /> diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml index a38165f9b9..fa17f22dc3 100644 --- a/man/systemd.mount.xml +++ b/man/systemd.mount.xml @@ -352,6 +352,19 @@ </varlistentry> <varlistentry> + <term><varname>LazyUnmount=</varname></term> + + <listitem><para>Takes a boolean argument. If true, detach the + filesystem from the filesystem hierarchy at time of the unmount + operation, and clean up all references to the filesystem as + soon as they are not busy anymore. + This corresponds with + <citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <parameter>-l</parameter> switch. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>DirectoryMode=</varname></term> <listitem><para>Directories of mount points (and any parent directories) are automatically created if needed. This option |