man/sd_event_source_set_description.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2014 Zbigniew Jędrzejewski-Szmek
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_event_source_set_description" xmlns:xi="http://www.w3.org/2001/XInclude">
  27
  28   <refentryinfo>
  29     <title>sd_event_source_set_description</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>More text</contrib>
  35         <firstname>Zbigniew</firstname>
  36         <surname>Jędrzejewski-Szmek</surname>
  37         <email>zbyszek@in.waw.pl</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>sd_event_source_set_description</refentrytitle>
  44     <manvolnum>3</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>sd_event_source_set_description</refname>
  49     <refname>sd_event_source_get_description</refname>
  50
  51     <refpurpose>Set or retrieve descriptive names of event sources</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <funcsynopsis>
  56       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  57
  58       <funcprototype>
  59         <funcdef>int <function>sd_event_source_set_description</function></funcdef>
  60         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  61         <paramdef>const char *<parameter>description</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>int <function>sd_event_source_get_description</function></funcdef>
  66         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  67         <paramdef>const char **<parameter>description</parameter></paramdef>
  68       </funcprototype>
  69
  70     </funcsynopsis>
  71   </refsynopsisdiv>
  72
  73   <refsect1>
  74     <title>Description</title>
  75
  76     <para><function>sd_event_source_set_description()</function> may
  77     be used to set an arbitrary descriptive name for the event source
  78     object specified as <parameter>source</parameter>. This name will
  79     be used in debugging messages generated by
  80     <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  81     for this event source, and may be queried using
  82     <function>sd_event_source_get_description()</function> for
  83     debugging purposes. The <parameter>description</parameter> parameter shall
  84     point to a <constant>NUL</constant>-terminated string or be
  85     <constant>NULL</constant>. In the latter case, the descriptive
  86     name will be unset. The string is copied internally, hence the
  87     <parameter>description</parameter> argument is not referenced
  88     after the function returns.</para>
  89
  90     <para><function>sd_event_source_get_description()</function> may
  91     be used to query the current descriptive name assigned to the
  92     event source object <parameter>source</parameter>. It returns a
  93     pointer to the current name in <parameter>description</parameter>,
  94     stored in memory internal to the event source. The memory is
  95     invalidated when the event source is destroyed or the descriptive
  96     name is changed.</para>
  97
  98     <para>Event source objects generally have no description set when
  99     they are created, except for UNIX signal event sources created
 100     with
 101     <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 102     whose descriptive name is initialized to the signal's C constant
 103     name (e.g. <literal>SIGINT</literal> or
 104     <literal>SIGTERM</literal>).</para>
 105   </refsect1>
 106
 107   <refsect1>
 108     <title>Return Value</title>
 109
 110     <para>On success, <function>sd_event_source_set_description()</function> and
 111     <function>sd_event_source_get_description()</function> return a
 112     non-negative integer. On failure, they return a negative
 113     errno-style error code.</para>
 114   </refsect1>
 115
 116   <refsect1>
 117     <title>Errors</title>
 118
 119     <para>Returned errors may indicate the following problems:</para>
 120
 121     <variablelist>
 122       <varlistentry>
 123         <term><constant>-EINVAL</constant></term>
 124
 125         <listitem><para><parameter>source</parameter> is not a valid
 126         pointer to an <structname>sd_event_source</structname>
 127         object or the <parameter>description</parameter> argument for
 128         <function>sd_event_source_get_description()</function> is
 129         <constant>NULL</constant>.</para></listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term><constant>-ENOMEM</constant></term>
 134
 135         <listitem><para>Not enough memory to copy the
 136         name.</para></listitem>
 137       </varlistentry>
 138
 139       <varlistentry>
 140         <term><constant>-ECHILD</constant></term>
 141
 142         <listitem><para>The event loop has been created in a different process.</para></listitem>
 143
 144       </varlistentry>
 145
 146       <varlistentry>
 147         <term><constant>-ENXIO</constant></term>
 148
 149         <listitem><para>No name was set for the event
 150         source.</para></listitem>
 151       </varlistentry>
 152
 153     </variablelist>
 154   </refsect1>
 155
 156   <xi:include href="libsystemd-pkgconfig.xml" />
 157
 158   <refsect1>
 159     <title>See Also</title>
 160
 161     <para>
 162       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 163       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 164       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 165       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 166       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 167       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 168       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 169     </para>
 170   </refsect1>
 171
 172 </refentry>