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_slot_set_description" xmlns:xi="http://www.w3.org/2001/XInclude">
7  <refentryinfo>
8    <title>sd_bus_slot_set_description</title>
9    <productname>systemd</productname>
10  </refentryinfo>
11
12  <refmeta>
13    <refentrytitle>sd_bus_slot_set_description</refentrytitle>
14    <manvolnum>3</manvolnum>
15  </refmeta>
16
17  <refnamediv>
18    <refname>sd_bus_slot_set_description</refname>
19    <refname>sd_bus_slot_get_description</refname>
20
21    <refpurpose>Set or query the description of bus slot objects</refpurpose>
22  </refnamediv>
23
24  <refsynopsisdiv>
25    <funcsynopsis>
26      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
27
28      <funcprototype>
29        <funcdef>int <function>sd_bus_slot_set_description</function></funcdef>
30        <paramdef>sd_bus_slot* <parameter>slot</parameter></paramdef>
31        <paramdef>const char *<parameter>description</parameter></paramdef>
32      </funcprototype>
33
34      <funcprototype>
35        <funcdef>int <function>sd_bus_slot_get_description</function></funcdef>
36        <paramdef>sd_bus_slot* <parameter>bus</parameter></paramdef>
37        <paramdef>const char **<parameter>description</parameter></paramdef>
38      </funcprototype>
39    </funcsynopsis>
40  </refsynopsisdiv>
41
42  <refsect1>
43    <title>Description</title>
44
45    <para><function>sd_bus_slot_set_description()</function> sets the description string
46    that is used in logging to the specified string. The string is copied internally
47    and freed when the bus slot object is deallocated. The
48    <parameter>description</parameter> argument may be <constant>NULL</constant>, in
49    which case the description is unset.</para>
50
51    <para><function>sd_bus_slot_get_description()</function> returns a description string in
52    <parameter>description</parameter>. If the string is not set, e.g. with
53    <function>sd_bus_slot_set_description()</function>, and the slot is a bus match callback slot,
54    the match string will be returned. Otherwise, <constant>-ENXIO</constant> is returned.
55    </para>
56  </refsect1>
57
58  <refsect1>
59    <title>Return Value</title>
60
61    <para>On success, these functions return 0 or a positive integer. On failure,
62    they return a negative errno-style error code.</para>
63
64    <refsect2>
65      <title>Errors</title>
66
67      <para>Returned errors may indicate the following problems:</para>
68
69      <variablelist>
70        <varlistentry>
71          <term><constant>-EINVAL</constant></term>
72
73          <listitem><para>An required argument is <constant>NULL</constant>.</para></listitem>
74        </varlistentry>
75
76        <varlistentry>
77          <term><constant>-ENXIO</constant></term>
78
79          <listitem><para>The bus slot object has no description.</para></listitem>
80        </varlistentry>
81
82        <varlistentry>
83          <term><constant>-ENOMEM</constant></term>
84
85          <listitem><para>Memory allocation failed.</para></listitem>
86        </varlistentry>
87      </variablelist>
88
89    </refsect2>
90  </refsect1>
91
92  <xi:include href="libsystemd-pkgconfig.xml" />
93
94  <refsect1>
95    <title>See Also</title>
96
97    <para>
98      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
99      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>
100      <citerefentry><refentrytitle>sd_bus_slot_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
101      <citerefentry><refentrytitle>sd_bus_slot_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>
102    </para>
103  </refsect1>
104
105</refentry>
106