X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_event_add_io.xml;h=3ba7c3bd3e4eff6b3f990001fedfb740708909c5;hb=a5c28308446550e0966825472babdf123fc976ac;hp=5c363f96b33d90276f9bc2e67d6aae574e5cb769;hpb=07045a1a92c839fd2af80bd0c060a595021bc3b3;p=elogind.git
diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml
index 5c363f96b..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: