man/sd_bus_get_fd.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//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 © 2016 Julian Orth
   9 -->
  10
  11 <refentry id="sd_bus_get_fd" xmlns:xi="http://www.w3.org/2001/XInclude">
  12
  13   <refentryinfo>
  14     <title>sd_bus_get_fd</title>
  15     <productname>systemd</productname>
  16   </refentryinfo>
  17
  18   <refmeta>
  19     <refentrytitle>sd_bus_get_fd</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>sd_bus_get_fd</refname>
  25     <refname>sd_bus_set_fd</refname>
  26     <refname>sd_bus_get_events</refname>
  27     <refname>sd_bus_get_timeout</refname>
  28
  29     <refpurpose>Get the file descriptor, I/O events and timeout to wait for from a message bus
  30     object</refpurpose>
  31   </refnamediv>
  32
  33   <refsynopsisdiv>
  34     <funcsynopsis>
  35       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  36
  37       <funcprototype>
  38         <funcdef>int <function>sd_bus_get_fd</function></funcdef>
  39         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  40       </funcprototype>
  41
  42       <funcprototype>
  43         <funcdef>int <function>sd_bus_set_fd</function></funcdef>
  44         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  45         <paramdef>int <parameter>input_fd</parameter></paramdef>
  46         <paramdef>int <parameter>output_fd</parameter></paramdef>
  47       </funcprototype>
  48
  49       <funcprototype>
  50         <funcdef>int <function>sd_bus_get_events</function></funcdef>
  51         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  52       </funcprototype>
  53
  54       <funcprototype>
  55         <funcdef>int <function>sd_bus_get_timeout</function></funcdef>
  56         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  57         <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef>
  58       </funcprototype>
  59     </funcsynopsis>
  60   </refsynopsisdiv>
  61
  62   <refsect1>
  63     <title>Description</title>
  64
  65     <para><function>sd_bus_get_fd()</function> returns the file descriptor used to communicate from
  66     a message bus object. This descriptor can be used with
  67     <citerefentry project='man-pages'><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  68     or a similar function to wait for I/O events on the specified bus connection object. If the bus
  69     object was configured with the <function>sd_bus_set_fd()</function> function, then the
  70     <parameter>input_fd</parameter> file descriptor used in that call is returned.</para>
  71
  72     <para><function>sd_bus_set_fd()</function> sets the file descriptors used to communicate from a
  73     message bus object. Both <parameter>input_fd</parameter> and <parameter>output_fd</parameter>
  74     must be valid file descriptors. The same file descriptor may be used as both the input and the
  75     output file descriptor. This function must be called before the bus is started.</para>
  76
  77     <para><function>sd_bus_get_events()</function> returns the I/O events to wait for, suitable for
  78     passing to <function>poll()</function> or a similar call. Returns a combination of
  79     <constant>POLLIN</constant>, <constant>POLLOUT</constant>, … events, or negative on error.
  80     </para>
  81
  82     <para><function>sd_bus_get_timeout()</function> returns the timeout in µs to pass to to
  83     <function>poll()</function> or a similar call when waiting for events on the specified bus
  84     connection. The returned timeout may be zero, in which case a subsequent I/O polling call
  85     should be invoked in non-blocking mode. The returned timeout may be
  86     <constant>UINT64_MAX</constant> in which case the I/O polling call may block indefinitely,
  87     without any applied timeout. Note that the returned timeout should be considered only a
  88     maximum sleeping time. It is permissible (and even expected) that shorter timeouts are used by
  89     the calling program, in case other event sources are polled in the same event loop. Note that
  90     the returned time-value is relative and specified in microseconds. When converting this value in
  91     order to pass it as third argument to <function>poll()</function> (which expects milliseconds),
  92     care should be taken to use a division that rounds up to ensure the I/O polling operation
  93     doesn't sleep for shorter than necessary, which might result in unintended busy looping
  94     (alternatively, use
  95     <citerefentry project='man-pages'><refentrytitle>ppoll</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  96     instead of plain <function>poll()</function>, which understands timeouts with nano-second
  97     granularity).</para>
  98
  99     <para>These three functions are useful to hook up a bus connection object with an external or
 100     manual event loop involving <function>poll()</function> or a similar I/O polling call. Before
 101     each invocation of the I/O polling call, all three functions should be invoked: the file
 102     descriptor returned by <function>sd_bus_get_fd()</function> should be polled for the events
 103     indicated by <function>sd_bus_get_events()</function>, and the I/O call should block for that up
 104     to the timeout returned by <function>sd_bus_get_timeout()</function>. After each I/O polling
 105     call the bus connection needs to process incoming or outgoing data, by invoking
 106     <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 107     </para>
 108
 109     <para>Note that these functions are only one of three supported ways to implement I/O event
 110     handling for bus connections. Alternatively use
 111     <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 112     to attach a bus connection to an
 113     <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 114     event loop. Or use
 115     <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 116     as a simple synchronous, blocking I/O waiting call.</para>
 117   </refsect1>
 118
 119   <refsect1>
 120     <title>Return Value</title>
 121
 122     <para>On success, <function>sd_bus_get_fd()</function> returns the file descriptor used for
 123     communication. On failure, it returns a negative errno-style error code.</para>
 124
 125     <para>On success, <function>sd_bus_set_fd()</function> returns a non-negative integer. On
 126     failure, it returns a negative errno-style error code.</para>
 127
 128     <para>On success, <function>sd_bus_get_events()</function> returns the I/O event mask to use for
 129     I/O event watching. On failure, it returns a negative errno-style error code.</para>
 130
 131     <para>On success, <function>sd_bus_get_timeout()</function> returns a non-negative integer. On
 132     failure, it returns a negative errno-style error code.</para>
 133
 134     <refsect2>
 135       <title>Errors</title>
 136
 137       <para>Returned errors may indicate the following problems:</para>
 138
 139       <variablelist>
 140         <varlistentry>
 141           <term><constant>-EINVAL</constant></term>
 142
 143           <listitem><para>An invalid bus object was passed.</para></listitem>
 144         </varlistentry>
 145
 146         <varlistentry>
 147           <term><constant>-ECHILD</constant></term>
 148
 149           <listitem><para>The bus connection was allocated in a parent process and is being reused
 150           in a child process after <function>fork()</function>.</para></listitem>
 151         </varlistentry>
 152
 153         <varlistentry>
 154           <term><constant>-ENOTCONN</constant></term>
 155
 156           <listitem><para>The bus connection has been terminated.</para></listitem>
 157         </varlistentry>
 158
 159         <varlistentry>
 160           <term><constant>-EPERM</constant></term>
 161
 162           <listitem><para>Two distinct file descriptors were passed for input and output using
 163           <function>sd_bus_set_fd()</function>, which <function>sd_bus_get_fd()</function> cannot
 164           return.</para></listitem>
 165         </varlistentry>
 166
 167         <varlistentry>
 168           <term><constant>-EBADF</constant></term>
 169
 170           <listitem><para>An invalid file descriptor was passed to
 171           <function>sd_bus_set_fd()</function>.</para></listitem>
 172         </varlistentry>
 173
 174         <varlistentry>
 175           <term><constant>-ENOPKG</constant></term>
 176
 177           <listitem><para>The bus cannot be resolved.</para></listitem>
 178         </varlistentry>
 179       </variablelist>
 180     </refsect2>
 181   </refsect1>
 182
 183   <xi:include href="libsystemd-pkgconfig.xml" />
 184
 185   <refsect1>
 186     <title>See Also</title>
 187
 188     <para>
 189       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 190       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 191       <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 192       <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 193       <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 194       <citerefentry project='man-pages'><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 195     </para>
 196   </refsect1>
 197
 198 </refentry>