io\_uring\_setup\_buf\_ring(3) liburing Manual io\_uring\_setup\_buf\_ring(3)

# [NAME](#NAME)

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

# [SYNOPSIS](#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](#DESCRIPTION)

The [**io\_uring\_setup\_buf\_ring**(3)](/man/os/liburing/io_uring_setup_buf_ring.3) 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**](#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)](/man/os/liburing/io_uring_register_buf_ring.3) 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)](/man/os/liburing/io_uring_free_buf_ring.3)**.**

Available since 5.19.

# [RETURN VALUE](#RETURN_VALUE)

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

# [NOTES](#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](#SEE_ALSO)

[**io\_uring\_register\_buf\_ring**(3)](/man/os/liburing/io_uring_register_buf_ring.3), [**io\_uring\_buf\_ring\_init**(3)](/man/os/liburing/io_uring_buf_ring_init.3), [**io\_uring\_buf\_ring\_add**(3)](/man/os/liburing/io_uring_buf_ring_add.3), [**io\_uring\_buf\_ring\_advance**(3)](/man/os/liburing/io_uring_buf_ring_advance.3), [**io\_uring\_buf\_ring\_cq\_advance**(3)](/man/os/liburing/io_uring_buf_ring_cq_advance.3)

March 7, 2023 liburing-2.4

---

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