diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/sd_bus_creds_new_from_pid.xml | 21 | ||||
| -rw-r--r-- | man/sd_bus_new.xml | 48 | ||||
| -rw-r--r-- | man/sd_event_new.xml | 31 | ||||
| -rw-r--r-- | man/sd_event_source_unref.xml | 21 | ||||
| -rw-r--r-- | man/sd_login_monitor_new.xml | 31 | ||||
| -rw-r--r-- | man/systemctl.xml | 5 | ||||
| -rw-r--r-- | man/systemd.timer.xml | 14 |
7 files changed, 152 insertions, 19 deletions
diff --git a/man/sd_bus_creds_new_from_pid.xml b/man/sd_bus_creds_new_from_pid.xml index 84dd509744..082f7b67db 100644 --- a/man/sd_bus_creds_new_from_pid.xml +++ b/man/sd_bus_creds_new_from_pid.xml @@ -48,6 +48,7 @@ <refname>sd_bus_creds_get_augmented_mask</refname> <refname>sd_bus_creds_ref</refname> <refname>sd_bus_creds_unref</refname> + <refname>sd_bus_creds_unrefp</refname> <refpurpose>Retrieve credentials object for the specified PID</refpurpose> </refnamediv> @@ -82,6 +83,11 @@ <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef> <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_creds_unrefp</function></funcdef> + <paramdef>sd_bus_creds **<parameter>c</parameter></paramdef> + </funcprototype> </funcsynopsis> <para> @@ -235,6 +241,21 @@ <para><function>sd_bus_creds_unref()</function> destroys a reference to <parameter>c</parameter>.</para> + + <para><function>sd_bus_creds_unrefp()</function> is similar to + <function>sd_bus_creds_unref()</function> but takes a pointer to a + pointer to an <type>sd_bus_creds</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_creds_ref()</function>, + <function>sd_bus_creds_unref()</function> and + <function>sd_bus_creds_unrefp()</function> execute no operation if + the passed in bus credentials object is + <constant>NULL</constant>.</para> + </refsect1> <refsect1> diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index e1cab6e567..d281b5dd44 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -46,6 +46,7 @@ <refname>sd_bus_new</refname> <refname>sd_bus_ref</refname> <refname>sd_bus_unref</refname> + <refname>sd_bus_unrefp</refname> <refpurpose>Create a new bus object and create or destroy references to it</refpurpose> </refnamediv> @@ -68,6 +69,11 @@ <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef> <paramdef>sd_bus *<parameter>bus</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_unrefp</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -93,14 +99,40 @@ only allocate a bus object but also start the connection to a well-known bus in a single function invocation.</para> - <para><function>sd_bus_ref()</function> creates a new reference to - <parameter>bus</parameter>.</para> + <para><function>sd_bus_ref()</function> increases the reference + counter of <parameter>bus</parameter> by one.</para> - <para><function>sd_bus_unref()</function> destroys a reference to - <parameter>bus</parameter>. Once the reference count has dropped - to zero, <parameter>bus</parameter> cannot be used anymore, so - further calls to <function>sd_bus_ref()</function> or + <para><function>sd_bus_unref()</function> decreases the reference + counter of <parameter>bus</parameter> by one. Once the reference + count has dropped to zero, <parameter>bus</parameter> is destroyed + and cannot be used anymore, so further calls to + <function>sd_bus_ref()</function> or <function>sd_bus_unref()</function> are illegal.</para> + + <para><function>sd_bus_unrefp()</function> is similar to + <function>sd_bus_unref()</function> but takes a pointer to a + pointer to an <type>sd_bus</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. Use a declaration like the following, in order to + allocate a bus object that is freed automatically as the code + block is left:</para> + + <programlisting>{ + __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL; + int r; + … + r = sd_bus_default(&bus); + if (r < 0) + fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r)); + … +}</programlisting> + + <para><function>sd_bus_ref()</function>, + <function>sd_bus_unref()</function> and + <function>sd_bus_unrefp()</function> execute no operation if the + passed in bus object is <constant>NULL</constant>.</para> </refsect1> <refsect1> @@ -110,10 +142,10 @@ positive integer. On failure, it returns a negative errno-style error code.</para> - <para><function>sd_bus_ref</function> always returns the argument. + <para><function>sd_bus_ref()</function> always returns the argument. </para> - <para><function>sd_bus_unref</function> always returns + <para><function>sd_bus_unref()</function> always returns <constant>NULL</constant>.</para> </refsect1> diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml index 3356faa899..2c23b00a8c 100644 --- a/man/sd_event_new.xml +++ b/man/sd_event_new.xml @@ -47,6 +47,7 @@ <refname>sd_event_default</refname> <refname>sd_event_ref</refname> <refname>sd_event_unref</refname> + <refname>sd_event_unrefp</refname> <refname>sd_event_get_tid</refname> <refname>sd_event</refname> @@ -80,6 +81,11 @@ </funcprototype> <funcprototype> + <funcdef>void <function>sd_event_unrefp</function></funcdef> + <paramdef>sd_event **<parameter>event</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_event_get_tid</function></funcdef> <paramdef>sd_event *<parameter>event</parameter></paramdef> <paramdef>pid_t *<parameter>tid</parameter></paramdef> @@ -139,8 +145,29 @@ all remaining event sources of the event loop also need to be freed as each keeps a reference to it.</para> - <para>Both <function>sd_event_ref()</function> and - <function>sd_event_unref()</function> execute no operation if the + <para><function>sd_event_unrefp()</function> is similar to + <function>sd_event_unref()</function> but takes a pointer to a + pointer to an <type>sd_event</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. Use a declaration like the following, + in order to allocate an event loop object that is freed + automatically as the code block is left:</para> + + <programlisting>{ + __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL; + int r; + … + r = sd_event_default(&event); + if (r < 0) + fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r)); + … +}</programlisting> + + <para><function>sd_event_ref()</function>, + <function>sd_event_unref()</function> and + <function>sd_event_unrefp()</function> execute no operation if the passed in event loop object is <constant>NULL</constant>.</para> <para><function>sd_event_get_tid()</function> retrieves the thread diff --git a/man/sd_event_source_unref.xml b/man/sd_event_source_unref.xml index 579ec47e8e..2c4d450763 100644 --- a/man/sd_event_source_unref.xml +++ b/man/sd_event_source_unref.xml @@ -44,6 +44,7 @@ <refnamediv> <refname>sd_event_source_unref</refname> + <refname>sd_event_source_unrefp</refname> <refname>sd_event_source_ref</refname> <refpurpose>Increase or decrease event source reference counters</refpurpose> @@ -59,6 +60,11 @@ </funcprototype> <funcprototype> + <funcdef>void <function>sd_event_source_unrefp</function></funcdef> + <paramdef>sd_event_source **<parameter>source</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>sd_event_source* <function>sd_event_source_ref</function></funcdef> <paramdef>sd_event_source *<parameter>source</parameter></paramdef> </funcprototype> @@ -80,12 +86,23 @@ the reference counter reaches zero it is removed from its event loop object and destroyed.</para> + <para><function>sd_event_source_unrefp()</function> is similar to + <function>sd_event_source_unref()</function> but takes a pointer to a + pointer to an <type>sd_event_source</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_event_source_ref()</function> may be used to increase by one the reference counter of the event source object specified as <parameter>source</parameter>.</para> - <para>Both functions execute no operation if the passed event - source object is <constant>NULL</constant>.</para> + <para><function>sd_event_source_unref()</function>, + <function>sd_bus_creds_unrefp()</function> and + <function>sd_bus_creds_ref()</function> execute no operation if + the passed event source object is + <constant>NULL</constant>.</para> <para>Note that event source objects stay alive and may be dispatched as long as they have a reference counter greater than diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index db21d70252..5625ab9207 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -45,6 +45,7 @@ <refnamediv> <refname>sd_login_monitor_new</refname> <refname>sd_login_monitor_unref</refname> + <refname>sd_login_monitor_unrefp</refname> <refname>sd_login_monitor_flush</refname> <refname>sd_login_monitor_get_fd</refname> <refname>sd_login_monitor_get_events</refname> @@ -69,6 +70,11 @@ </funcprototype> <funcprototype> + <funcdef>void <function>sd_login_monitor_unrefp</function></funcdef> + <paramdef>sd_login_monitor **<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_login_monitor_flush</function></funcdef> <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> </funcprototype> @@ -121,6 +127,26 @@ descriptor returned by <function>sd_login_monitor_get_fd()</function>.</para> + <para><function>sd_login_monitor_unrefp()</function> is similar to + <function>sd_login_monitor_unref()</function> but takes a pointer + to a pointer to an <type>sd_login_monitor</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. Use a declaration like the following, in order to + allocate a login monitor object that is freed automatically as the + code block is left:</para> + + <programlisting>{ + __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL; + int r; + … + r = sd_login_monitor_default(&m); + if (r < 0) + fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r)); + … +}</programlisting> + <para><function>sd_login_monitor_flush()</function> may be used to reset the wakeup state of the monitor object. Whenever an event causes the monitor to wake up the event loop via the file @@ -128,6 +154,11 @@ state. If this call is not invoked, the file descriptor will immediately wake up the event loop again.</para> + <para><function>sd_login_monitor_unref()</function> and + <function>sd_login_monitor_unrefp()</function> execute no + operation if the passed in monitor object is + <constant>NULL</constant>.</para> + <para><function>sd_login_monitor_get_fd()</function> may be used to retrieve the file descriptor of the monitor object that may be integrated in an application defined event loop, based around diff --git a/man/systemctl.xml b/man/systemctl.xml index 755a74f987..1fb056874c 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -888,6 +888,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>Example: <command>systemctl set-property foobar.service CPUShares=777</command></para> + <para>If the specified unit appears to be inactive, the + changes will be only stored on disk as described + previously hence they will be effective when the unit will + be started.</para> + <para>Note that this command allows changing multiple properties at the same time, which is preferable over setting them individually. Like unit file configuration diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml index fd03bda9cd..cfa13015b0 100644 --- a/man/systemd.timer.xml +++ b/man/systemd.timer.xml @@ -205,7 +205,7 @@ </varlistentry> <varlistentry> - <term><varname>RandomSec=</varname></term> + <term><varname>RandomizedDelaySec=</varname></term> <listitem><para>Delay the timer by a randomly selected, evenly distributed amount of time between 0 and the specified time @@ -222,16 +222,16 @@ time range in order to minimize wakeups, the former does the opposite: it stretches timer events over a time range, to make it unlikely that they fire simultaneously. If - <varname>RandomSec=</varname> and + <varname>RandomizedDelaySec=</varname> and <varname>AccuracySec=</varname> are used in conjunction, first - the a randomized time is added, and the result is then - possibly shifted further to coalesce it with other timer - events possibly happening on the system. As mentioned above + the randomized delay is added, and then the result is + possibly further shifted to coalesce it with other timer + events happening on the system. As mentioned above <varname>AccuracySec=</varname> defaults to 1min and - <varname>RandomSec=</varname> to 0, thus encouraging + <varname>RandomizedDelaySec=</varname> to 0, thus encouraging coalescing of timer events. In order to optimally stretch timer events over a certain range of time, make sure to set - <varname>RandomSec=</varname> to a higher value, and + <varname>RandomizedDelaySec=</varname> to a higher value, and <varname>AccuracySec=1us</varname>.</para></listitem> </varlistentry> |