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   This file is part of systemd.
   9
  10   Copyright 2017 Lennart Poettering
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_bus_set_watch_bind">
  27
  28   <refentryinfo>
  29     <title>sd_bus_set_watch_bind</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Lennart</firstname>
  36         <surname>Poettering</surname>
  37         <email>lennart@poettering.net</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>sd_bus_set_watch_bind</refentrytitle>
  44     <manvolnum>3</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>sd_bus_set_watch_bind</refname>
  49     <refname>sd_bus_get_watch_bind</refname>
  50
  51     <refpurpose>Control socket binding watching on bus connections</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <funcsynopsis>
  56       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  57
  58       <funcprototype>
  59         <funcdef>int <function>sd_bus_set_watch_bind</function></funcdef>
  60         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  61         <paramdef>int <parameter>b</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>int <function>sd_bus_get_watch_bind</function></funcdef>
  66         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  67       </funcprototype>
  68
  69     </funcsynopsis>
  70   </refsynopsisdiv>
  71
  72   <refsect1>
  73     <title>Description</title>
  74
  75     <para><function>sd_bus_set_watch_bind()</function> may be used to enable or disable client-side watching of server
  76     socket binding for a bus connection object. If the <parameter>b</parameter> is true, the feature is enabled,
  77     otherwise disabled (which is the default). When enabled, and the selected bus address refers to an
  78     <filename>AF_UNIX</filename> socket in the file system which does not exist while the connection attempt is made an
  79     <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> watch is installed on
  80     it, waiting for the socket to appear. As soon as the socket appears the connection is made. This functionality is
  81     useful in particular in early-boot programs that need to run before the system bus is available, but want to
  82     connect to it the instant it may be connected to.</para>
  83
  84     <para><function>sd_bus_get_watch_bind()</function> may be used to query the current setting of this feature. It
  85     returns zero when the feature is disabled, and positive if enabled.</para>
  86
  87     <para>Note that no timeout is applied while it is waited for the socket to appear. This means that any synchronous
  88     remote operation (such as
  89     <citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  90     <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
  91     <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>), that is
  92     used on a connection with this feature enabled that is not established yet might block unbounded if the socket is
  93     never created. However, asynchronous remote operations (such as
  94     <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  95     <citerefentry><refentrytitle>sd_bus_add_match_async</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
  96     <citerefentry><refentrytitle>sd_bus_request_match_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>) do
  97     not block in this case, and safely enqueue the requested operations to be dispatched the instant the connection is
  98     set up.</para>
  99
 100     <para>Use <citerefentry><refentrytitle>sd_bus_is_ready</refentrytitle><manvolnum>3</manvolnum></citerefentry> to
 101     determine whether the connection is fully established, i.e. whether the peer socket has been bound, connected to
 102     and authenticated. Use
 103     <citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry> to
 104     be notified when the connection is fully established.</para>
 105
 106   </refsect1>
 107
 108   <refsect1>
 109     <title>Return Value</title>
 110
 111     <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style
 112     error code.</para>
 113   </refsect1>
 114
 115   <refsect1>
 116     <title>Errors</title>
 117
 118     <para>Returned errors may indicate the following problems:</para>
 119
 120     <variablelist>
 121       <varlistentry>
 122         <term><constant>-ECHILD</constant></term>
 123
 124         <listitem><para>The bus connection has been created in a different process.</para></listitem>
 125       </varlistentry>
 126     </variablelist>
 127   </refsect1>
 128
 129   <refsect1>
 130     <title>Notes</title>
 131
 132     <para><function>sd_bus_set_watch_bind()</function> and <function>sd_bus_get_watch_bind()</function> are available as
 133     a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
 134     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
 135   </refsect1>
 136
 137   <refsect1>
 138     <title>See Also</title>
 139
 140     <para>
 141       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 142       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 143       <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 144       <citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 145       <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 146       <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 147       <citerefentry><refentrytitle>sd_bus_is_ready</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 148       <citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 149     </para>
 150   </refsect1>
 151
 152 </refentry>