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<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_bus_attach_event" 7 xmlns:xi="http://www.w3.org/2001/XInclude"> 8 9 <refentryinfo> 10 <title>sd_bus_attach_event</title> 11 <productname>systemd</productname> 12 </refentryinfo> 13 14 <refmeta> 15 <refentrytitle>sd_bus_attach_event</refentrytitle> 16 <manvolnum>3</manvolnum> 17 </refmeta> 18 19 <refnamediv> 20 <refname>sd_bus_attach_event</refname> 21 <refname>sd_bus_detach_event</refname> 22 <refname>sd_bus_get_event</refname> 23 24 <refpurpose>Attach a bus connection object to an event loop</refpurpose> 25 </refnamediv> 26 27 <refsynopsisdiv> 28 <funcsynopsis> 29 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> 30 31 <funcprototype> 32 <funcdef>int <function>sd_bus_attach_event</function></funcdef> 33 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 34 <paramdef>sd_event *<parameter>e</parameter></paramdef> 35 <paramdef>int <parameter>priority</parameter></paramdef> 36 </funcprototype> 37 38 <funcprototype> 39 <funcdef>int <function>sd_bus_detach_event</function></funcdef> 40 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 41 </funcprototype> 42 43 <funcprototype> 44 <funcdef>sd_event *<function>sd_bus_get_event</function></funcdef> 45 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 46 </funcprototype> 47 </funcsynopsis> 48 </refsynopsisdiv> 49 50 <refsect1> 51 <title>Description</title> 52 53 <para><function>sd_bus_attach_event()</function> attaches the specified bus connection object to an 54 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> event loop object at 55 the specified priority (see 56 <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry> 57 for details on event loop priorities). When a bus connection object is attached to an event loop incoming messages 58 will be automatically read and processed, and outgoing messages written, whenever the event loop is run. When the 59 event loop is about to terminate, the bus connection is automatically flushed and closed (see 60 <citerefentry><refentrytitle>sd_bus_set_close_on_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> for 61 details on this). By default bus connection objects are not attached to any event loop. When a bus connection 62 object is attached to one it is not necessary to invoke 63 <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> or 64 <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry> as this 65 functionality is handled automatically by the event loop.</para> 66 67 <para><function>sd_bus_detach_event()</function> detaches a bus object from its event loop.</para> 68 69 <para>The <function>sd_bus_get_event()</function> returns the event loop object the specified bus object is 70 currently attached to, or <constant>NULL</constant> if it is currently not attached to any.</para> 71 72 <para>Note that <function>sd_bus_attach_event()</function> is only one of three supported ways to implement I/O 73 event handling for bus connections. Alternatively use 74 <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> for hooking up a 75 bus connection object with external or manual event loops. Or use 76 <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> as a simple 77 synchronous, blocking I/O waiting call.</para> 78 </refsect1> 79 80 <refsect1> 81 <title>Return Value</title> 82 83 <para>On success, <function>sd_bus_attach_event()</function> and <function>sd_bus_detach_event()</function> return 84 0 or a positive integer. On failure, they return a negative errno-style error code.</para> 85 86 <para><function>sd_bus_get_event()</function> returns an event loop object or <constant>NULL</constant>.</para> 87 88 <refsect2> 89 <title>Errors</title> 90 91 <para>Returned errors may indicate the following problems:</para> 92 93 <variablelist> 94 <varlistentry> 95 <term><constant>-ECHILD</constant></term> 96 97 <listitem><para>The bus connection has been created in a different process.</para></listitem> 98 </varlistentry> 99 </variablelist> 100 </refsect2> 101 </refsect1> 102 103 <xi:include href="libsystemd-pkgconfig.xml" /> 104 105 <refsect1> 106 <title>See Also</title> 107 108 <para> 109 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 110 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 111 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 112 <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 113 <citerefentry><refentrytitle>sd_bus_set_close_on_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 114 <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 115 <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> 116 </para> 117 </refsect1> 118 119</refentry> 120