---
name: "io_uring_prep_timeout"
section: "3"
platform: "linux"
package: "liburing"
version: "2.15-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/io_uring_prep_timeout"
---

# io\_uring\_prep\_timeout(3)

prepare a timeout request

## NAME

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

## SYNOPSIS

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

**void io\_uring\_prep\_timeout(struct io\_uring\_sqe \****sqe***,**                            **const struct \_\_kernel\_timespec \****ts***,**                            **unsigned** *count***,**                            **unsigned** *flags***);**

## DESCRIPTION

The [**io\_uring\_prep\_timeout**(3)](/io_uring_prep_timeout/3.md) 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**

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

- **IORING\_TIMEOUT\_BOOTTIME**

  The boottime clock source should be used.

- **IORING\_TIMEOUT\_REALTIME**

  The realtime clock source should be used.

- **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**

  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**

  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)](/io_uring_prep_timeout/3.md) 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

None

## ERRORS

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

- **-ETIME**

  The specified timeout occurred and triggered the completion event.

- **-EINVAL**

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

- **-EFAULT**

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

- **-ECANCELED**

  The timeout was canceled by a removal request.

## 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)](/io_uring_queue_init_params/3.md).

## SEE ALSO

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