2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 Copyright © 2016 Julian Orth
11 <refentry id=
"sd_bus_get_fd" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
14 <title>sd_bus_get_fd
</title>
15 <productname>systemd
</productname>
19 <refentrytitle>sd_bus_get_fd
</refentrytitle>
20 <manvolnum>3</manvolnum>
24 <refname>sd_bus_get_fd
</refname>
25 <refname>sd_bus_get_events
</refname>
26 <refname>sd_bus_get_timeout
</refname>
28 <refpurpose>Get the file descriptor, I/O events and time-out to wait for from a message bus object
</refpurpose>
33 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
36 <funcdef>int
<function>sd_bus_get_fd
</function></funcdef>
37 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
41 <funcdef>int
<function>sd_bus_get_events
</function></funcdef>
42 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
46 <funcdef>int
<function>sd_bus_get_timeout
</function></funcdef>
47 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
48 <paramdef>uint64_t *
<parameter>timeout_usec
</parameter></paramdef>
54 <title>Description
</title>
56 <para><function>sd_bus_get_fd()
</function> returns the file descriptor used to communicate from a message bus
57 object. This descriptor can be used with
<citerefentry
58 project='man-pages'
><refentrytitle>poll
</refentrytitle><manvolnum>3</manvolnum></citerefentry> or a similar
59 function to wait for I/O events on the specified bus connection object. If the bus object was configured with the
60 <citerefentry><refentrytitle>sd_bus_set_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry> function, then
61 the
<parameter>input_fd
</parameter> file descriptor used in that call is returned.
</para>
63 <para><function>sd_bus_get_events()
</function> returns the I/O events to wait for, suitable for passing to
64 <function>poll()
</function> or a similar call. Returns a combination of
<constant>POLLIN
</constant>,
65 <constant>POLLOUT
</constant>, … events, or negative on error.
</para>
67 <para><function>sd_bus_get_timeout()
</function> returns the time-out in µs to pass to to
68 <function>poll()
</function> or a similar call when waiting for events on the specified bus connection. The returned
69 time-out may be zero, in which case a subsequent I/O polling call should be invoked in non-blocking mode. The
70 returned timeout may be
<constant>UINT64_MAX
</constant> in which case the I/O polling call may block indefinitely,
71 without any applied time-out. Note that the returned time-out should be considered only a maximum sleeping time. It
72 is permissible (and even expected) that shorter time-outs are used by the calling program, in case other event
73 sources are polled in the same event loop. Note that the returned time-value is relative and specified in
74 microseconds. When converting this value in order to pass it as third argument to
<function>poll()
</function>
75 (which expects milliseconds), care should be taken to use a division that rounds up to ensure the I/O polling
76 operation doesn't sleep for shorter than necessary, which might result in unintended busy looping (alternatively,
77 use
<citerefentry project='man-pages'
><refentrytitle>ppoll
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
78 instead of plain
<function>poll()
</function>, which understands time-outs with nano-second granularity).
</para>
80 <para>These three functions are useful to hook up a bus connection object with an external or manual event loop
81 involving
<function>poll()
</function> or a similar I/O polling call. Before each invocation of the I/O polling
82 call, all three functions should be invoked: the file descriptor returned by
<function>sd_bus_get_fd()
</function>
83 should be polled for the events indicated by
<function>sd_bus_get_events()
</function>, and the I/O call should
84 block for that up to the time-out returned by
<function>sd_bus_get_timeout()
</function>. After each I/O polling
85 call the bus connection needs to process incoming or outgoing data, by invoking
86 <citerefentry><refentrytitle>sd_bus_process
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
88 <para>Note that these function are only one of three supported ways to implement I/O event handling for bus
89 connections. Alternatively use
90 <citerefentry><refentrytitle>sd_bus_attach_event
</refentrytitle><manvolnum>3</manvolnum></citerefentry> to attach a
91 bus connection to an
<citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
92 event loop. Or use
<citerefentry><refentrytitle>sd_bus_wait
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
93 as a simple synchronous, blocking I/O waiting call.
</para>
97 <title>Return Value
</title>
99 <para><function>sd_bus_get_fd()
</function> returns the file descriptor used for communication, or a negative
100 <varname>errno
</varname>-style error code on error.
</para>
102 <para><function>sd_bus_get_events()
</function> returns the I/O event mask to use for I/O event watching, or a
103 negative
<varname>errno
</varname>-style error code on error.
</para>
105 <para><function>sd_bus_get_timeout()
</function> returns zero or positive on success, or a negative
106 <varname>errno
</varname>-style error code on error.
</para>
109 <title>Errors
</title>
111 <para>Returned errors may indicate the following problems:
</para>
115 <term><constant>-EINVAL
</constant></term>
117 <listitem><para>An invalid bus object was passed.
</para></listitem>
121 <term><constant>-ECHILD
</constant></term>
123 <listitem><para>The bus connection was allocated in a parent process and is being reused in a child
124 process after
<function>fork()
</function>.
</para></listitem>
128 <term><constant>-ENOTCONN
</constant></term>
130 <listitem><para>The bus connection has been terminated.
</para></listitem>
134 <term><constant>-EPERM
</constant></term>
136 <listitem><para>Two distinct file descriptors were passed for input and output using
137 <function>sd_bus_set_fd()
</function>, which
<function>sd_bus_get_fd()
</function> cannot
138 return.
</para></listitem>
144 <xi:include href=
"libsystemd-pkgconfig.xml" />
147 <title>See Also
</title>
150 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
151 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
152 <citerefentry><refentrytitle>sd_bus_set_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
153 <citerefentry><refentrytitle>sd_bus_process
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
154 <citerefentry><refentrytitle>sd_bus_attach_event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
155 <citerefentry><refentrytitle>sd_bus_wait
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
156 <citerefentry project='man-pages'
><refentrytitle>poll
</refentrytitle><manvolnum>3</manvolnum></citerefentry>