---
name: "io_uring_setup_buf_ring"
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_setup_buf_ring"
---

# io\_uring\_setup\_buf\_ring(3)

setup and register buffer ring for provided buffers

## NAME

io\_uring\_setup\_buf\_ring - setup and register buffer ring for provided buffers

## SYNOPSIS

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

**struct io\_uring\_buf\_ring \*io\_uring\_setup\_buf\_ring(struct io\_uring \****ring***,**                                                   **unsigned int** *nentries***,**                                                   **int** *bgid***,**                                                   **unsigned int** *flags***,**                                                   **int \****err***);**

## DESCRIPTION

The [**io\_uring\_setup\_buf\_ring**(3)](/io_uring_setup_buf_ring/3.md) function registers a shared buffer ring to be used with provided buffers. For the request types that support it, provided buffers are given to the ring and one is selected by a request if it has **IOSQE\_BUFFER\_SELECT** set in the SQE *flags*, when the request is ready to receive data. This allows both clear ownership of the buffer lifetime, and a way to have more read/receive type of operations in flight than buffers available.

The *ring* argument must be a pointer to the ring for which the provided buffer ring is being registered, *nentries* is the number of entries requested in the buffer ring. This argument must be a power-of 2 in size, and can be up to 32768 in size. *bgid* is the chosen buffer group ID, *flags* are modifier flags for the operation, and *\*err* is a pointer to an integer for the error value if any part of the ring allocation and registration fails.

The *flags* argument can be set to one of the following values:

- **IOU\_PBUF\_RING\_INC**

  The buffers in this ring can be incrementally consumed. With partial consumption, each completion of a given buffer ID will continue where the previous one left off, or from the start if no completions have been seen yet. When more completions should be expected for a given buffer ID, the CQE will have **IORING\_CQE\_F\_BUF\_MORE** set in the *flags* member. Available since 6.12.

Under the covers, this function uses [**io\_uring\_register\_buf\_ring**(3)](/io_uring_register_buf_ring/3.md) to register the ring, and handles the allocation of the ring rather than letting the application open code it.

To unregister and free a buffer group ID setup with this function, the application must call [**io\_uring\_free\_buf\_ring**(3)](/io_uring_free_buf_ring/3.md)**.**

Available since 5.19.

## RETURN VALUE

On success [**io\_uring\_setup\_buf\_ring**(3)](/io_uring_setup_buf_ring/3.md) returns a pointer to the buffer ring. On failure it returns **NULL** and sets *\*err* to -errno.

## NOTES

Note that even if the kernel supports this feature, registering a provided buffer ring may still fail with **-EINVAL** if the host is a 32-bit architecture and the memory being passed in resides in high memory.

## SEE ALSO

[**io\_uring\_register\_buf\_ring**(3)](/io_uring_register_buf_ring/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\_buf\_ring\_advance**(3)](/io_uring_buf_ring_advance/3.md), [**io\_uring\_buf\_ring\_cq\_advance**(3)](/io_uring_buf_ring_cq_advance/3.md)