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