io\_uring\_prep\_timeout(3) liburing Manual io\_uring\_prep\_timeout(3)

# [NAME](#NAME)

io\_uring\_prep\_timeout - prepare a timeout request

# [SYNOPSIS](#SYNOPSIS)

```
#include <liburing.h>
```

```
void io_uring_prep_timeout(struct io_uring_sqe *sqe,
                           const struct __kernel_timespec *ts,
                           unsigned count,
                           unsigned flags);
```

# [DESCRIPTION](#DESCRIPTION)

The [**io\_uring\_prep\_timeout**(3)](/man/os/liburing/io_uring_prep_timeout.3) function prepares a timeout request. The submission queue entry *sqe* is setup to arm a timeout specified by *ts* and with a timeout count of *count* completion entries. The *flags* argument holds modifier flags for the request.

This request type can be used as a timeout waking anyone sleeping for events on the CQ ring. The *flags* argument may contain:

[**IORING\_TIMEOUT\_ABS**](#IORING_TIMEOUT_ABS)

The value specified in *ts* is an absolute value rather than a relative one.

[**IORING\_TIMEOUT\_BOOTTIME**](#IORING_TIMEOUT_BOOTTIME)

The boottime clock source should be used.

[**IORING\_TIMEOUT\_REALTIME**](#IORING_TIMEOUT_REALTIME)

The realtime clock source should be used.

[**IORING\_TIMEOUT\_ETIME\_SUCCESS**](#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.

[**IORING\_TIMEOUT\_MULTISHOT**](#IORING_TIMEOUT_MULTISHOT)

The request will return multiple timeout completions. The completion flag IORING\_CQE\_F\_MORE is set if more timeouts are expected. The value specified in *count* is the number of repeats. A value of 0 means the timeout is indefinite and can only be stopped by a removal request. Available since the 6.4 kernel.

[**IORING\_TIMEOUT\_IMMEDIATE\_ARG**](#IORING_TIMEOUT_IMMEDIATE_ARG)

The timeout value is stored directly in the SQE as a nanosecond value rather than as a pointer to a **struct \_\_kernel\_timespec.** When this flag is set, the *ts* argument to [**io\_uring\_prep\_timeout**(3)](/man/os/liburing/io_uring_prep_timeout.3) is reinterpreted as a nanosecond value (cast to a **\_\_u64**) rather than a pointer. This avoids the need to keep a timespec structure valid in user memory until the request is submitted. Available since the 7.1 kernel.

If no alternate clock source is given in the above flags, then **CLOCK\_MONOTONIC** is used.

The timeout completion event will trigger if either the specified timeout has occurred, or the specified number of events to wait for have been posted to the CQ ring.

# [RETURN VALUE](#RETURN_VALUE)

None

# [ERRORS](#ERRORS)

These are the errors that are reported in the CQE *res* field. On success, **0** is returned.

[**-ETIME**](#ETIME)

The specified timeout occurred and triggered the completion event.

[**-EINVAL**](#EINVAL)

One of the fields set in the SQE was invalid. For example, two clocksources were given, the specified timeout seconds or nanoseconds were &lt; 0.

[**-EFAULT**](#EFAULT)

io\_uring was unable to access the data specified by *ts*.

[**-ECANCELED**](#ECANCELED)

The timeout was canceled by a removal request.

# [NOTES](#NOTES)

As with any request that passes in data in a struct, that data must remain valid until the request has been successfully submitted. It need not remain valid until completion. Once a request has been submitted, the in-kernel state is stable. Very early kernels (5.4 and earlier) required state to be stable until the completion occurred. Applications can test for this behavior by inspecting the **IORING\_FEAT\_SUBMIT\_STABLE** flag passed back from [**io\_uring\_queue\_init\_params**(3)](/man/os/liburing/io_uring_queue_init_params.3).

# [SEE ALSO](#SEE_ALSO)

[**io\_uring\_get\_sqe**(3)](/man/os/liburing/io_uring_get_sqe.3), [**io\_uring\_submit**(3)](/man/os/liburing/io_uring_submit.3), [**io\_uring\_prep\_timeout\_remove**(3)](/man/os/liburing/io_uring_prep_timeout_remove.3), [**io\_uring\_prep\_timeout\_update**(3)](/man/os/liburing/io_uring_prep_timeout_update.3)

March 12, 2022 liburing-2.2

---

Document: io_uring_prep_timeout(3) from liburing 2.15-r4 (Chainguard OS)
Source: https://github.com/axboe/liburing.git