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) 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 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. bgid is the chosen buffer group ID, flags are modifier flags for the operation, and *err is 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:

IORING_REGISTER_PBUF_RING

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.

Under the covers, this function uses 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).

Available since 5.19.

RETURN VALUE¶

On success io_uring_setup_buf_ring(3) 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_buf_ring_init(3), io_uring_buf_ring_add(3), io_uring_buf_ring_advance(3), io_uring_buf_ring_cq_advance(3)