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