sd_event_source_set_description, sd_event_source_get_description — Set or retrieve descriptive names of event sources
#include <systemd/sd-event.h>
int sd_event_source_set_description( | sd_event_source *source, |
const char *description) ; |
int sd_event_source_get_description( | sd_event_source *source, |
const char **description) ; |
sd_event_source_set_description()
may
be used to set an arbitrary descriptive name for the event source
object specified as source
. This name will
be used in debugging messages generated by
sd-event(3)
for this event source, and may be queried using
sd_event_source_get_description()
for
debugging purposes. The description
parameter shall
point to a NUL
-terminated string or be
NULL
. In the latter case, the descriptive
name will be unset. The string is copied internally, hence the
description
argument is not referenced
after the function returns.
sd_event_source_get_description()
may
be used to query the current descriptive name assigned to the
event source object source
. It returns a
pointer to the current name in description
,
stored in memory internal to the event source. The memory is
invalidated when the event source is destroyed or the descriptive
name is changed.
Event source objects generally have no description set when
they are created, except for UNIX signal event sources created
with
sd_event_add_signal(3),
whose descriptive name is initialized to the signal's C constant
name (e.g. "SIGINT
" or
"SIGTERM
").
On success, sd_event_source_set_description()
and
sd_event_source_get_description()
return a non-negative integer. On failure, they
return a negative errno-style error code.
Returned errors may indicate the following problems:
-EINVAL
¶source
is not a valid pointer to an
sd_event_source object or the description
argument
for sd_event_source_get_description()
is NULL
.
-ENOMEM
¶Not enough memory to copy the name.
-ECHILD
¶The event loop has been created in a different process, library or module instance.
-ENXIO
¶No name was set for the event source.
Functions described here are available as a shared
library, which can be compiled against and linked to with the
libsystemd
pkg-config(1)
file.
The code described here uses
getenv(3),
which is declared to be not multi-thread-safe. This means that the code calling the functions described
here must not call
setenv(3)
from a parallel thread. It is recommended to only do calls to setenv()
from an early phase of the program when no other threads have been started.
sd_event_source_set_description()
and
sd_event_source_get_description()
were added in version 229.