chiark / gitweb /
basic: split hash functions into their own header files
[elogind.git] / 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 elogind.
7
8   Copyright 2014 Zbigniew JÄ™drzejewski-Szmek
9
10   elogind 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   elogind 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 elogind; 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>elogind</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;elogind/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="libelogind-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>