From 7ad5d6bf5d7fcc61eace7e933b305f69d439fcc9 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Wed, 10 May 2017 15:51:29 -0400 Subject: ./tools/notsd-move --- src/libsystemd/sd_event_add_io.xml | 300 +++++++++++++++++++++++++++++++++++++ 1 file changed, 300 insertions(+) create mode 100644 src/libsystemd/sd_event_add_io.xml (limited to 'src/libsystemd/sd_event_add_io.xml') diff --git a/src/libsystemd/sd_event_add_io.xml b/src/libsystemd/sd_event_add_io.xml new file mode 100644 index 0000000000..c3749164cd --- /dev/null +++ b/src/libsystemd/sd_event_add_io.xml @@ -0,0 +1,300 @@ + + + + + + + + + sd_event_add_io + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_add_io + 3 + + + + sd_event_add_io + sd_event_source_get_io_events + sd_event_source_set_io_events + sd_event_source_get_io_revents + sd_event_source_get_io_fd + sd_event_source_set_io_fd + sd_event_source + sd_event_io_handler_t + + Add an I/O event source to an event loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_io_handler_t) + sd_event_source *s + int fd + uint32_t revents + void *userdata + + + + int sd_event_add_io + sd_event *event + sd_event_source **source + int fd + uint32_t events + sd_event_io_handler_t handler + void *userdata + + + + int sd_event_source_get_io_events + sd_event_source *source + uint32_t *events + + + + int sd_event_source_set_io_events + sd_event_source *source + uint32_t events + + + + int sd_event_source_get_io_revents + sd_event_source *source + uint32_t *revents + + + + int sd_event_source_get_io_fd + sd_event_source *source + + + + int sd_event_source_set_io_fd + sd_event_source *source + int fd + + + + + + + Description + + sd_event_add_io() adds a new I/O event + source to an event loop. The event loop object is specified in the + event parameter, the event source object is + returned in the source parameter. The + fd parameter takes the UNIX file descriptor + to watch, which may refer to a socket, a FIFO, a message queue, a + serial connection, a character device, or any other file descriptor + compatible with Linux + epoll7. The + events parameter takes a bit mask of events + to watch for, a combination of the following event flags: + EPOLLIN, EPOLLOUT, + EPOLLRDHUP, EPOLLPRI, + and EPOLLET, see + epoll_ctl2 + for details. The handler shall reference a + function to call when the event source is triggered. The + userdata pointer will be passed to the + handler function, and may be chosen freely by the caller. The + handler will also be passed the file descriptor the event was seen + on, as well as the actual event flags. It's generally a subset of + the events watched, however may additionally include + EPOLLERR and EPOLLHUP. + + + By default, an event source will stay enabled + continuously (SD_EVENT_ON), but this may be + changed with + sd_event_source_set_enabled3. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. Note + that an event source set to SD_EVENT_ON will + fire continuously unless data is read from or written to the file + descriptor to reset the mask of events seen. + + + Setting the I/O event mask to watch for to 0 does not mean + that the event source won't be triggered anymore, as + EPOLLHUP and EPOLLERR + may be triggered even with a zero event mask. To temporarily + disable an I/O event source use + sd_event_source_set_enabled3 + with SD_EVENT_OFF instead. + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even if it is still referenced, + disable the event source using + sd_event_source_set_enabled3 + with SD_EVENT_OFF. + + If the second parameter of + sd_event_add_io() is + NULL no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed. + + It is recommended to use + sd_event_add_io() only in conjunction with + file descriptors that have O_NONBLOCK set, to + ensure that all I/O operations from invoked handlers are properly + asynchronous and non-blocking. Using file descriptors without + O_NONBLOCK might result in unexpected + starvation of other event sources. See + fcntl2 + for details on enabling O_NONBLOCK mode. + + sd_event_source_get_io_events() retrieves + the configured mask of watched I/O events of an event source created + previously with sd_event_add_io(). It takes + the event source object and a pointer to a variable to store the + mask in. + + sd_event_source_set_io_events() + configures the mask of watched I/O events of an event source created + previously with sd_event_add_io(). It takes the + event source object and the new event mask. + + sd_event_source_get_io_revents() + retrieves the I/O event mask of currently seen but undispatched + events from an event source created previously with + sd_event_add_io(). It takes the event source + object and a pointer to a variable to store the event mask + in. When called from a handler function on the handler's event + source object this will return the same mask as passed to the + handler's revents parameter. This call is + primarily useful to check for undispatched events of an event + source from the handler of an unrelated (possibly higher priority) + event source. Note the relation between + sd_event_source_get_pending() and + sd_event_source_get_io_revents(): both + functions will report non-zero results when there's an event + pending for the event source, but the former applies to all event + source types, the latter only to I/O event sources. + + sd_event_source_get_io_fd() retrieves + the UNIX file descriptor of an event source created previously + with sd_event_add_io(). It takes the event + source object and returns the non-negative file descriptor + or a negative error number on error (see below). + + sd_event_source_set_io_fd() + changes the UNIX file descriptor of an I/O event source created + previously with sd_event_add_io(). It takes + the event source object and the new file descriptor. + + + + Return Value + + On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned values may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. + + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + -EDOM + + The passed event source is not an I/O event source. + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + sd_event_source_get_pending3, + epoll_ctl3, + epoll7 + + + + -- cgit v1.2.3-54-g00ecf