Debian Codegraph @

upstream/debian-unstable/man3/sd_event_get_fd.3

raw
1 '\" t
2 .TH "SD_EVENT_GET_FD" "3" "" "systemd 261~rc3" "sd_event_get_fd"
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_get_fd \- Obtain a file descriptor to poll for event loop events
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-event\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_event_get_fd('u
32 .BI "int sd_event_get_fd(sd_event\ *" "event" ");"
33 .SH "DESCRIPTION"
34 .PP
35 \fBsd_event_get_fd()\fR
36 returns the file descriptor that an event loop object returned by the
37 \fBsd_event_new\fR(3)
38 function uses to wait for events\&. This file descriptor may itself be polled for
39 \fBPOLLIN\fR/\fBEPOLLIN\fR
40 events\&. This makes it possible to embed an
41 \fBsd-event\fR(3)
42 event loop into another, possibly foreign, event loop\&.
43 .PP
44 The returned file descriptor refers to an
45 \fBepoll\fR(7)
46 object\&. It is recommended not to alter it by invoking
47 \fBepoll_ctl\fR(2)
48 on it, in order to avoid interference with the event loop\*(Aqs inner logic and assumptions\&.
49 .SH "RETURN VALUE"
50 .PP
51 On success,
52 \fBsd_event_get_fd()\fR
53 returns a non\-negative file descriptor\&. On failure, it returns a negative errno\-style error code\&.
54 .SS "Errors"
55 .PP
56 Returned errors may indicate the following problems:
57 .PP
58 \fB\-EINVAL\fR
59 .RS 4
60 \fIevent\fR
61 is not a valid pointer to an
62 sd_event
63 structure\&.
64 .RE
65 .PP
66 \fB\-ECHILD\fR
67 .RS 4
68 The event loop has been created in a different process, library or module instance\&.
69 .RE
70 .SH "EXAMPLES"
71 .PP
72 \fBExample\ \&1.\ \&Integration in the GLib event loop\fR
73 .sp
74 .if n \{\
75 .RS 4
76 .\}
77 .nf
78 /* SPDX\-License\-Identifier: MIT\-0 */
79
80 #include <stdlib\&.h>
81 #include <glib\&.h>
82 #include <systemd/sd\-event\&.h>
83
84 typedef struct SDEventSource {
85 GSource source;
86 GPollFD pollfd;
87 sd_event *event;
88 } SDEventSource;
89
90 static gboolean event_prepare(GSource *source, gint *timeout_) {
91 return sd_event_prepare(((SDEventSource *)source)\->event) > 0;
92 }
93
94 static gboolean event_check(GSource *source) {
95 return sd_event_wait(((SDEventSource *)source)\->event, 0) > 0;
96 }
97
98 static gboolean event_dispatch(GSource *source, GSourceFunc callback, gpointer user_data) {
99 return sd_event_dispatch(((SDEventSource *)source)\->event) > 0;
100 }
101
102 static void event_finalize(GSource *source) {
103 sd_event_unref(((SDEventSource *)source)\->event);
104 }
105
106 static GSourceFuncs event_funcs = {
107 \&.prepare = event_prepare,
108 \&.check = event_check,
109 \&.dispatch = event_dispatch,
110 \&.finalize = event_finalize,
111 };
112
113 GSource *g_sd_event_create_source(sd_event *event) {
114 SDEventSource *source;
115
116 source = (SDEventSource *)g_source_new(&event_funcs, sizeof(SDEventSource));
117
118 source\->event = sd_event_ref(event);
119 source\->pollfd\&.fd = sd_event_get_fd(event);
120 source\->pollfd\&.events = G_IO_IN | G_IO_HUP | G_IO_ERR;
121
122 g_source_add_poll((GSource *)source, &source\->pollfd);
123
124 return (GSource *)source;
125 }
126 .fi
127 .if n \{\
128 .RE
129 .\}
130 .SH "NOTES"
131 .PP
132 Functions described here are available as a shared library, which can be compiled against and linked to with the
133 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
134 file\&.
135 .PP
136 The code described here uses
137 \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
138 \fBsetenv\fR(3)
139 from a parallel thread\&. It is recommended to only do calls to
140 \fBsetenv()\fR
141 from an early phase of the program when no other threads have been started\&.
142 .SH "HISTORY"
143 .PP
144 \fBsd_event_get_fd()\fR
145 was added in version 217\&.
146 .SH "SEE ALSO"
147 .PP
148 \fBsd-event\fR(3), \fBsd_event_new\fR(3), \fBsd_event_wait\fR(3), \fBepoll_ctl\fR(2), \fBepoll\fR(7)