Debian Codegraph @

upstream/debian-unstable/man3/sd_event_new.3

raw
1 '\" t
2 .TH "SD_EVENT_NEW" "3" "" "systemd 261~rc3" "sd_event_new"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_event_new, sd_event_default, sd_event_ref, sd_event_unref, sd_event_unrefp, sd_event_get_tid, sd_event \- Acquire and release an event loop object
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-event\&.h>
29 .fi
30 .ft
31 .sp
32 .ft B
33 .nf
34 typedef struct sd_event sd_event;
35 .fi
36 .ft
37 .HP \w'int\ sd_event_new('u
38 .BI "int sd_event_new(sd_event\ **" "event" ");"
39 .HP \w'int\ sd_event_default('u
40 .BI "int sd_event_default(sd_event\ **" "event" ");"
41 .HP \w'sd_event\ *sd_event_ref('u
42 .BI "sd_event *sd_event_ref(sd_event\ *" "event" ");"
43 .HP \w'sd_event\ *sd_event_unref('u
44 .BI "sd_event *sd_event_unref(sd_event\ *" "event" ");"
45 .HP \w'void\ sd_event_unrefp('u
46 .BI "void sd_event_unrefp(sd_event\ **" "event" ");"
47 .HP \w'int\ sd_event_get_tid('u
48 .BI "int sd_event_get_tid(sd_event\ *" "event" ", pid_t\ *" "ret" ");"
49 .SH "DESCRIPTION"
50 .PP
51 \fBsd_event_new()\fR
52 allocates a new event loop object\&. The event loop object is returned in the
53 \fIevent\fR
54 parameter\&. After use, drop the returned reference with
55 \fBsd_event_unref()\fR\&. When the last reference is dropped, the object is freed\&.
56 .PP
57 \fBsd_event_default()\fR
58 acquires a reference to the default event loop object of the calling thread, possibly allocating a new object if no default event loop object has been allocated yet for the thread\&. After use, drop the returned reference with
59 \fBsd_event_unref()\fR\&. When the last reference is dropped, the event loop is freed\&. If this function is called while the object returned from a previous call from the same thread is still referenced, the same object is returned again, but the reference is increased by one\&. It is recommended to use this call instead of
60 \fBsd_event_new()\fR
61 in order to share event loop objects between various components that are dispatched in the same thread\&. All threads have exactly either zero or one default event loop objects associated, but never more\&.
62 .PP
63 After allocating an event loop object, add event sources to it with
64 \fBsd_event_add_io\fR(3),
65 \fBsd_event_add_time\fR(3),
66 \fBsd_event_add_signal\fR(3),
67 \fBsd_event_add_child\fR(3),
68 \fBsd_event_add_inotify\fR(3),
69 \fBsd_event_add_defer\fR(3),
70 \fBsd_event_add_post\fR(3)
71 or
72 \fBsd_event_add_exit\fR(3), and then execute the event loop using
73 \fBsd_event_loop\fR(3)\&.
74 .PP
75 \fBsd_event_ref()\fR
76 increases the reference count of the specified event loop object by one\&.
77 .PP
78 \fBsd_event_unref()\fR
79 decreases the reference count of the specified event loop object by one\&. If the count hits zero, the object is freed\&. Note that it is freed regardless of whether it is the default event loop object for a thread or not\&. This means that allocating an event loop with
80 \fBsd_event_default()\fR, then releasing it, and then acquiring a new one with
81 \fBsd_event_default()\fR
82 will result in two distinct objects\&. Note that, in order to free an event loop object, all remaining event sources of the event loop also need to be freed as each keeps a reference to it\&.
83 .PP
84 \fBsd_event_unrefp()\fR
85 is similar to
86 \fBsd_event_unref()\fR
87 but takes a pointer to a pointer to an
88 \fBsd_event\fR
89 object\&. This call is useful in conjunction with GCC\*(Aqs and LLVM\*(Aqs
90 \m[blue]\fBClean\-up Variable Attribute\fR\m[]\&\s-2\u[1]\d\s+2\&. Note that this function is defined as inline function\&. Use a declaration like the following, in order to allocate an event loop object that is freed automatically as the code block is left:
91 .sp
92 .if n \{\
93 .RS 4
94 .\}
95 .nf
96 {
97 __attribute__((cleanup(sd_event_unrefp))) sd_event *event = NULL;
98 int r;
99 \&...
100 r = sd_event_default(&event);
101 if (r < 0) {
102 errno = \-r;
103 fprintf(stderr, "Failed to allocate event loop: %m\en");
104 }
105 \&...
106 }
107 .fi
108 .if n \{\
109 .RE
110 .\}
111 .PP
112 \fBsd_event_ref()\fR,
113 \fBsd_event_unref()\fR
114 and
115 \fBsd_event_unrefp()\fR
116 execute no operation if the passed in event loop object is
117 \fBNULL\fR\&.
118 .PP
119 \fBsd_event_get_tid()\fR
120 retrieves the thread identifier ("TID") of the thread the specified event loop object is associated with\&. This call is only supported for event loops allocated with
121 \fBsd_event_default()\fR, and returns the identifier for the thread the event loop is the default event loop of\&. See
122 \fBgettid\fR(2)
123 for more information on thread identifiers\&.
124 .SH "RETURN VALUE"
125 .PP
126 On success,
127 \fBsd_event_new()\fR,
128 \fBsd_event_default()\fR
129 and
130 \fBsd_event_get_tid()\fR
131 return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
132 \fBsd_event_ref()\fR
133 always returns a pointer to the event loop object passed in\&.
134 \fBsd_event_unref()\fR
135 always returns
136 \fBNULL\fR\&.
137 .SS "Errors"
138 .PP
139 Returned errors may indicate the following problems:
140 .PP
141 \fB\-ENOMEM\fR
142 .RS 4
143 Not enough memory to allocate the object\&.
144 .RE
145 .PP
146 \fB\-EMFILE\fR
147 .RS 4
148 The maximum number of event loops has been allocated\&.
149 .RE
150 .PP
151 \fB\-ENXIO\fR
152 .RS 4
153 \fBsd_event_get_tid()\fR
154 was invoked on an event loop object that was not allocated with
155 \fBsd_event_default()\fR\&.
156 .RE
157 .SH "NOTES"
158 .PP
159 Functions described here are available as a shared library, which can be compiled against and linked to with the
160 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
161 file\&.
162 .PP
163 The code described here uses
164 \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
165 \fBsetenv\fR(3)
166 from a parallel thread\&. It is recommended to only do calls to
167 \fBsetenv()\fR
168 from an early phase of the program when no other threads have been started\&.
169 .SH "HISTORY"
170 .PP
171 \fBsd_event_new()\fR,
172 \fBsd_event_default()\fR,
173 \fBsd_event_ref()\fR, and
174 \fBsd_event_unref()\fR
175 were added in version 213\&.
176 .PP
177 \fBsd_event_unrefp()\fR
178 and
179 \fBsd_event_get_tid()\fR
180 were added in version 229\&.
181 .SH "SEE ALSO"
182 .PP
183 \fBsystemd\fR(1), \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_run\fR(3), \fBgettid\fR(2)
184 .SH "NOTES"
185 .IP " 1." 4
186 Clean-up Variable Attribute
187 .RS 4
188 \%https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
189 .RE