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">
6 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2014 Zbigniew Jędrzejewski-Szmek
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.
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.
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/>.
26 <refentry id=
"sd_event_source_set_description" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
29 <title>sd_event_source_set_description
</title>
30 <productname>systemd
</productname>
34 <contrib>More text
</contrib>
35 <firstname>Zbigniew
</firstname>
36 <surname>Jędrzejewski-Szmek
</surname>
37 <email>zbyszek@in.waw.pl
</email>
43 <refentrytitle>sd_event_source_set_description
</refentrytitle>
44 <manvolnum>3</manvolnum>
48 <refname>sd_event_source_set_description
</refname>
49 <refname>sd_event_source_get_description
</refname>
51 <refpurpose>Set or retrieve descriptive names of event sources
</refpurpose>
56 <funcsynopsisinfo>#include
<systemd/sd-event.h
></funcsynopsisinfo>
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>
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>
74 <title>Description
</title>
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>
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>
98 <para>Event source objects generally have no description set when
99 they are created, except for UNIX signal event sources created
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>
108 <title>Return Value
</title>
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>
117 <title>Errors
</title>
119 <para>Returned errors may indicate the following problems:
</para>
123 <term><constant>-EINVAL
</constant></term>
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>
133 <term><constant>-ENOMEM
</constant></term>
135 <listitem><para>Not enough memory to copy the
136 name.
</para></listitem>
140 <term><constant>-ECHILD
</constant></term>
142 <listitem><para>The event loop has been created in a different process.
</para></listitem>
147 <term><constant>-ENXIO
</constant></term>
149 <listitem><para>No name was set for the event
150 source.
</para></listitem>
156 <xi:include href=
"libsystemd-pkgconfig.xml" />
159 <title>See Also
</title>
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>