[systemd-devel] sd_bus_get_timeout returns absolute time despite what's documented

[Lennart Poettering]

On Sa, 07.01.23 10:35, Stanislav Angelovič (stanislav.angelovic at protonmail.com) wrote:

> Hi everyone,
>
> According to sd_bus_get_timeout(3) man page, sd_bus_get_timeout()
> returns "timeout in us to pass to poll()" and it also states that
> "the returned time-value is relative".
>
> However, in reality, this function returns an absolute time point
> (a-ka relative to the monotonic clock epoch). Hence, the returned
> value cannot be simply converted to milliseconds and given to
> poll(). It must first be subtracted from the current monotonic clock
> time.
>
> I followed the documentation and had a bug in my code for some time
> :) Shall the documentation be updated to mention the necessity of
> conversion from absolute to relative? Or does sd_bus_get_timeout()
> have a bug and shall this function do the subtraction for the user
> and return relative time?

Hmm, the man page says this currently:

https://www.freedesktop.org/software/systemd/man/sd_bus_get_fd.html#Description

    Note that the returned time-value is absolute, based of
    CLOCK_MONOTONIC and specified in microseconds. When converting
    this value in order to pass it as third argument to poll() (which
    expects relative milliseconds), care should be taken to convert to
    a relative time and 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
    ppoll(2) instead of plain poll(), which understands timeouts with
    nano-second granularity).

That's pretty explicit already, no?

(I mean, you have half a point, the first sentence of the explanation
might people think this was a relative timeout, but we all read the
full documentation, no, before actually using this API, no? ;-))

Anyway, will prep a fix that rewords the first sentence to make this
clearer right away.

Lennart

--
Lennart Poettering, Berlin