man/sd_bus_set_exit_on_disconnect.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 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="sd_bus_set_exit_on_disconnect"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_bus_set_exit_on_disconnect</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_bus_set_exit_on_disconnect</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_bus_set_exit_on_disconnect</refname>
  21     <refname>sd_bus_get_exit_on_disconnect</refname>
  22
  23     <refpurpose>Control the exit behavior when the bus object disconnects</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv>
  27     <funcsynopsis>
  28       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  29
  30       <funcprototype>
  31         <funcdef>int <function>sd_bus_set_exit_on_disconnect</function></funcdef>
  32         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  33         <paramdef>int <parameter>b</parameter></paramdef>
  34       </funcprototype>
  35
  36       <funcprototype>
  37         <funcdef>int <function>sd_bus_get_exit_on_disconnect</function></funcdef>
  38         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  39       </funcprototype>
  40     </funcsynopsis>
  41   </refsynopsisdiv>
  42
  43   <refsect1>
  44     <title>Description</title>
  45
  46     <para><function>sd_bus_set_exit_on_disconnect()</function> may be used to configure the exit
  47     behavior when the given bus object disconnects. If <parameter>b</parameter> is zero, no special
  48     logic is executed when the bus object disconnects. If <parameter>b</parameter> is non-zero, the
  49     behavior on disconnect depends on whether the bus object is attached to an event loop or not. If
  50     the bus object is attached to an event loop (see
  51     <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>),
  52     the event loop is closed when the bus object disconnects (as if calling
  53     <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
  54     Otherwise,
  55     <citerefentry project='man-pages'><refentrytitle>exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  56     is called. The exit code passed to <function>sd_event_exit()</function> and
  57     <function>exit()</function> is <constant>EXIT_FAILURE</constant>. If the bus object has already
  58     disconnected when enabling the exit behavior, the exit behavior is executed immediately. By
  59     default, the exit behavior is disabled.</para>
  60
  61     <para><function>sd_bus_get_exit_on_disconnect()</function> returns whether the exit on
  62     disconnect behavior is enabled for the given bus object.</para>
  63   </refsect1>
  64
  65   <refsect1>
  66     <title>Return Value</title>
  67
  68     <para>On success, <function>sd_bus_set_exit_on_disconnect()</function> returns a non-negative
  69     integer. On failure, it returns a negative errno-style error code.</para>
  70
  71     <para><function>sd_bus_get_exit_on_disconnect()</function> returns a positive integer if the
  72     exit on disconnect behavior is enabled. Otherwise, it returns zero.</para>
  73
  74     <refsect2>
  75       <title>Errors</title>
  76
  77       <para>Returned errors may indicate the following problems:</para>
  78
  79       <variablelist>
  80         <varlistentry>
  81           <term><constant>-EINVAL</constant></term>
  82
  83           <listitem><para>A required parameter was <constant>NULL</constant>.</para></listitem>
  84         </varlistentry>
  85
  86         <varlistentry>
  87           <term><constant>-ENOPKG</constant></term>
  88
  89           <listitem><para>The bus object could not be resolved.</para></listitem>
  90         </varlistentry>
  91
  92         <varlistentry>
  93           <term><constant>-ECHILD</constant></term>
  94
  95           <listitem><para>The bus connection was created in a different process.</para></listitem>
  96         </varlistentry>
  97       </variablelist>
  98     </refsect2>
  99   </refsect1>
 100
 101   <xi:include href="libsystemd-pkgconfig.xml" />
 102
 103   <refsect1>
 104     <title>See Also</title>
 105
 106     <para>
 107       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 108       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 109       <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 110       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 111       <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 112     </para>
 113   </refsect1>
 114 </refentry>