---
name: "io_uring_prep_read_multishot"
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_read_multishot"
---

# io\_uring\_prep\_read\_multishot(3)

prepare I/O read multishot request

## NAME

io\_uring\_prep\_read\_multishot - prepare I/O read multishot request

## SYNOPSIS

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

**void io\_uring\_prep\_read\_multishot(struct io\_uring\_sqe \****sqe***,**                                   **int** *fd***,**                                   **unsigned** *nbytes***,**                                   **\_\_u64** *offset***,**                                   **int** *buf\_group***);**

## DESCRIPTION

The [**io\_uring\_prep\_read\_multishot**(3)](/io_uring_prep_read_multishot/3.md) helper prepares an IO read multishot request. The submission queue entry *sqe* is setup to use the file descriptor *fd* to start reading into a buffer from the provided buffer group with ID *buf\_group* at the specified *offset*.

*nbytes* must be set to zero, as the size read will be given by the size of the buffers in the indicated buffer group IO.

On files that are not capable of seeking, the offset must be 0 or -1.

If *nbytes* exceeds the size of the buffers in the specified buffer group, or if *nbytes* is **0 ,** then the size of the buffer in that group will be used for the transfer.

A multishot read request will repeatedly trigger a completion event whenever data is available to read from the file. Because of that, this type of request can only be used with a file type that is pollable. Examples of that include pipes, tun devices, etc. If used with a regular file, or a wrong file type in general, the request will fail with **-EBADFD** in the CQE *res* field.

Since multishot requests repeatedly trigger completion events as data arrives, it must be used with provided buffers. With provided buffers, the application provides buffers to io\_uring upfront, and then the kernel picks a buffer from the specified group in *buf\_group* when the request is ready to transfer data.

A multishot request will persist as long as no errors are encountered doing handling of the request. For each CQE posted on behalf of this request, the CQE *flags* will have **IORING\_CQE\_F\_MORE** set if the application should expect more completions from this request. If this flag isn't set, then that signifies termination of the multishot read request.

After the read has been prepared it can be submitted with one of the submit functions.

Available since 6.7.

## RETURN VALUE

None

## ERRORS

The CQE *res* field will contain the result of the operation. See the related man page for details on possible values. Note that where synchronous system calls will return **-1** on failure and set *errno* to the actual error value, io\_uring never uses *errno*. Instead it returns the negated *errno* directly in the CQE *res* field.

This function accepts an unsigned number of bytes, but io\_uring\_cqe's result code is an \_\_s32 value, so in theory a short read with a large enough nbytes value could generate an ambiguous return.  But the number of bytes actually transferred has the same limit as [**read**(2)](/read/2.md) so this cannot happen in practice.

## SEE ALSO

[**io\_uring\_get\_sqe**(3)](/io_uring_get_sqe/3.md), [**io\_uring\_prep\_read**(3)](/io_uring_prep_read/3.md), [**io\_uring\_buf\_ring\_init**(3)](/io_uring_buf_ring_init/3.md) [**io\_uring\_buf\_ring\_add**(3)](/io_uring_buf_ring_add/3.md), [**io\_uring\_submit**(3)](/io_uring_submit/3.md)