diff options
Diffstat (limited to 'man/io_uring_register_buffers.3')
-rw-r--r-- | man/io_uring_register_buffers.3 | 61 |
1 files changed, 61 insertions, 0 deletions
diff --git a/man/io_uring_register_buffers.3 b/man/io_uring_register_buffers.3 new file mode 100644 index 0000000..656ac42 --- /dev/null +++ b/man/io_uring_register_buffers.3 @@ -0,0 +1,61 @@ +.\" 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) |