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