util: make http url validity checks more generic, and move them to util.c

[elogind.git] / man / sd_bus_negotiate_fds.xml

diff --git a/man/sd_bus_negotiate_fds.xml b/man/sd_bus_negotiate_fds.xml
index c2061941ab8e7e1595efaf94f98cfa59dfc4a75b..4babae5e2b0dfdc99e5790746b5ad9f8fee350b9 100644 (file)
--- a/man/sd_bus_negotiate_fds.xml
+++ b/man/sd_bus_negotiate_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">
 
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 


@@ -70,6 +70,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
         <funcdef>int <function>sd_bus_negotiate_creds</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
         <paramdef>int <parameter>b</parameter></paramdef>
         <funcdef>int <function>sd_bus_negotiate_creds</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
         <paramdef>int <parameter>b</parameter></paramdef>

+        <paramdef>uint64_t <parameter>flags</parameter></paramdef>

       </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
       </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>


@@ -79,53 +80,62 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
     <para><function>sd_bus_negotiate_fds()</function> controls whether
     file descriptor passing shall be negotiated for the specified bus
 
     <para><function>sd_bus_negotiate_fds()</function> controls whether
     file descriptor passing shall be negotiated for the specified bus

-    connection. Takes a bus object and a boolean, which when true
-    enables file descriptor passing, and when false disables it. Note
+    connection. It takes a bus object and a boolean, which, when true,
+    enables file descriptor passing, and, when false, disables it. Note

     that not all transports and servers support file descriptor
     passing. To find out whether file descriptor passing is available
     that not all transports and servers support file descriptor
     passing. To find out whether file descriptor passing is available

-    after negotiation use
+    after negotiation, use

     <citerefentry><refentrytitle>sd_bus_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     and pass <constant>SD_BUS_TYPE_UNIX_FD</constant>. Note that file
     descriptor passing is always enabled for both sending and
     receiving or for neither, but never only in one direction. By
     <citerefentry><refentrytitle>sd_bus_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     and pass <constant>SD_BUS_TYPE_UNIX_FD</constant>. Note that file
     descriptor passing is always enabled for both sending and
     receiving or for neither, but never only in one direction. By

-    default file descriptor passing is negotiated for all
+    default, file descriptor passing is negotiated for all

     connections.</para>
 
     connections.</para>
 

-    <para>Note that when bus activation is used it is highly
+    <para>Note that when bus activation is used, it is highly

     recommended to set the <option>AcceptFileDescriptors=</option>
     setting in the <filename>.busname</filename> unit file to the same
     setting as negotiated by the program ultimately activated. By
     recommended to set the <option>AcceptFileDescriptors=</option>
     setting in the <filename>.busname</filename> unit file to the same
     setting as negotiated by the program ultimately activated. By

-    default file descriptor passing is enabled for both.</para>
+    default, file descriptor passing is enabled for both.</para>

 
     <para><function>sd_bus_negotiate_timestamps()</function> controls
     whether implicit sender timestamps shall be attached automatically
 
     <para><function>sd_bus_negotiate_timestamps()</function> controls
     whether implicit sender timestamps shall be attached automatically

-    to all incoming messages. Takes a bus object and a boolean, which
-    when true enables timestamping, and when false disables it. If
+    to all incoming messages. Takes a bus object and a boolean, which,
+    when true, enables timestamping, and, when false, disables it. If

     this is disabled,
     <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_bus_message_get_seqno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     fail with <constant>-ENODATA</constant> on incoming messages. Note
     that not all transports support timestamping of messages. On local
     this is disabled,
     <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_bus_message_get_seqno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     fail with <constant>-ENODATA</constant> on incoming messages. Note
     that not all transports support timestamping of messages. On local

-    transports the timestamping is applied by the kernel and cannot be
-    manipulated by userspace.</para>
+    transports, the timestamping is applied by the kernel and cannot
+    be manipulated by userspace. By default, message timestamping is
+    not negotiated for all connections.</para>

 
     <para><function>sd_bus_negotiate_creds()</function> controls
     whether implicit sender credentials shall be attached
 
     <para><function>sd_bus_negotiate_creds()</function> controls
     whether implicit sender credentials shall be attached

-    automatically to all incoming messages. Takes a bus object and a
-    bit mask value, which controls which credential parameters are
-    attached. If this is not used,
-    <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    fails with <constant>-ENODATA</constant> on incoming
-    messages. Note that not all transports support attaching sender
-    credentials to messages, or do not support all types of sender
-    credential parameters. On local transports the sender credentials
-    are attached by the kernel and cannot be manipulated by
-    userspace. By default no sender credentials are attached.</para>
-
-    <para>These functions may be called only before the connection has
-    been started with
-    <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+    automatically to all incoming messages. Takes a bus object, a
+    boolean indicating whether to enable or disable the credential
+    parts encoded in the bit mask value argument. Note that not all
+    transports support attaching sender credentials to messages, or do
+    not support all types of sender credential parameters, or might
+    suppress them under certain circumstances for individual
+    messages. On local transports, the sender credentials are attached
+    by the kernel and cannot be manipulated by userspace. By default,
+    no sender credentials are attached.</para>
+
+    <para>The <function>sd_bus_negotiate_fds()</function> function may
+    be called only before the connection has been started with
+    <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Both
+    <function>sd_bus_negotiate_timestamp()</function> and
+    <function>sd_bus_negotiate_creds()</function> also may be called
+    after a connection has been set up. Note that when operating on a
+    connection that is shared between multiple components of the same
+    program (for example via
+    <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
+    it is highly recommended to only enable additional per message
+    metadata fields, but never disable them again, in order not to
+    disable functionality needed by other components.</para>

   </refsect1>
 
   <refsect1>
   </refsect1>
 
   <refsect1>


@@ -143,7 +153,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
     <variablelist>
       <varlistentry>
 
     <variablelist>
       <varlistentry>

-        <term><varname>-EPERM</varname></term>
+        <term><constant>-EPERM</constant></term>

 
         <listitem><para>The bus connection has already been started.</para></listitem>
       </varlistentry>
 
         <listitem><para>The bus connection has already been started.</para></listitem>
       </varlistentry>


@@ -156,7 +166,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
     <para><function>sd_bus_negotiate_fs()</function> and the other
     functions described here are available as a shared library, which
     can be compiled and linked to with the
     <para><function>sd_bus_negotiate_fs()</function> and the other
     functions described here are available as a shared library, which
     can be compiled and linked to with the

-    <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>

     file.</para>
   </refsect1>
 
     file.</para>
   </refsect1>
 


@@ -169,7 +179,8 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
       <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

-      <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.busname</refentrytitle><manvolnum>5</manvolnum></citerefentry>

     </para>
   </refsect1>
 
     </para>
   </refsect1>