man/sd_bus_set_watch_bind.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   Copyright 2017 Lennart Poettering
   9 -->
  10
  11 <refentry id="sd_bus_set_watch_bind">
  12
  13   <refentryinfo>
  14     <title>sd_bus_set_watch_bind</title>
  15     <productname>systemd</productname>
  16
  17     <authorgroup>
  18       <author>
  19         <contrib>Developer</contrib>
  20         <firstname>Lennart</firstname>
  21         <surname>Poettering</surname>
  22         <email>lennart@poettering.net</email>
  23       </author>
  24     </authorgroup>
  25   </refentryinfo>
  26
  27   <refmeta>
  28     <refentrytitle>sd_bus_set_watch_bind</refentrytitle>
  29     <manvolnum>3</manvolnum>
  30   </refmeta>
  31
  32   <refnamediv>
  33     <refname>sd_bus_set_watch_bind</refname>
  34     <refname>sd_bus_get_watch_bind</refname>
  35
  36     <refpurpose>Control socket binding watching on bus connections</refpurpose>
  37   </refnamediv>
  38
  39   <refsynopsisdiv>
  40     <funcsynopsis>
  41       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  42
  43       <funcprototype>
  44         <funcdef>int <function>sd_bus_set_watch_bind</function></funcdef>
  45         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  46         <paramdef>int <parameter>b</parameter></paramdef>
  47       </funcprototype>
  48
  49       <funcprototype>
  50         <funcdef>int <function>sd_bus_get_watch_bind</function></funcdef>
  51         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  52       </funcprototype>
  53
  54     </funcsynopsis>
  55   </refsynopsisdiv>
  56
  57   <refsect1>
  58     <title>Description</title>
  59
  60     <para><function>sd_bus_set_watch_bind()</function> may be used to enable or disable client-side watching of server
  61     socket binding for a bus connection object. If the <parameter>b</parameter> is true, the feature is enabled,
  62     otherwise disabled (which is the default). When enabled, and the selected bus address refers to an
  63     <filename>AF_UNIX</filename> socket in the file system which does not exist while the connection attempt is made an
  64     <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> watch is installed on
  65     it, waiting for the socket to appear. As soon as the socket appears the connection is made. This functionality is
  66     useful in particular in early-boot programs that need to run before the system bus is available, but want to
  67     connect to it the instant it may be connected to.</para>
  68
  69     <para><function>sd_bus_get_watch_bind()</function> may be used to query the current setting of this feature. It
  70     returns zero when the feature is disabled, and positive if enabled.</para>
  71
  72     <para>Note that no timeout is applied while it is waited for the socket to appear. This means that any synchronous
  73     remote operation (such as
  74     <citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  75     <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
  76     <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>), that is
  77     used on a connection with this feature enabled that is not established yet might block unbounded if the socket is
  78     never created. However, asynchronous remote operations (such as
  79     <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  80     <citerefentry><refentrytitle>sd_bus_add_match_async</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
  81     <citerefentry><refentrytitle>sd_bus_request_match_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>) do
  82     not block in this case, and safely enqueue the requested operations to be dispatched the instant the connection is
  83     set up.</para>
  84
  85     <para>Use <citerefentry><refentrytitle>sd_bus_is_ready</refentrytitle><manvolnum>3</manvolnum></citerefentry> to
  86     determine whether the connection is fully established, i.e. whether the peer socket has been bound, connected to
  87     and authenticated. Use
  88     <citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry> to
  89     be notified when the connection is fully established.</para>
  90
  91   </refsect1>
  92
  93   <refsect1>
  94     <title>Return Value</title>
  95
  96     <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style
  97     error code.</para>
  98   </refsect1>
  99
 100   <refsect1>
 101     <title>Errors</title>
 102
 103     <para>Returned errors may indicate the following problems:</para>
 104
 105     <variablelist>
 106       <varlistentry>
 107         <term><constant>-ECHILD</constant></term>
 108
 109         <listitem><para>The bus connection has been created in a different process.</para></listitem>
 110       </varlistentry>
 111     </variablelist>
 112   </refsect1>
 113
 114   <refsect1>
 115     <title>Notes</title>
 116
 117     <para><function>sd_bus_set_watch_bind()</function> and <function>sd_bus_get_watch_bind()</function> are available as
 118     a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
 119     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
 120   </refsect1>
 121
 122   <refsect1>
 123     <title>See Also</title>
 124
 125     <para>
 126       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 127       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 128       <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 129       <citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 130       <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 131       <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 132       <citerefentry><refentrytitle>sd_bus_is_ready</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 133       <citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 134     </para>
 135   </refsect1>
 136
 137 </refentry>