sd_event_source(3)

1SD_EVENT_ADD_IO(3)              sd_event_add_io             SD_EVENT_ADD_IO(3)
2
3
4

NAME

6       sd_event_add_io, sd_event_source_get_io_events,
7       sd_event_source_set_io_events, sd_event_source_get_io_revents,
8       sd_event_source_get_io_fd, sd_event_source_set_io_fd,
9       sd_event_source_get_io_fd_own, sd_event_source_set_io_fd_own,
10       sd_event_source, sd_event_io_handler_t - Add an I/O event source to an
11       event loop
12

SYNOPSIS

14       #include <systemd/sd-event.h>
15
16       typedef struct sd_event_source sd_event_source;
17
18       typedef int (*sd_event_io_handler_t)(sd_event_source *s, int fd,
19                                            uint32_t revents, void *userdata);
20
21       int sd_event_add_io(sd_event *event, sd_event_source **source, int fd,
22                           uint32_t events, sd_event_io_handler_t handler,
23                           void *userdata);
24
25       int sd_event_source_get_io_events(sd_event_source *source,
26                                         uint32_t *events);
27
28       int sd_event_source_set_io_events(sd_event_source *source,
29                                         uint32_t events);
30
31       int sd_event_source_get_io_revents(sd_event_source *source,
32                                          uint32_t *revents);
33
34       int sd_event_source_get_io_fd(sd_event_source *source);
35
36       int sd_event_source_set_io_fd(sd_event_source *source, int fd);
37
38       int sd_event_source_get_io_fd_own(sd_event_source *source);
39
40       int sd_event_source_set_io_fd_own(sd_event_source *source, int b);
41

DESCRIPTION

43       sd_event_add_io() adds a new I/O event source to an event loop. The
44       event loop object is specified in the event parameter, the event source
45       object is returned in the source parameter. The fd parameter takes the
46       UNIX file descriptor to watch, which may refer to a socket, a FIFO, a
47       message queue, a serial connection, a character device, or any other
48       file descriptor compatible with Linux epoll(7). The events parameter
49       takes a bit mask of events to watch for, a combination of the following
50       event flags: EPOLLIN, EPOLLOUT, EPOLLRDHUP, EPOLLPRI, and EPOLLET, see
51       epoll_ctl(2) for details.
52
53       The handler is a function to call when the event source is triggered or
54       NULL. The userdata pointer will be passed to the handler function, and
55       may be chosen freely by the caller. The handler will also be passed the
56       file descriptor the event was seen on, as well as the actual event
57       flags. It's generally a subset of the events watched, however may
58       additionally include EPOLLERR and EPOLLHUP. The handler may return
59       negative to signal an error (see below), other return values are
60       ignored. If handler is NULL, a default handler that calls
61       sd_event_exit(3) will be used.
62
63       By default, an event source will stay enabled continuously
64       (SD_EVENT_ON), but this may be changed with
65       sd_event_source_set_enabled(3). If the handler function returns a
66       negative error code, it will either be disabled after the invocation,
67       even if the SD_EVENT_ON mode was requested before, or it will cause the
68       loop to terminate, see sd_event_source_set_exit_on_failure(3). Note
69       that an event source set to SD_EVENT_ON will fire continuously unless
70       data is read from or written to the file descriptor to reset the mask
71       of events seen.
72
73       Setting the I/O event mask to watch for to 0 does not mean that the
74       event source won't be triggered anymore, as EPOLLHUP and EPOLLERR may
75       be triggered even with a zero event mask. To temporarily disable an I/O
76       event source use sd_event_source_set_enabled(3) with SD_EVENT_OFF
77       instead.
78
79       To destroy an event source object use sd_event_source_unref(3), but
80       note that the event source is only removed from the event loop when all
81       references to the event source are dropped. To make sure an event
82       source does not fire anymore, even if it is still referenced, disable
83       the event source using sd_event_source_set_enabled(3) with
84       SD_EVENT_OFF.
85
86       If the second parameter of sd_event_add_io() is NULL no reference to
87       the event source object is returned. In this case the event source is
88       considered "floating", and will be destroyed implicitly when the event
89       loop itself is destroyed.
90
91       If the handler to sd_event_add_io() is NULL, and the event source
92       fires, this will be considered a request to exit the event loop. In
93       this case, the userdata parameter, cast to an integer, is passed as the
94       exit code parameter to sd_event_exit(3).
95
96       Note that this call does not take possession of the file descriptor
97       passed in, ownership (and thus the duty to close it when it is no
98       longer needed) remains with the caller. However, with the
99       sd_event_source_set_io_fd_own() call (see below) the event source may
100       optionally take ownership of the file descriptor after the event source
101       has been created. In that case the file descriptor is closed
102       automatically as soon as the event source is released.
103
104       It is recommended to use sd_event_add_io() only in conjunction with
105       file descriptors that have O_NONBLOCK set, to ensure that all I/O
106       operations from invoked handlers are properly asynchronous and
107       non-blocking. Using file descriptors without O_NONBLOCK might result in
108       unexpected starvation of other event sources. See fcntl(2) for details
109       on enabling O_NONBLOCK mode.
110
111       sd_event_source_get_io_events() retrieves the configured mask of
112       watched I/O events of an event source created previously with
113       sd_event_add_io(). It takes the event source object and a pointer to a
114       variable to store the mask in.
115
116       sd_event_source_set_io_events() configures the mask of watched I/O
117       events of an event source created previously with sd_event_add_io(). It
118       takes the event source object and the new event mask.
119
120       sd_event_source_get_io_revents() retrieves the I/O event mask of
121       currently seen but undispatched events from an event source created
122       previously with sd_event_add_io(). It takes the event source object and
123       a pointer to a variable to store the event mask in. When called from a
124       handler function on the handler's event source object this will return
125       the same mask as passed to the handler's revents parameter. This call
126       is primarily useful to check for undispatched events of an event source
127       from the handler of an unrelated (possibly higher priority) event
128       source. Note the relation between sd_event_source_get_pending() and
129       sd_event_source_get_io_revents(): both functions will report non-zero
130       results when there's an event pending for the event source, but the
131       former applies to all event source types, the latter only to I/O event
132       sources.
133
134       sd_event_source_get_io_fd() retrieves the UNIX file descriptor of an
135       event source created previously with sd_event_add_io(). It takes the
136       event source object and returns the non-negative file descriptor or a
137       negative error number on error (see below).
138
139       sd_event_source_set_io_fd() changes the UNIX file descriptor of an I/O
140       event source created previously with sd_event_add_io(). It takes the
141       event source object and the new file descriptor.
142
143       sd_event_source_set_io_fd_own() controls whether the file descriptor of
144       the event source shall be closed automatically when the event source is
145       freed, i.e. whether it shall be considered 'owned' by the event source
146       object. By default it is not closed automatically, and the application
147       has to do this on its own. The b parameter is a boolean parameter: if
148       zero, the file descriptor is not closed automatically when the event
149       source is freed, otherwise it is closed.
150
151       sd_event_source_get_io_fd_own() may be used to query the current
152       setting of the file descriptor ownership boolean flag as set with
153       sd_event_source_set_io_fd_own(). It returns positive if the file
154       descriptor is closed automatically when the event source is destroyed,
155       zero if not, and negative on error.
156

RETURN VALUE

158       On success, these functions return 0 or a positive integer. On failure,
159       they return a negative errno-style error code.
160
161   Errors
162       Returned values may indicate the following problems:
163
164       -ENOMEM
165           Not enough memory to allocate an object.
166
167       -EINVAL
168           An invalid argument has been passed.
169
170       -ESTALE
171           The event loop is already terminated.
172
173       -ECHILD
174           The event loop has been created in a different process, library or
175           module instance.
176
177       -EDOM
178           The passed event source is not an I/O event source.
179

NOTES

181       Functions described here are available as a shared library, which can
182       be compiled against and linked to with the libsystemd pkg-config(1)
183       file.
184
185       The code described here uses getenv(3), which is declared to be not
186       multi-thread-safe. This means that the code calling the functions
187       described here must not call setenv(3) from a parallel thread. It is
188       recommended to only do calls to setenv() from an early phase of the
189       program when no other threads have been started.
190

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO