dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering This file is part of systemd.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering Copyright 2014 Zbigniew Jędrzejewski-Szmek
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering systemd is free software; you can redistribute it and/or modify it
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering under the terms of the GNU Lesser General Public License as published by
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering (at your option) any later version.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering systemd is distributed in the hope that it will be useful, but
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering Lesser General Public License for more details.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering You should have received a copy of the GNU Lesser General Public License
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering<refentry id="sd_event_source_set_description" xmlns:xi="http://www.w3.org/2001/XInclude">
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <refentryinfo>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <title>sd_event_source_set_description</title>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </authorgroup>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </refentryinfo>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <refentrytitle>sd_event_source_set_description</refentrytitle>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <refname>sd_event_source_set_description</refname>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <refname>sd_event_source_get_description</refname>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <refpurpose>Set or retrieve descriptive names of event sources</refpurpose>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <refsynopsisdiv>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcsynopsis>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcprototype>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcdef>int <function>sd_event_source_set_description</function></funcdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>const char *<parameter>description</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </funcprototype>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcprototype>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcdef>int <function>sd_event_source_get_description</function></funcdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>const char **<parameter>description</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </funcprototype>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </funcsynopsis>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </refsynopsisdiv>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para><function>sd_event_source_set_description()</function> may
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering be used to set an arbitrary descriptive name for the event source
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering object specified as <parameter>source</parameter>. This name will
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering be used in debugging messages generated by
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering for this event source, and may be queried using
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_source_get_description()</function> for
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering debugging purposes. The <parameter>description</parameter> parameter shall
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering point to a <constant>NUL</constant>-terminated string or be
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>NULL</constant>. In the latter case, the descriptive
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering name will be unset. The string is copied internally, hence the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <parameter>description</parameter> argument is not referenced
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering after the function returns.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para><function>sd_event_source_get_description()</function> may
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering be used to query the current descriptive name assigned to the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering event source object <parameter>source</parameter>. It returns a
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering pointer to the current name in <parameter>description</parameter>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering stored in memory internal to the event source. The memory is
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering invalidated when the event source is destroyed or the descriptive
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering name is changed.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>Event source objects generally have no description set when
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering they are created, except for UNIX signal event sources created
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering whose descriptive name is initialized to the signal's C constant
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>On success, <function>sd_event_source_set_description()</function> and
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_source_get_description()</function> return a
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering non-negative integer. On failure, they return a negative
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering errno-style error code.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>Returned errors may indicate the following problems:</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <variablelist>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <term><constant>-EINVAL</constant></term>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para><parameter>source</parameter> is not a valid
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering pointer to an <structname>sd_event_source</structname>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering object or the <parameter>description</parameter> argument for
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_source_get_description()</function> is
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>NULL</constant>.</para></listitem>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <term><constant>-ENOMEM</constant></term>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para>Not enough memory to copy the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <term><constant>-ECHILD</constant></term>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para>The event loop has been created in a different process.</para></listitem>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <listitem><para>No name was set for the event
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </varlistentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </variablelist>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <xi:include href="libsystemd-pkgconfig.xml" />
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>