Merge pull request #17561 from yuwata/man

man/journald.conf.xml

@@ -433,7 +433,7 @@
 
         <listitem><para>The maximum line length to permit when converting stream logs into record logs. When a systemd
         unit's standard output/error are connected to the journal via a stream socket, the data read is split into
-        individual log records at newline (<literal>\n</literal>, ASCII 10) and NUL characters. If no such delimiter is
+        individual log records at newline (<literal>\n</literal>, ASCII 10) and <constant>NUL</constant> characters. If no such delimiter is
         read for the specified number of bytes a hard log record boundary is artificially inserted, breaking up overly
         long lines into multiple log records. Selecting overly large values increases the possible memory usage of the
         Journal daemon for each stream client, as in the worst case the journal daemon needs to buffer the specified

man/pam_systemd.xml

@@ -244,7 +244,7 @@
     <title>Session limits</title>
 
     <para>PAM modules earlier in the stack, that is those that come before <command>pam_systemd.so</command>,
-    can set session scope limits using the PAM context objects. The data for these objects is provided as NUL-terminated C strings
+    can set session scope limits using the PAM context objects. The data for these objects is provided as <constant>NUL</constant>-terminated C strings
     and maps directly to the respective unit resource control directives. Note that these limits apply to individual sessions of the user,
     they do not apply to all user processes as a combined whole. In particular, the per-user <command>user@.service</command> unit instance,
     which runs the <command>systemd --user</command> manager process and its children, and is tracked outside of any session, being shared

man/sd-id128.xml

@@ -85,8 +85,8 @@
 
     <programlisting>#define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1)</programlisting>
 
-    <para><function>SD_ID128_NULL</function> may be used to refer to the 128bit ID consisting of only NUL
-    bytes.</para>
+    <para><constant>SD_ID128_NULL</constant> may be used to refer to the 128bit ID consisting of only
+    <constant>NUL</constant> bytes.</para>
 
     <para><function>SD_ID128_MAKE_STR()</function> is similar to <function>SD_ID128_MAKE()</function>, but creates a
     <type>const char*</type> expression that can be conveniently used in message formats and such:</para>
@@ -107,9 +107,8 @@ int main(int argc, char **argv) {
         puts("Match for coredumps: %s", SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP));
 }</programlisting>
 
-    <para><function>SD_ID128_FORMAT_STR()</function> and
-    <function>SD_ID128_FORMAT_VAL()</function> may be used to format a
-    128-bit ID in a
+    <para><constant>SD_ID128_FORMAT_STR</constant> and <function>SD_ID128_FORMAT_VAL()</function> may
+    be used to format a 128-bit ID in a
     <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     format string, as shown in the following example:</para>
 
@@ -120,8 +119,8 @@ int main(int argc, char **argv) {
         return 0;
 }</programlisting>
 
-    <para><function>SD_ID128_UUID_FORMAT_STR()</function> is similar to
-    <function>SD_ID128_FORMAT_STR()</function> but includes separating hyphens to conform to the
+    <para><constant>SD_ID128_UUID_FORMAT_STR</constant> is similar to
+    <constant>SD_ID128_FORMAT_STR</constant> but includes separating hyphens to conform to the
     "<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">canonical representation</ulink>".
     </para>
 
@@ -137,7 +136,8 @@ int main(int argc, char **argv) {
         return 0;
 }</programlisting>
 
-    <para>Use <function>sd_id128_is_null()</function> to check if an 128bit ID consists of only NUL bytes:</para>
+    <para>Use <function>sd_id128_is_null()</function> to check if an 128bit ID consists of only
+    <constant>NUL</constant> bytes:</para>
 
     <programlisting>int main(int argc, char *argv[]) {
         assert(sd_id128_is_null(SD_ID128_NULL));

man/sd_bus_add_object.xml

@@ -620,8 +620,8 @@
         <varlistentry>
           <term><constant>-EPROTOTYPE</constant></term>
 
-          <listitem><para><function>sd_bus_add_object_vtable</function> and
-          <function>sd_bus_add_fallback_vtable</function> have been both called for the same bus
+          <listitem><para><function>sd_bus_add_object_vtable()</function> and
+          <function>sd_bus_add_fallback_vtable()</function> have been both called for the same bus
           object path, which is not allowed.</para></listitem>
         </varlistentry>
 

man/sd_bus_call.xml

@@ -104,6 +104,12 @@
     <refsect2 id='errors'>
       <title>Errors</title>
 
+      <para>When <function>sd_bus_call()</function> internally receives a D-Bus error reply, it will set
+      <parameter>ret_error</parameter> if it is not <constant>NULL</constant>, and will return a negative
+      value mapped from the error reply, see
+      <citerefentry><refentrytitle>sd_bus_error_get_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+      </para>
+
       <para>Returned errors may indicate the following problems:</para>
 
       <variablelist>
@@ -180,7 +186,8 @@
       <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_call_method_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     </para>
   </refsect1>
 

man/sd_bus_can_send.xml

@@ -37,7 +37,7 @@
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_bus_can_send</function> is mostly used for checking if file descriptor
+    <para><function>sd_bus_can_send()</function> is mostly used for checking if file descriptor
     passing is available on the given bus. <parameter>type</parameter> can be any of the
     <constant>SD_BUS_TYPE</constant> constants.</para>
   </refsect1>

man/sd_bus_close.xml

@@ -72,7 +72,7 @@
     is provided that combines them into one.</para>
 
     <para><function>sd_bus_default_flush_close()</function> is similar to
-    <function>sd_bus_flush_close_unref</function>, but does not take a bus pointer argument and
+    <function>sd_bus_flush_close_unref()</function>, but does not take a bus pointer argument and
     instead iterates over any of the "default" buses opened by
     <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

man/sd_bus_creds_get_pid.xml

@@ -439,14 +439,14 @@
 
     <para>All functions that take a <parameter>const
     char**</parameter> parameter will store the answer there as an
-    address of a NUL-terminated string. It will be valid as long as
+    address of a <constant>NUL</constant>-terminated string. It will be valid as long as
     <parameter>c</parameter> remains valid, and should not be freed or
     modified by the caller.</para>
 
     <para>All functions that take a <parameter>char***</parameter>
     parameter will store the answer there as an address of an array
-    of strings. Each individual string is NUL-terminated, and the
-    array is NULL-terminated as a whole. It will be valid as long as
+    of strings. Each individual string is <constant>NUL</constant>-terminated, and the
+    array is <constant>NULL</constant>-terminated as a whole. It will be valid as long as
     <parameter>c</parameter> remains valid, and should not be freed or
     modified by the caller.</para>
   </refsect1>

man/sd_bus_error.xml

@@ -160,10 +160,10 @@
     but additional domain-specific errors may be defined by
     applications. The <structfield>message</structfield> field usually
     contains a human-readable string describing the details, but might
-    be NULL. An unset <structname>sd_bus_error</structname> structure
-    should have both fields initialized to NULL. Set an error
+    be <constant>NULL</constant>. An unset <structname>sd_bus_error</structname> structure
+    should have both fields initialized to <constant>NULL</constant>. Set an error
     structure to <constant>SD_BUS_ERROR_NULL</constant> in order to
-    reset both fields to NULL. When no longer necessary, resources
+    reset both fields to <constant>NULL</constant>. When no longer necessary, resources
     held by the <structname>sd_bus_error</structname> structure should
     be destroyed with <function>sd_bus_error_free()</function>.</para>
 
@@ -181,14 +181,14 @@
     for a list of well-known error names. Additional error mappings
     may be defined with
     <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
-    <parameter>e</parameter> is NULL, no error structure is initialized,
+    <parameter>e</parameter> is <constant>NULL</constant>, no error structure is initialized,
     but the error is still converted into an
     <varname>errno</varname>-style error. If
     <parameter>name</parameter> is <constant>NULL</constant>, it is
     assumed that no error occurred, and 0 is returned. This means that
     this function may be conveniently used in a
     <function>return</function> statement. If
-    <parameter>message</parameter> is NULL, no message is set. This
+    <parameter>message</parameter> is <constant>NULL</constant>, no message is set. This
     call can fail if no memory may be allocated for the name and
     message strings, in which case an
     <constant>SD_BUS_ERROR_NO_MEMORY</constant> error might be set
@@ -291,10 +291,10 @@
     will not be deallocated, and must be <citerefentry
     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
     by the caller if necessary. The function may also be called safely
-    on unset errors (error structures with both fields set to NULL),
+    on unset errors (error structures with both fields set to <constant>NULL</constant>),
     in which case it performs no operation. This call will reset the
     error structure after freeing the data, so that all fields are set
-    to NULL. The structure may be reused afterwards.</para>
+    to <constant>NULL</constant>. The structure may be reused afterwards.</para>
   </refsect1>
 
   <refsect1>

man/sd_bus_interface_name_is_valid.xml

@@ -65,7 +65,7 @@
     <title>Return Value</title>
 
     <para>Those functions return 1 if the argument is a valid interface / service / member name or object
-    path, and 0 if it is not. If the argument is NULL, an error is returned.</para>
+    path, and 0 if it is not. If the argument is <constant>NULL</constant>, an error is returned.</para>
 
     <refsect2>
       <title>Errors</title>

man/sd_bus_message_append_string_memfd.xml

@@ -54,20 +54,20 @@
     <title>Description</title>
 
     <para>The functions
-    <function>sd_bus_message_append_string_memfd</function> and
-    <function>sd_bus_message_append_string_iovec</function> can be
+    <function>sd_bus_message_append_string_memfd()</function> and
+    <function>sd_bus_message_append_string_iovec()</function> can be
     used to append a single string (item of type <literal>s</literal>)
     to message <parameter>m</parameter>.</para>
 
     <para>In case of
-    <function>sd_bus_message_append_string_memfd</function>, the
+    <function>sd_bus_message_append_string_memfd()</function>, the
     contents of <parameter>memfd</parameter> are the string. They must
     satisfy the same constraints as described for the
     <literal>s</literal> type in
     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 
     <para>In case of
-    <function>sd_bus_message_append_string_iovec</function>, the
+    <function>sd_bus_message_append_string_iovec()</function>, the
     payload of <parameter>iov</parameter> is the string. It must
     satisfy the same constraints as described for the
     <literal>s</literal> type in
@@ -84,9 +84,9 @@
     after this call.</para>
 
     <para>The
-    <function>sd_bus_message_append_string_space</function> function appends
+    <function>sd_bus_message_append_string_space()</function> function appends
     space for a string to message <parameter>m</parameter>. It behaves
-    similar to <function>sd_bus_message_append_basic</function> with
+    similar to <function>sd_bus_message_append_basic()</function> with
     type <literal>s</literal>, but instead of copying a string into
     the message, it returns a pointer to the destination area to
     the caller in pointer <parameter>p</parameter>. Space for the string

man/sd_bus_message_append_strv.xml

@@ -37,7 +37,7 @@
   <refsect1>
     <title>Description</title>
 
-    <para>The <function>sd_bus_message_append</function> function can be
+    <para>The <function>sd_bus_message_append()</function> function can be
     used to append an array of strings to message
     <parameter>m</parameter>. The parameter <parameter>l</parameter>
     shall point to a <constant>NULL</constant>-terminated array of pointers

man/sd_bus_message_new_method_error.xml

@@ -143,8 +143,8 @@
           <para>Message <parameter>call</parameter> is not a method call
           message.</para>
 
-          <para>The error <parameter>error</parameter> parameter to
-          <function>sd_bus_message_new_method_error</function> is not set, see
+          <para>The error <parameter>e</parameter> parameter to
+          <function>sd_bus_message_new_method_error()</function> is not set, see
           <citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
           </para>
           </listitem>

man/sd_bus_path_encode.xml

@@ -118,7 +118,7 @@
     will be stored there. Each <literal>%</literal> character will
     only match the current label. It will never match across labels.
     Furthermore, only a single directive is allowed per label.
-    If <literal>NULL</literal> is passed as output storage, the
+    If <constant>NULL</constant> is passed as output storage, the
     label is verified but not returned to the caller.</para>
   </refsect1>
 
@@ -130,7 +130,7 @@
     argument. On success, <function>sd_bus_path_decode()</function>
     returns a positive value if the prefixed matched, or 0 if it
     did not. If the prefix matched, the external identifier is returned
-    in the return parameter. If it did not match, NULL is returned in
+    in the return parameter. If it did not match, <constant>NULL</constant> is returned in
     the return parameter. On failure, a negative errno-style error
     number is returned by either function. The returned strings must
     be

man/sd_bus_process.xml

@@ -56,7 +56,7 @@
     <parameter>ret</parameter> is not <constant>NULL</constant> and the call processed a message,
     <parameter>*ret</parameter> is set to this message.  The caller owns a reference to this message and should call
     <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> when the
-    message is no longer needed. If <parameter>ret</parameter> is not NULL, progress was made, but no message was
+    message is no longer needed. If <parameter>ret</parameter> is not <constant>NULL</constant>, progress was made, but no message was
     processed, <parameter>*ret</parameter> is set to <constant>NULL</constant>.</para>
 
     <para>If a the bus object is connected to an

man/sd_bus_reply_method_error.xml

@@ -127,8 +127,8 @@
 
           <para>Message <parameter>call</parameter> is not attached to a bus.</para>
 
-          <para>The error parameter <parameter>error</parameter> to
-          <function>sd_bus_reply_method_error</function> is not set, see
+          <para>The error parameter <parameter>e</parameter> to
+          <function>sd_bus_reply_method_error()</function> is not set, see
           <citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
           </para>
           </listitem>

man/sd_bus_set_address.xml

@@ -112,7 +112,7 @@
     <citerefentry><refentrytitle>sd_bus_open</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
     similar calls, based on environment variables or built-in defaults.</para>
 
-    <para><function>sd_bus_set_exec</function> is a shorthand function for setting a
+    <para><function>sd_bus_set_exec()</function> is a shorthand function for setting a
     <literal>unixexec</literal> address that spawns the given executable with the given arguments.
     If <parameter>argv</parameter> is <constant>NULL</constant>, the given executable is spawned
     without any extra arguments.</para>

man/sd_bus_set_property.xml

@@ -157,7 +157,7 @@
 
       <para>See the
       <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-      man page for a list of possible errors</para>
+      man page for a list of possible errors.</para>
     </refsect2>
   </refsect1>
 

man/sd_bus_track_new.xml

@@ -101,11 +101,11 @@
     <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>
+    when they disconnect from the bus.  If non-<constant>NULL</constant> 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

man/sd_event_source_get_event.xml

@@ -51,7 +51,7 @@
 
     <para>On success, <function>sd_event_source_get_event()</function>
     returns the associated event loop object. On failure, it returns
-    NULL.</para>
+    <constant>NULL</constant>.</para>
   </refsect1>
 
   <xi:include href="libsystemd-pkgconfig.xml" />

man/sd_event_source_set_prepare.xml

@@ -52,7 +52,7 @@
     when the event source was created. The event source will be disabled
     if the callback function returns a negative error code. The callback
     function may be used to reconfigure the precise events to wait for.
-    If the <parameter>callback</parameter> parameter is passed as NULL
+    If the <parameter>callback</parameter> parameter is passed as <constant>NULL</constant>
     the callback function is reset. </para>
 
     <para>Event source objects have no preparation callback associated

man/sd_event_source_set_userdata.xml

@@ -70,7 +70,7 @@
     <function>sd_event_source_set_userdata()</function> and
     <function>sd_event_source_get_userdata()</function> return the
     previously set user data pointer. On failure, they return
-    NULL.</para>
+    <constant>NULL</constant>.</para>
   </refsect1>
 
   <xi:include href="libsystemd-pkgconfig.xml" />

man/sd_get_seats.xml

@@ -56,7 +56,7 @@
 
     <para><function>sd_get_seats()</function> may be used to determine
     all currently available local seats. Returns the number of seat
-    identifiers and if the input pointer is non-NULL, a
+    identifiers and if the input pointer is non-<constant>NULL</constant>, a
     <constant>NULL</constant>-terminated array of seat identifiers
     is stored at the address.
     The returned array and all strings it references need to be freed