X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_event_add_io.xml;h=3ba7c3bd3e4eff6b3f990001fedfb740708909c5;hp=010ecdbaf8f5526e256d7689cd0a5ef4610e47cb;hb=2b18106e03096fec69dbd821a126241981a1febd;hpb=07c9d5f5d8171ac47f22e2cab1c0aef3b81ef404 diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml index 010ecdbaf..3ba7c3bd3 100644 --- a/man/sd_event_add_io.xml +++ b/man/sd_event_add_io.xml @@ -120,36 +120,35 @@ 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 I/O - events to watch the file descriptor for, a combination of the - following event flags: EPOLLIN, - EPOLLOUT, EPOLLRDHUP, - EPOLLPRI and EPOLLET, - see epoll_ctl2 + 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 I/O event source is triggered. The - handler function will be passed the - userdata pointer, which 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 - seen. It's generally a subset of the events watched, however may - additionally have EPOLLERR and - EPOLLHUP set. - - By default, the I/O event source will stay enabled + 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 I/O event source set to SD_EVENT_ON will - fire continuously unless data is read or written to the file - descriptor in order to reset the mask of events seen. + 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 @@ -164,16 +163,17 @@ 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 when there's still a - reference to it kept, consider setting the event source to - SD_EVENT_OFF with - sd_event_source_set_enabled3. + 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 passed as 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. + 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 @@ -181,24 +181,24 @@ 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 - starving of other event sources. See fcntl2 + starvation of other event sources. See + fcntl2 for details on enabling O_NONBLOCK mode. sd_event_source_get_io_events() retrieves - the configured I/O event mask to watch of an I/O event source created + 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 - event mask in. + mask in. - sd_event_source_set_io_events() changes the - configured I/O event mask to watch of an I/O event source created previously - with sd_event_add_io(). It takes the event - source object and the new event mask to set. + 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_events() + sd_event_source_get_io_revents() retrieves the I/O event mask of currently seen but undispatched - events from an I/O event source created previously with + 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 @@ -214,15 +214,15 @@ source types, the latter only to I/O event sources. sd_event_source_get_io_fd() retrieves - the UNIX file descriptor of an I/O event source created previously + the UNIX file descriptor of an event source created previously with sd_event_add_io(). It takes the event - source object and returns the positive file descriptor in the return - value, or a negative error number on error (see below). + 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 to set. + the event source object and the new file descriptor. @@ -230,13 +230,13 @@ On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error - code. + code. Errors - Returned errors may indicate the following problems: + Returned values may indicate the following problems: @@ -279,7 +279,7 @@ See Also - elogind1, + elogind8, sd-event3, sd_event_new3, sd_event_now3,