man/sd_bus_slot_set_description.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_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>