X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fsd_bus_get_fd.xml;h=6a022b1a19053f91239b21418b6f9854a63ec869;hb=5057d73ba1bb016c9325d0a7fdb84519d3443622;hp=2e867b0bf7f80af3d5248c87d5bd3d2fd09c534d;hpb=0e74bad141d035b7d45f5e46ea4f33217db3c9e8;p=thirdparty%2Fsystemd.git diff --git a/man/sd_bus_get_fd.xml b/man/sd_bus_get_fd.xml index 2e867b0bf7f..6a022b1a190 100644 --- a/man/sd_bus_get_fd.xml +++ b/man/sd_bus_get_fd.xml @@ -1,41 +1,18 @@ - - + + - + sd_bus_get_fd systemd - - - - Julian - Orth - ju.orth@gmail.com - - @@ -45,8 +22,10 @@ sd_bus_get_fd + sd_bus_get_events + sd_bus_get_timeout - Get the file descriptor connected to the message bus + Get the file descriptor, I/O events and time-out to wait for from a message bus object @@ -57,39 +36,113 @@ int sd_bus_get_fd sd_bus *bus + + + int sd_bus_get_events + sd_bus *bus + + + + int sd_bus_get_timeout + sd_bus *bus + uint64_t *timeout_usec + Description - - sd_bus_get_fd() returns the file descriptor used to - communicate with the message bus. This descriptor can be used with - select3, - poll3, - or similar functions to wait for incoming messages. - - - - If the bus was created with the - sd_bus_set_fd3 - function, then the input_fd used in that call is - returned. - + sd_bus_get_fd() returns the file descriptor used to communicate from a message bus + object. This descriptor can be used with poll3 or a similar + function to wait for I/O events on the specified bus connection object. If the bus object was configured with the + sd_bus_set_fd3 function, then + the input_fd file descriptor used in that call is returned. + + sd_bus_get_events() returns the I/O events to wait for, suitable for passing to + poll() or a similar call. Returns a combination of POLLIN, + POLLOUT, … events, or negative on error. + + sd_bus_get_timeout() returns the time-out in µs to pass to to + poll() or a similar call when waiting for events on the specified bus connection. The returned + time-out may be zero, in which case a subsequent I/O polling call should be invoked in non-blocking mode. The + returned timeout may be UINT64_MAX in which case the I/O polling call may block indefinitely, + without any applied time-out. Note that the returned time-out should be considered only a maximum sleeping time. It + is permissible (and even expected) that shorter time-outs are used by the calling program, in case other event + sources are polled in the same event loop. Note that the returned time-value is relative and specified in + microseconds. When converting this value in order to pass it as third argument to poll() + (which expects milliseconds), care should be taken to use a division that rounds up to ensure the I/O polling + operation doesn't sleep for shorter than necessary, which might result in unintended busy looping (alternatively, + use ppoll3 + instead of plain poll(), which understands time-outs with nano-second granularity). + + These three functions are useful to hook up a bus connection object with an external or manual event loop + involving poll() or a similar I/O polling call. Before each invocation of the I/O polling + call, all three functions should be invoked: the file descriptor returned by sd_bus_get_fd() + should be polled for the events indicated by sd_bus_get_events(), and the I/O call should + block for that up to the time-out returned by sd_bus_get_timeout(). After each I/O polling + call the bus connection needs to process incoming or outgoing data, by invoking + sd_bus_process3. + + Note that these function are only one of three supported ways to implement I/O event handling for bus + connections. Alternatively use + sd_bus_attach_event3 to attach a + bus connection to an sd-event3 + event loop. Or use sd_bus_wait3 + as a simple synchronous, blocking I/O waiting call. Return Value - - Returns the file descriptor used for incoming messages from the message - bus. - + sd_bus_get_fd() returns the file descriptor used for communication, or a negative + errno-style error code on error. + + sd_bus_get_events() returns the I/O event mask to use for I/O event watching, or a + negative errno-style error code on error. + + sd_bus_get_timeout() returns zero or positive on success, or a negative + errno-style error code on error. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + An invalid bus object was passed. + + + + -ECHILD + + The bus connection was allocated in a parent process and is being reused in a child + process after fork(). + + + + -ENOTCONN + + The bus connection has been terminated. + + + + -EPERM + + Two distinct file descriptors were passed for input and output using + sd_bus_set_fd(), which sd_bus_get_fd() cannot + return. + + + + + See Also @@ -97,6 +150,10 @@ systemd1, sd-bus3, sd_bus_set_fd3, + sd_bus_process3, + sd_bus_attach_event3, + sd_bus_wait3, + poll3