'\" t
.TH "SD_EVENT_SOURCE_UNREF" "3" "" "systemd 256.8" "sd_event_source_unref"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sd_event_source_unref, sd_event_source_unrefp, sd_event_source_ref, sd_event_source_disable_unref, sd_event_source_disable_unrefp \- Increase or decrease event source reference counters
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-event\&.h>
.fi
.ft
.HP \w'sd_event_source*\ sd_event_source_unref('u
.BI "sd_event_source* sd_event_source_unref(sd_event_source\ *" "source" ");"
.HP \w'void\ sd_event_source_unrefp('u
.BI "void sd_event_source_unrefp(sd_event_source\ **" "source" ");"
.HP \w'sd_event_source*\ sd_event_source_ref('u
.BI "sd_event_source* sd_event_source_ref(sd_event_source\ *" "source" ");"
.HP \w'sd_event_source*\ sd_event_source_disable_unref('u
.BI "sd_event_source* sd_event_source_disable_unref(sd_event_source\ *" "source" ");"
.HP \w'void\ sd_event_source_disable_unrefp('u
.BI "void sd_event_source_disable_unrefp(sd_event_source\ **" "source" ");"
.SH "DESCRIPTION"
.PP
\fBsd_event_source_unref()\fR
may be used to decrement by one the internal reference counter of the event source object specified as
\fIsource\fR\&. The reference counter is initially set to one, when the event source is created with calls such as
\fBsd_event_add_io\fR(3)
or
\fBsd_event_add_time\fR(3)\&. When the reference counter reaches zero, the object is detached from the event loop object and destroyed\&.
.PP
\fBsd_event_source_unrefp()\fR
is similar to
\fBsd_event_source_unref()\fR
but takes a pointer to a pointer to an
\fBsd_event_source\fR
object\&. This call is useful in conjunction with GCC\*(Aqs and LLVM\*(Aqs
\m[blue]\fBClean\-up Variable Attribute\fR\m[]\&\s-2\u[1]\d\s+2\&. Note that this function is defined as inline function\&.
.PP
\fBsd_event_source_ref()\fR
may be used to increase by one the internal reference counter of the event source object specified as
\fIsource\fR\&.
.PP
\fBsd_event_source_unref()\fR,
\fBsd_bus_creds_unrefp()\fR
and
\fBsd_bus_creds_ref()\fR
execute no operation if the passed event source object is
\fBNULL\fR\&.
.PP
Note that event source objects stay alive and may be dispatched as long as they have a reference counter greater than zero\&. In order to drop a reference of an event source and make sure the associated event source handler function is not called anymore it is recommended to combine a call of
\fBsd_event_source_unref()\fR
with a prior call to
\fBsd_event_source_set_enabled()\fR
with
\fBSD_EVENT_OFF\fR
or call
\fBsd_event_source_disable_unref()\fR, see below\&.
.PP
\fBsd_event_source_disable_unref()\fR
combines a call to
\fBsd_event_source_set_enabled()\fR
with
\fBSD_EVENT_OFF\fR
with
\fBsd_event_source_unref()\fR\&. This ensures that the source is disabled before the local reference to it is lost\&. The
\fIsource\fR
parameter is allowed to be
\fBNULL\fR\&.
.PP
\fBsd_event_source_disable_unrefp()\fR
is similar to
\fBsd_event_source_unrefp()\fR, but in addition disables the source first\&. This call is useful in conjunction with GCC\*(Aqs and LLVM\*(Aqs
\m[blue]\fBClean\-up Variable Attribute\fR\m[]\&\s-2\u[1]\d\s+2\&. Note that this function is defined as inline function\&.
.SH "RETURN VALUE"
.PP
\fBsd_event_source_unref()\fR
and
\fBsd_event_source_disable_unref()\fR
always return
\fBNULL\fR\&.
\fBsd_event_source_ref()\fR
always returns the event source object passed in\&.
.SH "NOTES"
.PP
Functions described here are available as a shared library, which can be compiled against and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.PP
The code described here uses
\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
\fBsetenv\fR(3)
from a parallel thread\&. It is recommended to only do calls to
\fBsetenv()\fR
from an early phase of the program when no other threads have been started\&.
.SH "HISTORY"
.PP
\fBsd_event_source_unref()\fR,
\fBsd_event_source_unrefp()\fR, and
\fBsd_event_source_ref()\fR
were added in version 229\&.
.PP
\fBsd_event_source_disable_unref()\fR
and
\fBsd_event_source_disable_unrefp()\fR
were added in version 243\&.
.SH "SEE ALSO"
.PP
\fBsd-event\fR(3), \fBsd_event_add_io\fR(3), \fBsd_event_add_time\fR(3), \fBsd_event_add_signal\fR(3), \fBsd_event_add_child\fR(3), \fBsd_event_add_inotify\fR(3), \fBsd_event_add_defer\fR(3), \fBsd_event_source_set_enabled\fR(3)
.SH "NOTES"
.IP " 1." 4
Clean-up Variable Attribute
.RS 4
\%https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
.RE