1io_uring_setup_buf_ring(3)      liburing Manual     io_uring_setup_buf_ring(3)
2
3
4

NAME

6       io_uring_setup_buf_ring  -  setup and register buffer ring for provided
7       buffers
8

SYNOPSIS

10       #include <liburing.h>
11
12       struct io_uring_buf_ring *io_uring_setup_buf_ring(struct io_uring *ring,
13                                   unsigned int nentries,
14                                   int bgid,
15                                   unsigned int flags,
16                                   int *ret);
17
18

DESCRIPTION

20       The io_uring_setup_buf_ring(3) function registers a shared buffer  ring
21       to  be  used  with provided buffers. For the request types that support
22       it, provided buffers are given to the ring and one is selected by a re‐
23       quest  if it has IOSQE_BUFFER_SELECT set in the SQE flags, when the re‐
24       quest is ready to receive data. This allows both clear ownership of the
25       buffer lifetime, and a way to have more read/receive type of operations
26       in flight than buffers available.
27
28       The ring argument must pointer to the ring for which the provided  buf‐
29       fer  ring  is  being  registered, nentries is the number of entries re‐
30       quested in the buffer ring. This argument must be a power-of 2 in size.
31       bgid  is  the  chosen buffer group ID, flags are modifier flags for the
32       operation, and *ret is is a pointer to an integer for the  error  value
33       if any part of the ring allocation and registration fails.
34
35       The flags argument is currently unused and must be set to zero.
36
37       Under  the  covers, this function uses io_uring_register_buf_ring(3) to
38       register the ring, and handles the allocation of the ring  rather  than
39       letting the application open code it.
40
41       To  unregister and free a buffer group ID setup with this function, the
42       application must call io_uring_free_buf_ring(3).
43
44       Available since 5.19.
45
46

RETURN VALUE

48       On success io_uring_setup_buf_ring(3) returns a pointer to  the  buffer
49       ring. On failure it returns NULL and sets *ret to -errno.
50

NOTES

52       Note  that even if the kernel supports this feature, registering a pro‐
53       vided buffer ring may still fail with -EINVAL if the host is  a  32-bit
54       architecture and the memory being passed in resides in high memory.
55

SEE ALSO

57       io_uring_register_buf_ring(3),     io_uring_buf_ring_init(3),    io_ur‐
58       ing_buf_ring_add(3),        io_uring_buf_ring_advance(3),        io_ur‐
59       ing_buf_ring_cq_advance(3)
60
61
62
63liburing-2.4                     Mar 07, 2023       io_uring_setup_buf_ring(3)