Possible documentation inaccuracy for `TimeoutFlags::ETIME_SUCCESS`

[pacak]

Documentation for TimeoutFlags describes behavior for ETIME_SUCCESS as

The default behavior when the timeout expires is to return a CQE with -libc::ETIME in the res field. To change this behavior to have zero returned, include types::TimeoutFlags::ETIME_SUCCESS.

The actual behavior, as far as I can replicate with this example is that it does not affect the value in the res field of CQE:

fn main() {
    use io_uring::types::{TimeoutFlags, Timespec};
    let mut ring = IoUring::new(256).unwrap();

    const TS: Timespec = Timespec::new().sec(1).nsec(0);
    let entry = opcode::Timeout::new(&TS)
        .count(0)
        .flags(TimeoutFlags::ETIME_SUCCESS)
        .build()
        .user_data(42);
    let (submitter, mut sq, mut cq) = ring.split();

    unsafe { sq.push(&entry).unwrap() }
    sq.sync();

    let r = submitter.submit_and_wait(1);
    println!("Wait complete, {r:?}");
    cq.sync();

    for cqe in &mut cq {
        let ret = cqe.result();
        let data = cqe.user_data();
        println!("{ret} {data}");
    }
}

Wait complete, Ok(1)
-62 42

Documentation for what is I'm assuming to be the underlying function io_uring_prep_timeoute describes the behavior differently: result code still contains -ETIME, but behavior changes with respect to dependent links.

   IORING_TIMEOUT_ETIME_SUCCESS
          Consider an expired timeout a success in terms of the
          posted completion. This means it will not sever dependent
          links, as a failed request normally would. The posted CQE
          result code will still contain -ETIME in the res value.

FWIW this description was added here: #223 so I don't think io-uring does anything to change the behavior.

[quininer]

Good catch, we're missing a test for it. Would you open a PR to improve the docs?

[pacak]

Yeah, probably in a day or two. We'll see what other issues I can find :)