| .\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> |
| .\" |
| .\" SPDX-License-Identifier: LGPL-2.0-or-later |
| .\" |
| .TH io_uring_register_buffers 3 "November 15, 2021" "liburing-2.1" "liburing Manual" |
| .SH NAME |
| io_uring_register_buffers \- register buffers for fixed buffer operations |
| .SH SYNOPSIS |
| .nf |
| .B #include <liburing.h> |
| .PP |
| .BI "int io_uring_register_buffers(struct io_uring *" ring ", |
| .BI " const struct iovec *" iovecs ", |
| .BI " unsigned " nr_iovecs ");" |
| .PP |
| .BI "int io_uring_register_buffers_sparse(struct io_uring *" ring ", |
| .BI " unsigned " nr_iovecs ");" |
| .fi |
| .SH DESCRIPTION |
| .PP |
| The |
| .BR io_uring_register_buffers (3) |
| function registers |
| .I nr_iovecs |
| number of buffers defined by the array |
| .I iovecs |
| belonging to the |
| .IR ring . |
| |
| The |
| .BR io_uring_register_buffers_sparse (3) |
| function registers |
| .I nr_iovecs |
| empty buffers belonging to the |
| .IR ring . |
| These buffers must be updated before use, using eg |
| .BR io_uring_register_buffers_update_tag (3). |
| |
| After the caller has registered the buffers, they can be used with one of the |
| fixed buffers functions. |
| |
| Registered buffers is an optimization that is useful in conjunction with |
| .B O_DIRECT |
| reads and writes, where it maps the specified range into the kernel once when |
| the buffer is registered rather than doing a map and unmap for each IO |
| every time IO is performed to that region. Additionally, it also avoids |
| manipulating the page reference counts for each IO. |
| |
| .SH RETURN VALUE |
| On success |
| .BR io_uring_register_buffers (3) |
| and |
| .BR io_uring_register_buffers_sparse (3) |
| return 0. On failure they return |
| .BR -errno . |
| .SH SEE ALSO |
| .BR io_uring_get_sqe (3), |
| .BR io_uring_unregister_buffers (3), |
| .BR io_uring_register_buf_ring (3), |
| .BR io_uring_prep_read_fixed (3), |
| .BR io_uring_prep_write_fixed (3) |