[thirdparty/systemd.git] / man / sd_bus_new.xml

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  SPDX-License-Identifier: LGPL-2.1+
-->

<refentry id="sd_bus_new" xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>sd_bus_new</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sd_bus_new</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>sd_bus_new</refname>
    <refname>sd_bus_ref</refname>
    <refname>sd_bus_unref</refname>
    <refname>sd_bus_unrefp</refname>
    <refname>sd_bus_close_unref</refname>
    <refname>sd_bus_close_unrefp</refname>
    <refname>sd_bus_flush_close_unref</refname>
    <refname>sd_bus_flush_close_unrefp</refname>

    <refpurpose>Create a new bus object and create or destroy references to it</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>

      <funcprototype>
        <funcdef>int <function>sd_bus_new</function></funcdef>
        <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sd_bus *<function>sd_bus_ref</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sd_bus *<function>sd_bus_close_unref</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sd_bus *<function>sd_bus_flush_close_unref</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>void <function>sd_bus_unrefp</function></funcdef>
        <paramdef>sd_bus **<parameter>busp</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>void <function>sd_bus_close_unrefp</function></funcdef>
        <paramdef>sd_bus **<parameter>busp</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>void <function>sd_bus_flush_close_unrefp</function></funcdef>
        <paramdef>sd_bus **<parameter>busp</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><function>sd_bus_new()</function> creates a new bus
    object. This object is reference-counted, and will be destroyed
    when all references are gone. Initially, the caller of this
    function owns the sole reference and the bus object will not be
    connected to any bus. To connect it to a bus, make sure
    to set an address with
    <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    or a related call, and then start the connection with
    <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>

    <para>In most cases, it is a better idea to invoke
    <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    or related calls instead of the more low-level
    <function>sd_bus_new()</function> and
    <function>sd_bus_start()</function>. The higher-level calls not
    only allocate a bus object but also start the connection to a
    well-known bus in a single function invocation.</para>

    <para><function>sd_bus_ref()</function> increases the reference
    counter of <parameter>bus</parameter> by one.</para>

    <para><function>sd_bus_unref()</function> decreases the reference
    counter of <parameter>bus</parameter> by one. Once the reference
    count has dropped to zero, <parameter>bus</parameter> is destroyed
    and cannot be used anymore, so further calls to
    <function>sd_bus_ref()</function> or
    <function>sd_bus_unref()</function> are illegal.</para>

    <para><function>sd_bus_unrefp()</function> is similar to
    <function>sd_bus_unref()</function> but takes a pointer to a
    pointer to an <type>sd_bus</type> object. This call is useful in
    conjunction with GCC's and LLVM's <ulink
    url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
    Variable Attribute</ulink>. Note that this function is defined as
    inline function. Use a declaration like the following, in order to
    allocate a bus object that is freed automatically as the code
    block is left:</para>

    <programlisting>{
  __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
  int r;
  …
  r = sd_bus_default(&amp;bus);
  if (r &lt; 0)
    fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r));
  …
}</programlisting>

    <para><function>sd_bus_ref()</function> and <function>sd_bus_unref()</function>
    execute no operation if the passed in bus object address is
    <constant>NULL</constant>. <function>sd_bus_unrefp()</function> will first
    dereference its argument, which must not be <constant>NULL</constant>, and will
    execute no operation if <emphasis>that</emphasis> is <constant>NULL</constant>.
    </para>

    <para><function>sd_bus_close_unref()</function> is similar to <function>sd_bus_unref()</function>, but
    first executes
    <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    ensuring that the connection is terminated before the reference to the connection is dropped and possibly
    the object freed.</para>

    <para><function>sd_bus_flush_close_unref()</function> is similar to <function>sd_bus_unref()</function>,
    but first executes
    <citerefentry><refentrytitle>sd_bus_flush</refentrytitle><manvolnum>3</manvolnum></citerefentry> as well
    as <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    ensuring that any pending messages are synchronously flushed out before the reference to the connection
    is dropped and possibly the object freed. This call is particularly useful immediately before exiting
    from a program as it ensures that any pending outgoing messages are written out, and unprocessed but
    queued incoming messages released before the connection is terminated and released.</para>

    <para><function>sd_bus_close_unrefp()</function> is similar to
    <function>sd_bus_close_unref()</function>, but may be used in GCC's and LLVM's Clean-up Variable
    Attribute, see above. Similarly, <function>sd_bus_flush_close_unrefp()</function> is similar to
    <function>sd_bus_flush_close_unref()</function>.</para>
  </refsect1>

  <refsect1>
    <title>Return Value</title>

    <para>On success, <function>sd_bus_new()</function> returns 0 or a
    positive integer. On failure, it returns a negative errno-style
    error code.</para>

    <para><function>sd_bus_ref()</function> always returns the argument.
    </para>

    <para><function>sd_bus_unref()</function> and <function>sd_bus_flush_close_unref()</function> always return
    <constant>NULL</constant>.</para>
  </refsect1>

  <refsect1>
    <title>Errors</title>

    <para>Returned errors may indicate the following problems:</para>

    <variablelist>
      <varlistentry>
        <term><constant>-ENOMEM</constant></term>

        <listitem><para>Memory allocation failed.</para></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <xi:include href="libsystemd-pkgconfig.xml" />

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>
Commit	Line	Data
514094f9	1	<?xml version='1.0'?>
cd6d5e1c	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76	3	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
cd6d5e1c ZJS	4
cd6d5e1c ZJS	5	<!--
572eb058	6	SPDX-License-Identifier: LGPL-2.1+
cd6d5e1c ZJS	7	-->
cd6d5e1c ZJS	8
7d6b2723	9	<refentry id="sd_bus_new" xmlns:xi="http://www.w3.org/2001/XInclude">
cd6d5e1c ZJS	10
	11	<refentryinfo>
	12	<title>sd_bus_new</title>
	13	<productname>systemd</productname>
cd6d5e1c ZJS	14	</refentryinfo>
	15
	16	<refmeta>
	17	<refentrytitle>sd_bus_new</refentrytitle>
	18	<manvolnum>3</manvolnum>
	19	</refmeta>
	20
	21	<refnamediv>
	22	<refname>sd_bus_new</refname>
	23	<refname>sd_bus_ref</refname>
	24	<refname>sd_bus_unref</refname>
4afd3348	25	<refname>sd_bus_unrefp</refname>
bd62b744 LP	26	<refname>sd_bus_close_unref</refname>
bd62b744 LP	27	<refname>sd_bus_close_unrefp</refname>
eda0d9a1 LP	28	<refname>sd_bus_flush_close_unref</refname>
eda0d9a1 LP	29	<refname>sd_bus_flush_close_unrefp</refname>
cd6d5e1c ZJS	30
	31	<refpurpose>Create a new bus object and create or destroy references to it</refpurpose>
	32	</refnamediv>
	33
	34	<refsynopsisdiv>
	35	<funcsynopsis>
	36	<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
	37
	38	<funcprototype>
	39	<funcdef>int <function>sd_bus_new</function></funcdef>
8dc385e7	40	<paramdef>sd_bus **<parameter>bus</parameter></paramdef>
cd6d5e1c ZJS	41	</funcprototype>
	42
	43	<funcprototype>
8dc385e7 JE	44	<funcdef>sd_bus *<function>sd_bus_ref</function></funcdef>
8dc385e7 JE	45	<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
cd6d5e1c ZJS	46	</funcprototype>
	47
	48	<funcprototype>
8dc385e7 JE	49	<funcdef>sd_bus *<function>sd_bus_unref</function></funcdef>
8dc385e7 JE	50	<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
cd6d5e1c	51	</funcprototype>
4afd3348 LP	52
4afd3348 LP	53	<funcprototype>
bd62b744 LP	54	<funcdef>sd_bus *<function>sd_bus_close_unref</function></funcdef>
bd62b744 LP	55	<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
4afd3348	56	</funcprototype>
eda0d9a1 LP	57
	58	<funcprototype>
	59	<funcdef>sd_bus *<function>sd_bus_flush_close_unref</function></funcdef>
	60	<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
	61	</funcprototype>
	62
bd62b744 LP	63	<funcprototype>
	64	<funcdef>void <function>sd_bus_unrefp</function></funcdef>
	65	<paramdef>sd_bus **<parameter>busp</parameter></paramdef>
	66	</funcprototype>
	67
	68	<funcprototype>
	69	<funcdef>void <function>sd_bus_close_unrefp</function></funcdef>
	70	<paramdef>sd_bus **<parameter>busp</parameter></paramdef>
	71	</funcprototype>
	72
eda0d9a1 LP	73	<funcprototype>
	74	<funcdef>void <function>sd_bus_flush_close_unrefp</function></funcdef>
	75	<paramdef>sd_bus **<parameter>busp</parameter></paramdef>
	76	</funcprototype>
cd6d5e1c ZJS	77	</funcsynopsis>
	78	</refsynopsisdiv>
	79
	80	<refsect1>
	81	<title>Description</title>
	82
	83	<para><function>sd_bus_new()</function> creates a new bus
73e231ab	84	object. This object is reference-counted, and will be destroyed
cd6d5e1c	85	when all references are gone. Initially, the caller of this
db03761e UTL	86	function owns the sole reference and the bus object will not be
db03761e UTL	87	connected to any bus. To connect it to a bus, make sure
850df10a LP	88	to set an address with
	89	<citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
	90	or a related call, and then start the connection with
	91	<citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
	92
7ca41557	93	<para>In most cases, it is a better idea to invoke
850df10a LP	94	<citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	95	<citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
	96	or related calls instead of the more low-level
	97	<function>sd_bus_new()</function> and
	98	<function>sd_bus_start()</function>. The higher-level calls not
	99	only allocate a bus object but also start the connection to a
	100	well-known bus in a single function invocation.</para>
cd6d5e1c	101
4afd3348 LP	102	<para><function>sd_bus_ref()</function> increases the reference
4afd3348 LP	103	counter of <parameter>bus</parameter> by one.</para>
cd6d5e1c	104
4afd3348 LP	105	<para><function>sd_bus_unref()</function> decreases the reference
	106	counter of <parameter>bus</parameter> by one. Once the reference
	107	count has dropped to zero, <parameter>bus</parameter> is destroyed
	108	and cannot be used anymore, so further calls to
	109	<function>sd_bus_ref()</function> or
db03761e	110	<function>sd_bus_unref()</function> are illegal.</para>
4afd3348 LP	111
	112	<para><function>sd_bus_unrefp()</function> is similar to
	113	<function>sd_bus_unref()</function> but takes a pointer to a
	114	pointer to an <type>sd_bus</type> object. This call is useful in
	115	conjunction with GCC's and LLVM's <ulink
	116	url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
	117	Variable Attribute</ulink>. Note that this function is defined as
	118	inline function. Use a declaration like the following, in order to
	119	allocate a bus object that is freed automatically as the code
	120	block is left:</para>
	121
	122	<programlisting>{
787f78b6 ZJS	123	__attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
	124	int r;
	125	…
	126	r = sd_bus_default(&bus);
	127	if (r < 0)
	128	fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r));
	129	…
4afd3348 LP	130	}</programlisting>
4afd3348 LP	131
2c47fff6 ZJS	132	<para><function>sd_bus_ref()</function> and <function>sd_bus_unref()</function>
	133	execute no operation if the passed in bus object address is
	134	<constant>NULL</constant>. <function>sd_bus_unrefp()</function> will first
	135	dereference its argument, which must not be <constant>NULL</constant>, and will
	136	execute no operation if <emphasis>that</emphasis> is <constant>NULL</constant>.
	137	</para>
eda0d9a1	138
bd62b744 LP	139	<para><function>sd_bus_close_unref()</function> is similar to <function>sd_bus_unref()</function>, but
	140	first executes
	141	<citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	142	ensuring that the connection is terminated before the reference to the connection is dropped and possibly
	143	the object freed.</para>
	144
	145	<para><function>sd_bus_flush_close_unref()</function> is similar to <function>sd_bus_unref()</function>,
	146	but first executes
	147	<citerefentry><refentrytitle>sd_bus_flush</refentrytitle><manvolnum>3</manvolnum></citerefentry> as well
	148	as <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	149	ensuring that any pending messages are synchronously flushed out before the reference to the connection
	150	is dropped and possibly the object freed. This call is particularly useful immediately before exiting
	151	from a program as it ensures that any pending outgoing messages are written out, and unprocessed but
	152	queued incoming messages released before the connection is terminated and released.</para>
	153
	154	<para><function>sd_bus_close_unrefp()</function> is similar to
	155	<function>sd_bus_close_unref()</function>, but may be used in GCC's and LLVM's Clean-up Variable
	156	Attribute, see above. Similarly, <function>sd_bus_flush_close_unrefp()</function> is similar to
	157	<function>sd_bus_flush_close_unref()</function>.</para>
cd6d5e1c ZJS	158	</refsect1>
	159
	160	<refsect1>
	161	<title>Return Value</title>
	162
	163	<para>On success, <function>sd_bus_new()</function> returns 0 or a
	164	positive integer. On failure, it returns a negative errno-style
	165	error code.</para>
	166
4afd3348	167	<para><function>sd_bus_ref()</function> always returns the argument.
cd6d5e1c ZJS	168	</para>
cd6d5e1c ZJS	169
eda0d9a1	170	<para><function>sd_bus_unref()</function> and <function>sd_bus_flush_close_unref()</function> always return
cd6d5e1c ZJS	171	<constant>NULL</constant>.</para>
	172	</refsect1>
	173
	174	<refsect1>
	175	<title>Errors</title>
	176
	177	<para>Returned errors may indicate the following problems:</para>
	178
	179	<variablelist>
	180	<varlistentry>
8474b70c	181	<term><constant>-ENOMEM</constant></term>
cd6d5e1c ZJS	182
	183	<listitem><para>Memory allocation failed.</para></listitem>
	184	</varlistentry>
	185	</variablelist>
	186	</refsect1>
	187
7d6b2723	188	<xi:include href="libsystemd-pkgconfig.xml" />
cd6d5e1c ZJS	189
	190	<refsect1>
	191	<title>See Also</title>
	192
	193	<para>
	194	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	195	<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
cd6d5e1c	196	<citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
850df10a LP	197	<citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
850df10a LP	198	<citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
eda0d9a1 LP	199	<citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
eda0d9a1 LP	200	<citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>
cd6d5e1c ZJS	201	</para>
	202	</refsect1>
	203
	204	</refentry>