# io_uring_setup_buf_ring

## 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 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)
           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.
    


* * *