diff options
Diffstat (limited to 'man')
106 files changed, 6061 insertions, 111 deletions
diff --git a/man/io_uring.7 b/man/io_uring.7 index a63b3e9..8c71d93 100644 --- a/man/io_uring.7 +++ b/man/io_uring.7 @@ -84,17 +84,35 @@ a read operation under .BR io_uring , started with the .BR IORING_OP_READ -operation, -which issues the equivalent of the +operation, issues the equivalent of the .BR read (2) -system call, -would return as part of +system call. In practice, it mixes the semantics of +.BR pread (2) +and +.BR preadv2 (2) +in that it takes an explicit offset, and supports using -1 for the offset to +indicate that the current file position should be used instead of passing in +an explicit offset. See the opcode documentation for more details. Given that +io_uring is an async interface, +.I errno +is never used for passing back error information. Instead, .I res -what -.BR read (2) -would have returned if called directly, -without using -.BR io_uring . +will contain what the equivalent system call would have returned in case +of success, and in case of error +.I res +will contain +.I -errno . +For example, if the normal read system call would have returned -1 and set +.I errno +to +.B EINVAL , +then +.I res +would contain +.B -EINVAL . +If the normal system call would have returned a read size of 1024, then +.I res +would contain 1024. .IP \(bu Optionally, .BR io_uring_enter (2) @@ -259,7 +277,8 @@ you need to acquire a submission queue entry (SQE) from the submission queue (SQ), fill it up with details of the operation you want to submit and call .BR io_uring_enter (2). -If you want to avoid calling +There are helper functions of the form io_uring_prep_X to enable proper +setup of the SQE. If you want to avoid calling .BR io_uring_enter (2), you have the option of setting up Submission Queue Polling. .PP @@ -425,7 +444,7 @@ successful read and update of the head. Because of the shared ring buffers between kernel and user space, .B io_uring can be a zero-copy system. -Copying buffers to and fro becomes necessary when system calls that +Copying buffers to and from becomes necessary when system calls that transfer data between kernel and user space are involved. But since the bulk of the communication in .B io_uring @@ -435,7 +454,7 @@ this huge performance overhead is completely avoided. While system calls may not seem like a significant overhead, in high performance applications, making a lot of them will begin to matter. -While workarounds the operating system has in place to deal with Specter +While workarounds the operating system has in place to deal with Spectre and Meltdown are ideally best done away with, unfortunately, some of these workarounds are around the system call interface, @@ -466,7 +485,7 @@ them to the submission queue. This avoids the .BR io_uring_enter (2) call you need to make to tell the kernel to pick SQEs up. For high-performance applications, -this means even lesser system call overheads. +this means even fewer system call overheads. .SH CONFORMING TO .B io_uring is Linux-specific. @@ -533,8 +552,8 @@ int io_uring_setup(unsigned entries, struct io_uring_params *p) int io_uring_enter(int ring_fd, unsigned int to_submit, unsigned int min_complete, unsigned int flags) { - return (int) syscall(__NR_io_uring_enter, ring_fd, to_submit, min_complete, - flags, NULL, 0); + return (int) syscall(__NR_io_uring_enter, ring_fd, to_submit, + min_complete, flags, NULL, 0); } int app_setup_uring(void) { @@ -623,7 +642,7 @@ int app_setup_uring(void) { int read_from_cq() { struct io_uring_cqe *cqe; - unsigned head, reaped = 0; + unsigned head; /* Read barrier */ head = io_uring_smp_load_acquire(cring_head); @@ -678,10 +697,10 @@ int submit_to_sq(int fd, int op) { io_uring_smp_store_release(sring_tail, tail); /* - * Tell the kernel we have submitted events with the io_uring_enter() system - * call. We also pass in the IOURING_ENTER_GETEVENTS flag which causes the - * io_uring_enter() call to wait until min_complete (the 3rd param) events - * complete. + * Tell the kernel we have submitted events with the io_uring_enter() + * system call. We also pass in the IOURING_ENTER_GETEVENTS flag which + * causes the io_uring_enter() call to wait until min_complete + * (the 3rd param) events complete. * */ int ret = io_uring_enter(ring_fd, 1,1, IORING_ENTER_GETEVENTS); diff --git a/man/io_uring_buf_ring_add.3 b/man/io_uring_buf_ring_add.3 new file mode 100644 index 0000000..9d8283b --- /dev/null +++ b/man/io_uring_buf_ring_add.3 @@ -0,0 +1,53 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_buf_ring_add 3 "May 18, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_buf_ring_add \- add buffers to a shared buffer ring +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_buf_ring_add(struct io_uring_buf_ring *" br ", +.BI " void *" addr ", +.BI " unsigned int " len ", +.BI " unsigned short " bid ", +.BI " int " mask ", +.BI " int " buf_offset ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_buf_ring_add (3) +adds a new buffer to the shared buffer ring +.IR br . +The buffer address is indicated by +.I addr +and is of +.I len +bytes of length. +.I bid +is the buffer ID, which will be returned in the CQE. +.I mask +is the size mask of the ring, available from +.BR io_uring_buf_ring_mask (3) . +.I buf_offset +is the offset to insert at from the current tail. If just one buffer is provided +before the ring tail is committed with +.BR io_uring_buf_ring_advance (3) +or +.BR io_uring_buf_ring_cq_advance (3), +then +.I buf_offset +should be 0. If buffers are provided in a loop before being committed, the +.I buf_offset +must be incremented by one for each buffer added. + +.SH RETURN VALUE +None +.SH SEE ALSO +.BR io_uring_register_buf_ring (3), +.BR io_uring_buf_ring_mask (3), +.BR io_uring_buf_ring_advance (3), +.BR io_uring_buf_ring_cq_advance (3) diff --git a/man/io_uring_buf_ring_advance.3 b/man/io_uring_buf_ring_advance.3 new file mode 100644 index 0000000..29a3578 --- /dev/null +++ b/man/io_uring_buf_ring_advance.3 @@ -0,0 +1,31 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_buf_ring_advance 3 "May 18, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_buf_ring_advance \- advance index of provided buffer in buffer ring +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_buf_ring_advance(struct io_uring_buf_ring *" br ", +.BI " int " count ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_buf_ring_advance (3) +commits +.I count +previously added buffers to the shared buffer ring +.IR br , +making them visible to the kernel and hence consumable. This passes ownership +of the buffer to the ring. + +.SH RETURN VALUE +None +.SH SEE ALSO +.BR io_uring_register_buf_ring (3), +.BR io_uring_buf_ring_add (3), +.BR io_uring_buf_ring_cq_advance (3) diff --git a/man/io_uring_buf_ring_cq_advance.3 b/man/io_uring_buf_ring_cq_advance.3 new file mode 100644 index 0000000..caf882f --- /dev/null +++ b/man/io_uring_buf_ring_cq_advance.3 @@ -0,0 +1,41 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_buf_ring_cq_advance 3 "May 18, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_buf_ring_cq_advance \- advance index of provided buffer and CQ ring +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_buf_ring_cq_advance(struct io_uring *" ring ", +.BI " struct io_uring_buf_ring *" br ", +.BI " int " count ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_buf_ring_cq_advance (3) +commits +.I count +previously added buffers to the shared buffer ring +.IR br , +making them visible to the kernel and hence consumable. This passes ownership +of the buffer to the ring. At the same time, it advances the CQ ring of +.I ring +by +.I count +amount. This effectively bundles both a +.BR io_uring_buf_ring_advance (3) +call and a +.BR io_uring_cq_avance (3) +into one operation. Since updating either ring index entails a store memory +barrier, doing both at once is more efficient. + +.SH RETURN VALUE +None +.SH SEE ALSO +.BR io_uring_register_buf_ring (3), +.BR io_uring_buf_ring_add (3), +.BR io_uring_buf_ring_advance (3) diff --git a/man/io_uring_buf_ring_init.3 b/man/io_uring_buf_ring_init.3 new file mode 100644 index 0000000..50cf69a --- /dev/null +++ b/man/io_uring_buf_ring_init.3 @@ -0,0 +1,30 @@ +.\" Copyright (C) 2022 Dylan Yudaken <dylany@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_buf_ring_init 3 "June 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_buf_ring_init \- Initialise a buffer ring +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_buf_ring_init(struct io_uring_buf_ring *" br ");" +.fi +.SH DESCRIPTION +.PP +.BR io_uring_buf_ring_init (3) +initialises +.IR br +so that it is ready to be used. It may be called after +.BR io_uring_register_buf_ring (3) +but must be called before the buffer ring is used in any other way. + +.SH RETURN VALUE +None + +.SH SEE ALSO +.BR io_uring_register_buf_ring (3), +.BR io_uring_buf_ring_add (3) +.BR io_uring_buf_ring_advance (3), +.BR io_uring_buf_ring_cq_advance (3) diff --git a/man/io_uring_buf_ring_mask.3 b/man/io_uring_buf_ring_mask.3 new file mode 100644 index 0000000..9160663 --- /dev/null +++ b/man/io_uring_buf_ring_mask.3 @@ -0,0 +1,27 @@ +.\" Copyright (C) 2022 Dylan Yudaken <dylany@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_buf_ring_mask 3 "June 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_buf_ring_mask \- Calculate buffer ring mask size +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_buf_ring_mask(__u32 " ring_entries ");" +.fi +.SH DESCRIPTION +.PP +.BR io_uring_buf_ring_mask (3) +calculates the appropriate size mask for a buffer ring. +.IR ring_entries +is the ring entries as specified in +.BR io_uring_register_buf_ring (3) . + +.SH RETURN VALUE +Size mask for the buffer ring. + +.SH SEE ALSO +.BR io_uring_register_buf_ring (3), +.BR io_uring_buf_ring_add (3) diff --git a/man/io_uring_cq_advance.3 b/man/io_uring_cq_advance.3 new file mode 100644 index 0000000..fae2572 --- /dev/null +++ b/man/io_uring_cq_advance.3 @@ -0,0 +1,49 @@ +.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_cq_advance 3 "January 25, 2022" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_cq_advance \- mark one or more io_uring completion events as consumed +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_cq_advance(struct io_uring *" ring "," +.BI " unsigned " nr ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_cq_advance (3) +function marks +.I nr +IO completions belonging to the +.I ring +param as consumed. + +After the caller has submitted a request with +.BR io_uring_submit (3), +the application can retrieve the completion with +.BR io_uring_wait_cqe (3), +.BR io_uring_peek_cqe (3), +or any of the other CQE retrieval helpers, and mark it as consumed with +.BR io_uring_cqe_seen (3). + +The function +.BR io_uring_cqe_seen (3) +calls the function +.BR io_uring_cq_advance (3). + +Completions must be marked as seen, so their slot can get reused. Failure to do +so will result in the same completion being returned on the next invocation. + +.SH RETURN VALUE +None +.SH SEE ALSO +.BR io_uring_submit (3), +.BR io_uring_wait_cqe (3), +.BR io_uring_peek_cqe (3), +.BR io_uring_wait_cqes (3), +.BR io_uring_wait_cqe_timeout (3), +.BR io_uring_cqe_seen (3) diff --git a/man/io_uring_cq_ready.3 b/man/io_uring_cq_ready.3 new file mode 100644 index 0000000..e411a64 --- /dev/null +++ b/man/io_uring_cq_ready.3 @@ -0,0 +1,26 @@ +.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_cq_ready "January 25, 2022" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_cq_ready \- returns number of unconsumed ready entries in the CQ ring +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "unsigned io_uring_cq_ready(const struct io_uring *" ring ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_cq_ready (3) +function retuns the number of unconsumed entries that are ready belonging to the +.I ring +param. + +.SH RETURN VALUE +Returns the number of unconsumed ready entries in the CQ ring. +.SH SEE ALSO +.BR io_uring_submit (3), +.BR io_uring_wait_cqe (3) diff --git a/man/io_uring_cqe_get_data.3 b/man/io_uring_cqe_get_data.3 new file mode 100644 index 0000000..4cbb32c --- /dev/null +++ b/man/io_uring_cqe_get_data.3 @@ -0,0 +1,53 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_cqe_get_data 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_cqe_get_data \- get user data for completion event +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void *io_uring_cqe_get_data(struct io_uring_cqe *" cqe ");" +.BI " +.BI "__u64 io_uring_cqe_get_data64(struct io_uring_cqe *" cqe ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_cqe_get_data (3) +function returns the user_data with the completion queue entry +.IR cqe +as a data pointer. + +The +.BR io_uring_cqe_get_data64 (3) +function returns the user_data with the completion queue entry +.IR cqe +as a 64-bit data value. + +After the caller has received a completion queue entry (CQE) with +.BR io_uring_wait_cqe (3), +the application can call +.BR io_uring_cqe_get_data (3) +or +.BR io_uring_cqe_get_data64 (3) +function to retrieve the +.I user_data +value. This requires that +.I user_data +has been set earlier with the function +.BR io_uring_sqe_set_data (3) +or +.BR io_uring_sqe_set_data64 (3). + +.SH RETURN VALUE +If the +.I user_data +value has been set before submitting the request, it will be returned. +Otherwise the functions returns NULL. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_sqe_set_data (3), +.BR io_uring_sqe_submit (3) diff --git a/man/io_uring_cqe_get_data64.3 b/man/io_uring_cqe_get_data64.3 new file mode 120000 index 0000000..51991c2 --- /dev/null +++ b/man/io_uring_cqe_get_data64.3 @@ -0,0 +1 @@ +io_uring_cqe_get_data.3
\ No newline at end of file diff --git a/man/io_uring_cqe_seen.3 b/man/io_uring_cqe_seen.3 new file mode 100644 index 0000000..d2f2984 --- /dev/null +++ b/man/io_uring_cqe_seen.3 @@ -0,0 +1,42 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_cqe_seen 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_cqe_seen \- mark io_uring completion event as consumed +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_cqe_seen(struct io_uring *" ring "," +.BI " struct io_uring_cqe *" cqe ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_cqe_seen (3) +function marks the IO completion +.I cqe +belonging to the +.I ring +param as consumed. + +After the caller has submitted a request with +.BR io_uring_submit (3), +the application can retrieve the completion with +.BR io_uring_wait_cqe (3), +.BR io_uring_peek_cqe (3), +or any of the other CQE retrieval helpers, and mark it as consumed with +.BR io_uring_cqe_seen (3). + +Completions must be marked as completed so their slot can get reused. +.SH RETURN VALUE +None +.SH SEE ALSO +.BR io_uring_submit (3), +.BR io_uring_wait_cqe (3), +.BR io_uring_peek_cqe (3), +.BR io_uring_wait_cqes (3), +.BR io_uring_wait_cqe_timeout (3), +.BR io_uring_cqe_seen (3) diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2 index 909cc9b..3c04541 100644 --- a/man/io_uring_enter.2 +++ b/man/io_uring_enter.2 @@ -55,6 +55,52 @@ application can no longer get a free SQE entry to submit, without knowing when it one becomes available as the SQ kernel thread consumes them. If the system call is used with this flag set, then it will wait until at least one entry is free in the SQ ring. +.TP +.B IORING_ENTER_EXT_ARG +Since kernel 5.11, the system calls arguments have been modified to look like +the following: + +.nf +.BI "int io_uring_enter(unsigned int " fd ", unsigned int " to_submit , +.BI " unsigned int " min_complete ", unsigned int " flags , +.BI " const void *" arg ", size_t " argsz ); +.fi + +which is behaves just like the original definition by default. However, if +.B IORING_ENTER_EXT_ARG +is set, then instead of a +.I sigset_t +being passed in, a pointer to a +.I struct io_uring_getevents_arg +is used instead and +.I argsz +must be set to the size of this structure. The definition is as follows: + +.nf +.BI "struct io_uring_getevents_args { +.BI " __u64 sigmask; +.BI " __u32 sigmask_sz; +.BI " __u32 pad; +.BI " __u64 ts; +.BI "}; +.fi + +which allows passing in both a signal mask as well as pointer to a +.I struct __kernel_timespec +timeout value. If +.I ts +is set to a valid pointer, then this time value indicates the timeout for +waiting on events. If an application is waiting on events and wishes to +stop waiting after a specified amount of time, then this can be accomplished +directly in version 5.11 and newer by using this feature. +.TP +.B IORING_ENTER_REGISTERED_RING +If the ring file descriptor has been registered through use of +.B IORING_REGISTER_RING_FDS, +then setting this flag will tell the kernel that the +.I ring_fd +passed in is the registered ring offset rather than a normal file descriptor. + .PP .PP If the io_uring instance was configured for polling, by specifying @@ -159,22 +205,28 @@ struct io_uring_sqe { __u32 statx_flags; __u32 fadvise_advice; __u32 splice_flags; + __u32 rename_flags; + __u32 unlink_flags; + __u32 hardlink_flags; }; __u64 user_data; /* data to be passed back at completion time */ union { - struct { - /* index into fixed buffers, if used */ + struct { + /* index into fixed buffers, if used */ union { /* index into fixed buffers, if used */ __u16 buf_index; /* for grouped buffer selection */ __u16 buf_group; } - /* personality to use, if used */ - __u16 personality; + /* personality to use, if used */ + __u16 personality; + union { __s32 splice_fd_in; + __u32 file_index; }; - __u64 __pad2[3]; + }; + __u64 __pad2[3]; }; }; .EE @@ -228,11 +280,55 @@ specified in the .I poll_events field. Unlike poll or epoll without .BR EPOLLONESHOT , -this interface always works in one shot mode. That is, once the poll -operation is completed, it will have to be resubmitted. This command works like +by default this interface always works in one shot mode. That is, once the poll +operation is completed, it will have to be resubmitted. + +If +.B IORING_POLL_ADD_MULTI +is set in the SQE +.I len +field, then the poll will work in multi shot mode instead. That means it'll +repatedly trigger when the requested event becomes true, and hence multiple +CQEs can be generated from this single SQE. The CQE +.I flags +field will have +.B IORING_CQE_F_MORE +set on completion if the application should expect further CQE entries from +the original request. If this flag isn't set on completion, then the poll +request has been terminated and no further events will be generated. This mode +is available since 5.13. + +If +.B IORING_POLL_UPDATE_EVENTS +is set in the SQE +.I len +field, then the request will update an existing poll request with the mask of +events passed in with this request. The lookup is based on the +.I user_data +field of the original SQE submitted, and this values is passed in the +.I addr +field of the SQE. This mode is available since 5.13. + +If +.B IORING_POLL_UPDATE_USER_DATA +is set in the SQE +.I len +field, then the request will update the +.I user_data +of an existing poll request based on the value passed in the +.I off +field. This mode is available since 5.13. + +This command works like an async .BR poll(2) -and the completion event result is the returned mask of events. +and the completion event result is the returned mask of events. For the +variants that update +.I user_data +or +.I events +, the completion result will be similar to +.B IORING_OP_POLL_REMOVE. .TP .B IORING_OP_POLL_REMOVE @@ -243,7 +339,10 @@ field of the will contain 0. If not found, .I res will contain -.B -ENOENT. +.B -ENOENT, +or +.B -EALREADY +if the poll request was in the process of completing already. .TP .B IORING_OP_EPOLL_CTL @@ -342,10 +441,32 @@ clock source. The request will complete with if the timeout got completed through expiration of the timer, or .I 0 if the timeout got completed through requests completing on their own. If -the timeout was cancelled before it expired, the request will complete with +the timeout was canceled before it expired, the request will complete with .I -ECANCELED. Available since 5.4. +Since 5.15, this command also supports the following modifiers in +.I timeout_flags: + +.PP +.in +12 +.B IORING_TIMEOUT_BOOTTIME +If set, then the clocksource used is +.I CLOCK_BOOTTIME +instead of +.I CLOCK_MONOTONIC. +This clocksource differs in that it includes time elapsed if the system was +suspend while having a timeout request in-flight. + +.B IORING_TIMEOUT_REALTIME +If set, then the clocksource used is +.I CLOCK_BOOTTIME +instead of +.I CLOCK_MONOTONIC. +.EE +.in +.PP + .TP .B IORING_OP_TIMEOUT_REMOVE If @@ -355,7 +476,7 @@ operation. must contain the .I user_data field of the previously issued timeout operation. If the specified timeout -request is found and cancelled successfully, this request will terminate +request is found and canceled successfully, this request will terminate with a result value of .I 0 If the timeout request was found but expiration was already in progress, @@ -370,13 +491,14 @@ If .I timeout_flags contain .I IORING_TIMEOUT_UPDATE, -instead of removing an existing operation it updates it. +instead of removing an existing operation, it updates it. .I addr and return values are same as before. .I addr2 field must contain a pointer to a struct timespec64 structure. .I timeout_flags -may also contain IORING_TIMEOUT_ABS. +may also contain IORING_TIMEOUT_ABS, in which case the value given is an +absolute one, not a relative one. Available since 5.11. .TP @@ -389,26 +511,47 @@ must be set to the socket file descriptor, .I addr must contain the pointer to the sockaddr structure, and .I addr2 -must contain a pointer to the socklen_t addrlen field. See also +must contain a pointer to the socklen_t addrlen field. Flags can be passed using +the +.I accept_flags +field. See also .BR accept4(2) for the general description of the related system call. Available since 5.5. +If the +.I file_index +field is set to a positive number, the file won't be installed into the +normal file table as usual but will be placed into the fixed file table at index +.I file_index - 1. +In this case, instead of returning a file descriptor, the result will contain +either 0 on success or an error. If the index points to a valid empty slot, the +installation is guaranteed to not fail. If there is already a file in the slot, +it will be replaced, similar to +.B IORING_OP_FILES_UPDATE. +Please note that only io_uring has access to such files and no other syscall +can use them. See +.B IOSQE_FIXED_FILE +and +.B IORING_REGISTER_FILES. + +Available since 5.5. + .TP .B IORING_OP_ASYNC_CANCEL Attempt to cancel an already issued request. .I addr must contain the .I user_data -field of the request that should be cancelled. The cancellation request will +field of the request that should be canceled. The cancelation request will complete with one of the following results codes. If found, the .I res field of the cqe will contain 0. If not found, .I res -will contain -ENOENT. If found and attempted cancelled, the +will contain -ENOENT. If found and attempted canceled, the .I res field will contain -EALREADY. In this case, the request may or may not terminate. In general, requests that are interruptible (like socket IO) will -get cancelled, while disk IO requests cannot be cancelled if already started. +get canceled, while disk IO requests cannot be canceled if already started. Available since 5.5. .TP @@ -426,9 +569,9 @@ If used, the timeout specified in the command will cancel the linked command, unless the linked command completes before the timeout. The timeout will complete with .I -ETIME -if the timer expired and the linked request was attempted cancelled, or +if the timer expired and the linked request was attempted canceled, or .I -ECANCELED -if the timer got cancelled because of completion of the linked request. Like +if the timer got canceled because of completion of the linked request. Like .B IORING_OP_TIMEOUT the clock source used is .B CLOCK_MONOTONIC @@ -516,6 +659,24 @@ is access mode of the file. See also .BR openat(2) for the general description of the related system call. Available since 5.6. +If the +.I file_index +field is set to a positive number, the file won't be installed into the +normal file table as usual but will be placed into the fixed file table at index +.I file_index - 1. +In this case, instead of returning a file descriptor, the result will contain +either 0 on success or an error. If the index points to a valid empty slot, the +installation is guaranteed to not fail. If there is already a file in the slot, +it will be replaced, similar to +.B IORING_OP_FILES_UPDATE. +Please note that only io_uring has access to such files and no other syscall +can use them. See +.B IOSQE_FIXED_FILE +and +.B IORING_REGISTER_FILES. + +Available since 5.15. + .TP .B IORING_OP_OPENAT2 Issue the equivalent of a @@ -536,6 +697,24 @@ should be set to the address of the open_how structure. See also .BR openat2(2) for the general description of the related system call. Available since 5.6. +If the +.I file_index +field is set to a positive number, the file won't be installed into the +normal file table as usual but will be placed into the fixed file table at index +.I file_index - 1. +In this case, instead of returning a file descriptor, the result will contain +either 0 on success or an error. If the index points to a valid empty slot, the +installation is guaranteed to not fail. If there is already a file in the slot, +it will be replaced, similar to +.B IORING_OP_FILES_UPDATE. +Please note that only io_uring has access to such files and no other syscall +can use them. See +.B IOSQE_FIXED_FILE +and +.B IORING_REGISTER_FILES. + +Available since 5.15. + .TP .B IORING_OP_CLOSE Issue the equivalent of a @@ -545,6 +724,18 @@ system call. is the file descriptor to be closed. See also .BR close(2) for the general description of the related system call. Available since 5.6. +If the +.I file_index +field is set to a positive number, this command can be used to close files +that were direct opened through +.B IORING_OP_OPENAT +, +.B IORING_OP_OPENAT2 +, or +.B IORING_OP_ACCEPT +using the io_uring specific direct descriptors. Note that only one of the +descriptor fields may be set. The direct close feature is available since +the 5.15 kernel, where direct descriptors were introduced. .TP .B IORING_OP_STATX @@ -596,7 +787,9 @@ does not refer to a seekable file, .I off must be set to zero. If .I offs -is set to -1, the offset will use (and advance) the file position, like the +is set to +.B -1 +, the offset will use (and advance) the file position, like the .BR read(2) and .BR write(2) @@ -622,8 +815,9 @@ is an offset to read from, .I fd is the file descriptor to write to, .I off -is an offset from which to start writing to. A sentinel value of -1 is used -to pass the equivalent of a NULL for the offsets to +is an offset from which to start writing to. A sentinel value of +.B -1 +is used to pass the equivalent of a NULL for the offsets to .BR splice(2). .I len contains the number of bytes to copy. @@ -724,8 +918,11 @@ Issue the equivalent of a .BR shutdown(2) system call. .I fd -is the file descriptor to the socket being shutdown, no other fields should -be set. Available since 5.11. +is the file descriptor to the socket being shutdown, and +.I len +must be set to the +.I how +argument. No no other fields should be set. Available since 5.11. .TP .B IORING_OP_RENAMEAT @@ -774,6 +971,90 @@ being passed in to .BR unlinkat(2). Available since 5.11. +.TP +.B IORING_OP_MKDIRAT +Issue the equivalent of a +.BR mkdirat2(2) +system call. +.I fd +should be set to the +.I dirfd, +.I addr +should be set to the +.I pathname, +and +.I len +should be set to the +.I mode +being passed in to +.BR mkdirat(2). +Available since 5.15. + +.TP +.B IORING_OP_SYMLINKAT +Issue the equivalent of a +.BR symlinkat2(2) +system call. +.I fd +should be set to the +.I newdirfd, +.I addr +should be set to the +.I target +and +.I addr2 +should be set to the +.I linkpath +being passed in to +.BR symlinkat(2). +Available since 5.15. + +.TP +.B IORING_OP_LINKAT +Issue the equivalent of a +.BR linkat2(2) +system call. +.I fd +should be set to the +.I olddirfd, +.I addr +should be set to the +.I oldpath, +.I len +should be set to the +.I newdirfd, +.I addr2 +should be set to the +.I newpath, +and +.I hardlink_flags +should be set to the +.I flags +being passed in to +.BR linkat(2). +Available since 5.15. + +.TP +.B IORING_OP_MSG_RING +Send a message to an io_uring. +.I fd +must be set to a file descriptor of a ring that the application has access to, +.I len +can be set to any 32-bit value that the application wishes to pass on, and +.I off +should be set any 64-bit value that the application wishes to send. On the +target ring, a CQE will be posted with the +.I res +field matching the +.I len +set, and a +.I user_data +field matching the +.I off +value being passed in. This request type can be used to either just wake or +interrupt anyone waiting for completions on the target ring, ot it can be used +to pass messages via the two fields. Available since 5.18. + .PP The .I flags @@ -786,7 +1067,10 @@ is an index into the files array registered with the io_uring instance (see the .B IORING_REGISTER_FILES section of the .BR io_uring_register (2) -man page). Available since 5.1. +man page). Note that this isn't always available for all commands. If used on +a command that doesn't support fixed files, the SQE will error with +.B -EBADF. +Available since 5.1. .TP .B IOSQE_IO_DRAIN When this flag is specified, the SQE will not be started before previously @@ -794,12 +1078,14 @@ submitted SQEs have completed, and new SQEs will not be started before this one completes. Available since 5.2. .TP .B IOSQE_IO_LINK -When this flag is specified, it forms a link with the next SQE in the -submission ring. That next SQE will not be started before this one completes. -This, in effect, forms a chain of SQEs, which can be arbitrarily long. The tail -of the chain is denoted by the first SQE that does not have this flag set. -This flag has no effect on previous SQE submissions, nor does it impact SQEs -that are outside of the chain tail. This means that multiple chains can be +When this flag is specified, the SQE forms a link with the next SQE in the +submission ring. That next SQE will not be started before the previous request +completes. This, in effect, forms a chain of SQEs, which can be arbitrarily +long. The tail of the chain is denoted by the first SQE that does not have this +flag set. Chains are not supported across submission boundaries. Even if the +last SQE in a submission has this flag set, it will still terminate the current +chain. This flag has no effect on previous SQE submissions, nor does it impact +SQEs that are outside of the chain tail. This means that multiple chains can be executing in parallel, or chains and individual SQEs. Only members inside the chain are serialized. A chain of SQEs will be broken, if any request in that chain ends in error. io_uring considers any unexpected result an error. This @@ -829,7 +1115,7 @@ Used in conjunction with the command, which registers a pool of buffers to be used by commands that read or receive data. When buffers are registered for this use case, and this flag is set in the command, io_uring will grab a buffer from this pool when -the request is ready to receive or read data. If succesful, the resulting CQE +the request is ready to receive or read data. If successful, the resulting CQE will have .B IORING_CQE_F_BUFFER set in the flags part of the struct, and the upper @@ -841,6 +1127,37 @@ are available and this flag is set, then the request will fail with as the error code. Once a buffer has been used, it is no longer available in the kernel pool. The application must re-register the given buffer again when it is ready to recycle it (eg has completed using it). Available since 5.7. +.TP +.B IOSQE_CQE_SKIP_SUCCESS +Don't generate a CQE if the request completes successfully. If the request +fails, an appropriate CQE will be posted as usual and if there is no +.B IOSQE_IO_HARDLINK, +CQEs for all linked requests will be omitted. The notion of failure/success is +opcode specific and is the same as with breaking chains of +.B IOSQE_IO_LINK. +One special case is when the request has a linked timeout, then the CQE +generation for the linked timeout is decided solely by whether it has +.B IOSQE_CQE_SKIP_SUCCESS +set, regardless whether it timed out or was canceled. In other words, if a +linked timeout has the flag set, it's guaranteed to not post a CQE. + +The semantics are chosen to accommodate several use cases. First, when all but +the last request of a normal link without linked timeouts are marked with the +flag, only one CQE per lin is posted. Additionally, it enables supression of +CQEs in cases where the side effects of a successfully executed operation is +enough for userspace to know the state of the system. One such example would +be writing to a synchronisation file. + +This flag is incompatible with +.B IOSQE_IO_DRAIN. +Using both of them in a single ring is undefined behavior, even when they are +not used together in a single request. Currently, after the first request with +.B IOSQE_CQE_SKIP_SUCCESS, +all subsequent requests marked with drain will be failed at submission time. +Note that the error reporting is best effort only, and restrictions may change +in the future. + +Available since 5.17. .PP .I ioprio @@ -933,7 +1250,13 @@ is copied from the field of the same name in the submission queue entry. The primary use case is to store data that the application will need to access upon completion of this particular I/O. The .I flags -is reserved for future use. +is used for certain commands, like +.B IORING_OP_POLL_ADD +or in conjunction with +.B IOSQE_BUFFER_SELECT +or +.B IORING_OP_MSG_RING, +, see those entries for details. .I res is the operation-specific result, but io_uring-specific errors (e.g. flags or opcode invalid) are returned through this field. @@ -941,13 +1264,22 @@ They are described in section .B CQE ERRORS. .PP For read and write opcodes, the -return values match those documented in the +return values match +.I errno +values documented in the .BR preadv2 (2) and .BR pwritev2 (2) -man pages. -Return codes for the io_uring-specific opcodes are documented in the -description of the opcodes above. +man pages, with +.I +res +holding the equivalent of +.I -errno +for error cases, or the transferred number of bytes in case the operation +is successful. Hence both error and success return can be found in that +field in the CQE. For other request types, the return values are documented +in the matching man page for that type, or in the opcodes section above for +io_uring-specific opcodes. .PP .SH RETURN VALUE .BR io_uring_enter () @@ -967,7 +1299,9 @@ completion queue entry (see section rather than through the system call itself. Errors that occur not on behalf of a submission queue entry are returned via the -system call directly. On such an error, -1 is returned and +system call directly. On such an error, +.B -1 +is returned and .I errno is set appropriately. .PP diff --git a/man/io_uring_free_probe.3 b/man/io_uring_free_probe.3 new file mode 100644 index 0000000..d2308fa --- /dev/null +++ b/man/io_uring_free_probe.3 @@ -0,0 +1,27 @@ +.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_free_probe "January 25, 2022" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_free_probe \- free probe instance +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_free_probe(struct io_uring_probe *" probe ");" +.fi +.SH DESCRIPTION +.PP +The function +.BR io_uring_free_probe (3) +frees the +.I probe +instance allocated with the +.BR io_uring_get_probe (3) +function. + +.SH RETURN VALUE +None +.SH SEE ALSO +.BR io_uring_get_probe (3) diff --git a/man/io_uring_get_probe.3 b/man/io_uring_get_probe.3 new file mode 100644 index 0000000..94c1b21 --- /dev/null +++ b/man/io_uring_get_probe.3 @@ -0,0 +1,30 @@ +.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_get_probe "January 25, 2022" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_get_probe \- get probe instance +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "io_uring_probe *io_uring_get_probe(void);" +.fi +.SH DESCRIPTION +.PP +The function +.BR io_uring_get_probe (3) +returns an allocated io_uring_probe structure to the caller. The caller is +responsible for freeing the structure with the function +.BR io_uring_free_probe (3). + +.SH NOTES +Earlier versions of the Linux kernel do not support probe. If the kernel +doesn't support probe, this function will return NULL. + +.SH RETURN VALUE +On success it returns an allocated io_uring_probe structure, otherwise +it returns NULL. +.SH SEE ALSO +.BR io_uring_free_probe (3) diff --git a/man/io_uring_get_sqe.3 b/man/io_uring_get_sqe.3 index 24834f3..58c8b96 100644 --- a/man/io_uring_get_sqe.3 +++ b/man/io_uring_get_sqe.3 @@ -5,25 +5,28 @@ .\" .TH io_uring_get_sqe 3 "July 10, 2020" "liburing-0.7" "liburing Manual" .SH NAME -io_uring_get_sqe - get the next vacant event from the submission queue +io_uring_get_sqe \- get the next available submission queue entry from the +submission queue .SH SYNOPSIS .nf -.BR "#include <liburing.h>" +.B #include <liburing.h> .PP -.BI "struct io_uring_sqe *io_uring_get_sqe(struct io_uring " *ring ); +.BI "struct io_uring_sqe *io_uring_get_sqe(struct io_uring *" ring ");" .fi -.PP .SH DESCRIPTION .PP -The io_uring_get_sqe() function gets the next vacant event from the submission +The +.BR io_uring_get_sqe (3) +function gets the next available submission queue entry from the submission queue belonging to the .I ring param. -On success io_uring_get_sqe() returns a pointer to the submission queue event. -On failure NULL is returned. +On success +.BR io_uring_get_sqe (3) +returns a pointer to the submission queue entry. On failure NULL is returned. -If a submission queue event is returned, it should be filled out via one of the +If a submission queue entry is returned, it should be filled out via one of the prep functions such as .BR io_uring_prep_read (3) and submitted via @@ -32,6 +35,7 @@ and submitted via .SH RETURN VALUE .BR io_uring_get_sqe (3) returns a pointer to the next submission queue event on success and NULL on -failure. +failure. If NULL is returned, the SQ ring is currently full and entries must +be submitted for processing before new ones can get allocated. .SH SEE ALSO .BR io_uring_submit (3) diff --git a/man/io_uring_opcode_supported.3 b/man/io_uring_opcode_supported.3 new file mode 100644 index 0000000..b20b504 --- /dev/null +++ b/man/io_uring_opcode_supported.3 @@ -0,0 +1,30 @@ +.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_opcode_supported "January 25, 2022" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_opcode_supported \- is op code supported? +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_opcode_supported(struct io_uring_probe *" probe "," +.BI " int " opcode ");" +.fi +.SH DESCRIPTION +.PP +The function +.BR io_uring_opcode_supported (3) +allows the caller to determine if the passed in +.I opcode +belonging to the +.I probe +param is supported. An instance of the io_uring_probe instance can be +obtained by calling the function +.BR io_uring_get_probe (3). + +.SH RETURN VALUE +On success it returns 1, otherwise it returns 0. +.SH SEE ALSO +.BR io_uring_get_probe (3) diff --git a/man/io_uring_peek_cqe.3 b/man/io_uring_peek_cqe.3 new file mode 100644 index 0000000..a4ac2da --- /dev/null +++ b/man/io_uring_peek_cqe.3 @@ -0,0 +1,38 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_peek_cqe 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_peek_cqe \- check if an io_uring completion event is available +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_peek_cqe(struct io_uring *" ring "," +.BI " struct io_uring_cqe **" cqe_ptr ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_peek_cqe (3) +function returns an IO completion from the queue belonging to the +.I ring +param, if one is readily available. On successful return, +.I cqe_ptr +param is filled with a valid CQE entry. + +This function does not enter the kernel to wait for an event, an event +is only returned if it's already available in the CQ ring. + +.SH RETURN VALUE +On success +.BR io_uring_peek_cqe (3) +returns +.B 0 +and the cqe_ptr parameter is filled in. On failure it returns +.BR -EAGAIN . +.SH SEE ALSO +.BR io_uring_submit (3), +.BR io_uring_wait_cqes (3), +.BR io_uring_wait_cqe (3) diff --git a/man/io_uring_prep_accept.3 b/man/io_uring_prep_accept.3 new file mode 100644 index 0000000..3800ccb --- /dev/null +++ b/man/io_uring_prep_accept.3 @@ -0,0 +1,159 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_accept 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_accept \- prepare an accept request +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_accept(struct io_uring_sqe *" sqe "," +.BI " int " sockfd "," +.BI " struct sockaddr *" addr "," +.BI " socklen_t *" addrlen "," +.BI " int " flags ");" +.PP +.BI "void io_uring_prep_accept_direct(struct io_uring_sqe *" sqe "," +.BI " int " sockfd "," +.BI " struct sockaddr *" addr "," +.BI " socklen_t *" addrlen "," +.BI " int " flags "," +.BI " unsigned int " file_index ");" +.PP +.BI "void io_uring_prep_multishot_accept(struct io_uring_sqe *" sqe "," +.BI " int " sockfd "," +.BI " struct sockaddr *" addr "," +.BI " socklen_t *" addrlen "," +.BI " int " flags ");" +.PP +.BI "void io_uring_prep_multishot_accept_direct(struct io_uring_sqe *" sqe "," +.BI " int " sockfd "," +.BI " struct sockaddr *" addr "," +.BI " socklen_t *" addrlen "," +.BI " int " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_accept (3) +function prepares an accept request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I sockfd +to start accepting a connection request described by the socket address at +.I addr +and of structure length +.I addrlen +and using modifier flags in +.IR flags . + +For a direct descriptor accept request, the offset is specified by the +.I file_index +argument. Direct descriptors are io_uring private file descriptors. They +avoid some of the overhead associated with thread shared file tables and +can be used in any io_uring request that takes a file descriptor. To do so, +.B IOSQE_FIXED_FILE +must be set in the SQE +.I flags +member, and the SQE +.I fd +field should use the direct descriptor value rather than the regular file +descriptor. Direct descriptors are managed like registered files. + +If the direct variant is used, the application must first have registered +a file table using +.BR io_uring_register_files (3) +of the appropriate size. Once registered, a direct accept request may use any +entry in that table, as long as it is within the size of the registered table. +If a specified entry already contains a file, the file will first be removed +from the table and closed. It's consistent with the behavior of updating an +existing file with +.BR io_uring_register_files_update (3). +Note that old kernels don't check the SQE +.I file_index +field, which is not a problem for liburing helpers, but users of the raw +io_uring interface need to zero SQEs to avoid unexpected behavior. This also +means that applications should check for availability of +.B IORING_OP_ACCEPT_DIRECT +before using it, they cannot rely on a +.B -EINVAL +CQE +.I res +return. + +For a direct descriptor accept request, the +.I file_index +argument can be set to +.BR IORING_FILE_INDEX_ALLOC , +In this case a free entry in io_uring file table will +be used automatically and the file index will be returned as CQE +.IR res . +.B -ENFILE +is otherwise returned if there is no free entries in the io_uring file table. + +The multishot version accept and accept_direct allow an application to issue +a single accept request, which will repeatedly trigger a CQE when a connection +request comes in. Like other multishot type requests, the application should +look at the CQE +.I flags +and see if +.B IORING_CQE_F_MORE +is set on completion as an indication of whether or not the accept request +will generate further CQEs. The multishot variants are available since 5.19. + +For multishot with direct descriptors, +.B IORING_FILE_INDEX_ALLOC +must be used as the file descriptor. This tells io_uring to allocate a free +direct descriptor from our table, rather than the application passing one in. +Failure to do so will result in the accept request being terminated with +.BR -EINVAL . +The allocated descriptor will be returned in the CQE +.I res +field, like a non-direct accept request. + +These functions prepare an async +.BR accept4 (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. For singleshot accept, the +non-direct accept returns the installed file descriptor as its value, the +direct accept returns +.B 0 +on success. The caller must know which direct descriptor was picked for this +request. For multishot accept, the non-direct accept returns the installed +file descriptor as its value, the direct accept returns the file index used on +success. See the related man page for details on possible values for the +non-direct accept. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_register (2), +.BR accept4 (2) diff --git a/man/io_uring_prep_accept_direct.3 b/man/io_uring_prep_accept_direct.3 new file mode 120000 index 0000000..0404bf5 --- /dev/null +++ b/man/io_uring_prep_accept_direct.3 @@ -0,0 +1 @@ +io_uring_prep_accept.3
\ No newline at end of file diff --git a/man/io_uring_prep_cancel.3 b/man/io_uring_prep_cancel.3 new file mode 100644 index 0000000..3c9f2df --- /dev/null +++ b/man/io_uring_prep_cancel.3 @@ -0,0 +1,118 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_cancel 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_cancel \- prepare a cancelation request +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_cancel64(struct io_uring_sqe *" sqe "," +.BI " __u64 " user_data "," +.BI " int " flags ");" +.PP +.BI "void io_uring_prep_cancel(struct io_uring_sqe *" sqe "," +.BI " void *" user_data "," +.BI " int " flags ");" +.PP +.BI "void io_uring_prep_cancel_fd(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " int " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_cancel (3) +function prepares a cancelation request. The submission queue entry +.I sqe +is prepared to cancel an existing request identified by +.IR user_data . +For the +.I flags +argument, see below. + +.BR io_uring_prep_cancel64 (3) +is identical to +.BR io_uring_prep_cancel (3) , +except it takes a 64-bit integer rather than a pointer type. + +The cancelation request will attempt to find the previously issued request +identified by +.I user_data +and cancel it. The identifier is what the previously issued request has in +their +.I user_data +field in the SQE. + +The +.BR io_uring_prep_cancel_fd (3) +function prepares a cancelation request. The submission queue entry +.I sqe +is prepared to cancel an existing request that used the file descriptor +.IR fd . +For the +.I flags +argument, see below. + +The cancelation request will attempt to find the previously issued request +that used +.I fd +as the file descriptor and cancel it. + +By default, the first request matching the criteria given will be canceled. +This can be modified with any of the following flags passed in: +.TP +.B IORING_ASYNC_CANCEL_ALL +Cancel all requests that match the given criteria, rather than just canceling +the first one found. Available since 5.19. +.TP +.B IORING_ASYNC_CANCEL_FD +Match based on the file descriptor used in the original request rather than +the user_data. This is what +.BR io_uring_prep_cancel_fd (3) +sets up. Available since 5.19. +.TP +.B IORING_ASYNC_CANCEL_ANY +Match any request in the ring, regardless of user_data or file descriptor. +Can be used to cancel any pending request in the ring. Available since 5.19. +.P + +.SH RETURN VALUE +None +.SH ERRORS +These are the errors that are reported in the CQE +.I res +field. If no flags are used to cancel multiple requests, +.B 0 +is returned on success. If flags are used to match multiple requests, then +a positive value is returned indicating how many requests were found and +canceled. +.TP +.B -ENOENT +The request identified by +.I user_data +could not be located. This could be because it completed before the cancelation +request was issued, or if an invalid identifier is used. +.TP +.B -EINVAL +One of the fields set in the SQE was invalid. +.TP +.B -EALREADY +The execution state of the request has progressed far enough that cancelation +is no longer possible. This should normally mean that it will complete shortly, +either successfully, or interrupted due to the cancelation. +.SH NOTES +Although the cancelation request uses async request syntax, the kernel side of +the cancelation is always run synchronously. It is guaranteed that a CQE is +always generated by the time the cancel request has been submitted. If the +cancelation is successful, the completion for the request targeted for +cancelation will have been posted by the time submission returns. For +.B -EALREADY +it may take a bit of time to do so. For this case, the caller must wait for the +canceled request to post its completion event. +.SH SEE ALSO +.BR io_uring_prep_poll_remove (3), +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3) diff --git a/man/io_uring_prep_cancel64.3 b/man/io_uring_prep_cancel64.3 new file mode 120000 index 0000000..347db09 --- /dev/null +++ b/man/io_uring_prep_cancel64.3 @@ -0,0 +1 @@ +io_uring_prep_cancel.3
\ No newline at end of file diff --git a/man/io_uring_prep_close.3 b/man/io_uring_prep_close.3 new file mode 100644 index 0000000..94780f2 --- /dev/null +++ b/man/io_uring_prep_close.3 @@ -0,0 +1,59 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_close 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_close \- prepare a file descriptor close request +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_close(struct io_uring_sqe *" sqe "," +.BI " int " fd ");" +.PP +.BI "void io_uring_prep_close_direct(struct io_uring_sqe *" sqe "," +.BI " unsigned " file_index ");" +.PP +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_close (3) +function prepares a close request. The submission queue entry +.I sqe +is setup to close the file descriptor indicated by +.IR fd . + +For a direct descriptor close request, the offset is specified by the +.I file_index +argument instead of the +.IR fd . +This is identical to unregistering the direct descriptor, and is provided as +a convenience. + +These functions prepare an async +.BR close (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR close (2) diff --git a/man/io_uring_prep_close_direct.3 b/man/io_uring_prep_close_direct.3 new file mode 120000 index 0000000..d9ce6a6 --- /dev/null +++ b/man/io_uring_prep_close_direct.3 @@ -0,0 +1 @@ +io_uring_prep_close.3
\ No newline at end of file diff --git a/man/io_uring_prep_connect.3 b/man/io_uring_prep_connect.3 new file mode 100644 index 0000000..6a7c64a --- /dev/null +++ b/man/io_uring_prep_connect.3 @@ -0,0 +1,66 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_connect 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_connect \- prepare a connect request +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <sys/socket.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_connect(struct io_uring_sqe *" sqe "," +.BI " int " sockfd "," +.BI " const struct sockaddr *" addr "," +.BI " socklen_t " addrlen ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_connect (3) +function prepares a connect request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I sockfd +to start connecting to the destination described by the socket address at +.I addr +and of structure length +.IR addrlen . + +This function prepares an async +.BR connect (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR connect (2) diff --git a/man/io_uring_prep_fadvise.3 b/man/io_uring_prep_fadvise.3 new file mode 100644 index 0000000..a53ab25 --- /dev/null +++ b/man/io_uring_prep_fadvise.3 @@ -0,0 +1,59 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_fadvise 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_fadvise \- prepare a fadvise request +.SH SYNOPSIS +.nf +.B #include <fcntl.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_fadvise(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " __u64 " offset "," +.BI " off_t " len "," +.BI " int " advice ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_fadvise (3) +function prepares an fadvise request. The submission queue entry +.I sqe +is setup to use the file descriptor pointed to by +.I fd +to start an fadvise operation at +.I offset +and of +.I len +length in bytes, giving it the advise located in +.IR advice . + +This function prepares an async +.BR posix_fadvise (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_register (2), +.BR posix_fadvise (2) diff --git a/man/io_uring_prep_fallocate.3 b/man/io_uring_prep_fallocate.3 new file mode 100644 index 0000000..86e1d39 --- /dev/null +++ b/man/io_uring_prep_fallocate.3 @@ -0,0 +1,59 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_fallocate 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_fallocate \- prepare a fallocate request +.SH SYNOPSIS +.nf +.B #include <fcntl.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_fallocate(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " int " mode "," +.BI " off_t " offset "," +.BI " off_t " len ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_fallocate (3) +function prepares a fallocate request. The submission queue entry +.I sqe +is setup to use the file descriptor pointed to by +.I fd +to start a fallocate operation described by +.I mode +at offset +.I offset +and +.I len +length in bytes. + +This function prepares an async +.BR fallocate (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR fallocate (2) diff --git a/man/io_uring_prep_files_update.3 b/man/io_uring_prep_files_update.3 new file mode 100644 index 0000000..bedb85e --- /dev/null +++ b/man/io_uring_prep_files_update.3 @@ -0,0 +1,92 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_files_update 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_files_update \- prepare a registered file update request +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_files_update(struct io_uring_sqe *" sqe "," +.BI " int *" fds "," +.BI " unsigned " nr_fds "," +.BI " int " offset ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_files_update (3) +function prepares a request for updating a number of previously registered file +descriptors. The submission queue entry +.I sqe +is setup to use the file descriptor array pointed to by +.I fds +and of +.I nr_fds +in length to update that amount of previously registered files starting at +offset +.IR offset . + +Once a previously registered file is updated with a new one, the existing +entry is updated and then removed from the table. This operation is equivalent to +first unregistering that entry and then inserting a new one, just bundled into +one combined operation. + +If +.I offset +is specified as IORING_FILE_INDEX_ALLOC, io_uring will allocate free direct +descriptors instead of having the application to pass, and store allocated +direct descriptors into +.I fds +array, +.I cqe->res +will return the number of direct descriptors allocated. + +.SH RETURN VALUE +None +.SH ERRORS +These are the errors that are reported in the CQE +.I res +field. On success, +.I res +will contain the number of successfully updated file descriptors. On error, +the following errors can occur. +.TP +.B -ENOMEM +The kernel was unable to allocate memory for the request. +.TP +.B -EINVAL +One of the fields set in the SQE was invalid. +.TP +.B -EFAULT +The kernel was unable to copy in the memory pointed to by +.IR fds . +.TP +.B -EBADF +On of the descriptors located in +.I fds +didn't refer to a valid file descriptor, or one of the file descriptors in +the array referred to an io_uring instance. +.TP +.B -EOVERFLOW +The product of +.I offset +and +.I nr_fds +exceed the valid amount or overflowed. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_register (2) diff --git a/man/io_uring_prep_fsync.3 b/man/io_uring_prep_fsync.3 new file mode 100644 index 0000000..a3259a0 --- /dev/null +++ b/man/io_uring_prep_fsync.3 @@ -0,0 +1,70 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_fsync 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_fsync \- prepare an fsync request +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_fsync(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " unsigned " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_fsync (3) +function prepares an fsync request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +that should get synced, with the modifier flags indicated by the +.I flags +argument. + +This function prepares an fsync request. It can act either like an +.BR fsync (2) +operation, which is the default behavior. If +.B IORING_FSYNC_DATASYNC +is set in the +.I flags +argument, then it behaves like +.BR fdatasync (2). +If no range is specified, the +.I fd +will be synced from 0 to end-of-file. + +It's possible to specify a range to sync, if one is desired. If the +.I off +field of the SQE is set to non-zero, then that indicates the offset to +start syncing at. If +.I len +is set in the SQE, then that indicates the size in bytes to sync from the +offset. Note that these fields are not accepted by this helper, so they have +to be set manually in the SQE after calling this prep helper. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR fsync (2), +.BR fdatasync (2) diff --git a/man/io_uring_prep_link.3 b/man/io_uring_prep_link.3 new file mode 120000 index 0000000..6d3059d --- /dev/null +++ b/man/io_uring_prep_link.3 @@ -0,0 +1 @@ +io_uring_prep_linkat.3
\ No newline at end of file diff --git a/man/io_uring_prep_linkat.3 b/man/io_uring_prep_linkat.3 new file mode 100644 index 0000000..0949e3b --- /dev/null +++ b/man/io_uring_prep_linkat.3 @@ -0,0 +1,91 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_linkat 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_linkat \- prepare a linkat request +.SH SYNOPSIS +.nf +.B #include <fcntl.h> +.B #include <unistd.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_linkat(struct io_uring_sqe *" sqe "," +.BI " int " olddirfd "," +.BI " const char *" oldpath "," +.BI " int " newdirfd "," +.BI " const char *" newpath "," +.BI " int " flags ");" +.PP +.BI "void io_uring_prep_link(struct io_uring_sqe *" sqe "," +.BI " const char *" oldpath "," +.BI " const char *" newpath "," +.BI " int " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_linkat (3) +function prepares a linkat request. The submission queue entry +.I sqe +is setup to use the old directory file descriptor pointed to by +.I olddirfd +and old path pointed to by +.I oldpath +with the new directory file descriptor pointed to by +.I newdirfd +and the new path pointed to by +.I newpath +and using the specified flags in +.IR flags . + +The +.BR io_uring_prep_link (3) +function prepares a link request. The submission queue entry +.I sqe +is setup to use the old path pointed to by +.I oldpath +and the new path pointed to by +.IR newpath , +both relative to the current working directory and using the specified flags in +.IR flags . + +These functions prepare an async +.BR linkat (2) +or +.BR link (2) +request. See those man pages for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR linkat (2), +.BR link (2) diff --git a/man/io_uring_prep_madvise.3 b/man/io_uring_prep_madvise.3 new file mode 100644 index 0000000..6c5f16b --- /dev/null +++ b/man/io_uring_prep_madvise.3 @@ -0,0 +1,56 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_madvise 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_madvise \- prepare a madvise request +.SH SYNOPSIS +.nf +.B #include <sys/mman.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_madvise(struct io_uring_sqe *" sqe "," +.BI " void *" addr "," +.BI " off_t " len "," +.BI " int " advice ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_madvise (3) +function prepares an madvise request. The submission queue entry +.I sqe +is setup to start an madvise operation at the virtual address of +.I addr +and of +.I len +length in bytes, giving it the advise located in +.IR advice . + +This function prepares an async +.BR madvise (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_register (2), +.BR madvise (2) diff --git a/man/io_uring_prep_mkdir.3 b/man/io_uring_prep_mkdir.3 new file mode 120000 index 0000000..b3412d1 --- /dev/null +++ b/man/io_uring_prep_mkdir.3 @@ -0,0 +1 @@ +io_uring_prep_mkdirat.3
\ No newline at end of file diff --git a/man/io_uring_prep_mkdirat.3 b/man/io_uring_prep_mkdirat.3 new file mode 100644 index 0000000..a98b4e3 --- /dev/null +++ b/man/io_uring_prep_mkdirat.3 @@ -0,0 +1,83 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_mkdirat 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_mkdirat \- prepare an mkdirat request +.SH SYNOPSIS +.nf +.B #include <fcntl.h> +.B #include <sys/stat.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_mkdirat(struct io_uring_sqe *" sqe "," +.BI " int " dirfd "," +.BI " const char *" path "," +.BI " mode_t " mode ");" +.PP +.BI "void io_uring_prep_mkdir(struct io_uring_sqe *" sqe "," +.BI " const char *" path "," +.BI " mode_t " mode ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_mkdirat (3) +function prepares a mkdirat request. The submission queue entry +.I sqe +is setup to use the directory file descriptor pointed to by +.I dirfd +to start a mkdirat operation on the path identified by +.I path +with the mode given in +.IR mode . + +The +.BR io_uring_prep_mkdir (3) +function prepares a mkdir request. The submission queue entry +.I sqe +is setup to use the current working directory to start a mkdir +operation on the path identified by +.I path +with the mode given in +.IR mode . + +These functions prepare an async +.BR mkdir (2) +or +.BR mkdirat (2) +request. See those man pages for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR mkdirat (2), +.BR mkdir (2) diff --git a/man/io_uring_prep_msg_ring.3 b/man/io_uring_prep_msg_ring.3 new file mode 100644 index 0000000..9cf3444 --- /dev/null +++ b/man/io_uring_prep_msg_ring.3 @@ -0,0 +1,72 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_msg_ring 3 "March 10, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_msg_ring \- send a message to another ring +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_msg_ring(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " unsigned int " len "," +.BI " __u64 " data "," +.BI " unsigned int " flags ");" +.fi +.SH DESCRIPTION +.PP +.BR io_uring_prep_msg_ring (3) +prepares a to send a CQE to an io_uring file descriptor. The submission queue +entry +.I sqe +is setup to use the file descriptor +.IR fd , +which must identify a io_uring context, to post a CQE on that ring where the +target CQE +.B res +field will contain the content of +.I len +and the +.B user_data +of +.I data +with the request modifier flags set by +.IR flags . +Currently there are no valid flag modifiers, this field must contain +.BR 0 . + +The targeted ring may be any ring that the user has access to, even the ring +itself. This request can be used for simple message passing to another ring, +allowing 32+64 bits of data to be transferred through the +.I len +and +.I data +fields. The use case may be anything from simply waking up someone waiting +on the targeted ring, or it can be used to pass messages between the two +rings. + +.SH RETURN VALUE +None + +.SH ERRORS +These are the errors that are reported in the CQE +.I res +field. +.TP +.B -ENOMEM +The kernel was unable to allocate memory for the request. +.TP +.B -EINVAL +One of the fields set in the SQE was invalid. +.TP +.B -EBADFD +The descriptor passed in +.I fd +does not refer to an io_uring file descriptor. +.TP +.B -EOVERFLOW +The kernel was unable to fill a CQE on the target ring. This can happen if +the target CQ ring is in an overflow state and the kernel wasn't able to +allocate memory for a new CQE entry. diff --git a/man/io_uring_prep_multishot_accept.3 b/man/io_uring_prep_multishot_accept.3 new file mode 120000 index 0000000..0404bf5 --- /dev/null +++ b/man/io_uring_prep_multishot_accept.3 @@ -0,0 +1 @@ +io_uring_prep_accept.3
\ No newline at end of file diff --git a/man/io_uring_prep_multishot_accept_direct.3 b/man/io_uring_prep_multishot_accept_direct.3 new file mode 120000 index 0000000..0404bf5 --- /dev/null +++ b/man/io_uring_prep_multishot_accept_direct.3 @@ -0,0 +1 @@ +io_uring_prep_accept.3
\ No newline at end of file diff --git a/man/io_uring_prep_openat.3 b/man/io_uring_prep_openat.3 new file mode 100644 index 0000000..e8b4217 --- /dev/null +++ b/man/io_uring_prep_openat.3 @@ -0,0 +1,117 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_openat 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_openat \- prepare an openat request +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <sys/stat.h> +.B #include <fcntl.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_openat(struct io_uring_sqe *" sqe "," +.BI " int " dfd "," +.BI " const char *" path "," +.BI " int " flags "," +.BI " mode_t " mode ");" +.PP +.BI "void io_uring_prep_openat_direct(struct io_uring_sqe *" sqe "," +.BI " int " dfd "," +.BI " const char *" path "," +.BI " int " flags "," +.BI " mode_t " mode "," +.BI " unsigned " file_index ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_openat (3) +function prepares an openat request. The submission queue entry +.I sqe +is setup to use the directory file descriptor +.I dfd +to start opening a file described by +.I path +and using the open flags in +.I flags +and using the file mode bits specified in +.IR mode . + +For a direct descriptor open request, the offset is specified by the +.I file_index +argument. Direct descriptors are io_uring private file descriptors. They +avoid some of the overhead associated with thread shared file tables, and +can be used in any io_uring request that takes a file descriptor. To do so, +.B IOSQE_FIXED_FILE +must be set in the SQE +.I flags +member, and the SQE +.I fd +field should use the direct descriptor value rather than the regular file +descriptor. Direct descriptors are managed like registered files. + +If the direct variant is used, the application must first have registered +a file table using +.BR io_uring_register_files (3) +of the appropriate size. Once registered, a direct accept request may use any +entry in that table, as long as it is within the size of the registered table. +If a specified entry already contains a file, the file will first be removed +from the table and closed. It's consistent with the behavior of updating an +existing file with +.BR io_uring_register_files_update (3). +Note that old kernels don't check the SQE +.I file_index +field, which is not a problem for liburing helpers, but users of the raw +io_uring interface need to zero SQEs to avoid unexpected behavior. + +If +.B IORING_FILE_INDEX_ALLOC +is used as the +.I file_index +for a direct open, then io_uring will allocate a free direct descriptor in +the existing table. The allocated descriptor is returned in the CQE +.I res +field just like it would be for a non-direct open request. If no more entries +are available in the direct descriptor table, +.B -ENFILE +is returned instead. + +These functions prepare an async +.BR openat (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_register (2), +.BR openat (2) diff --git a/man/io_uring_prep_openat2.3 b/man/io_uring_prep_openat2.3 new file mode 100644 index 0000000..338cf7e --- /dev/null +++ b/man/io_uring_prep_openat2.3 @@ -0,0 +1,117 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_openat2 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_openat2 \- prepare an openat2 request +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <sys/stat.h> +.B #include <fcntl.h> +.B #include <linux/openat2.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_openat2(struct io_uring_sqe *" sqe "," +.BI " int " dfd "," +.BI " const char *" path "," +.BI " int " flags "," +.BI " struct open_how *" how ");" +.PP +.BI "void io_uring_prep_openat2_direct(struct io_uring_sqe *" sqe "," +.BI " int " dfd "," +.BI " const char *" path "," +.BI " int " flags "," +.BI " struct open_how *" how "," +.BI " unsigned " file_index ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_openat2 (3) +function prepares an openat2 request. The submission queue entry +.I sqe +is setup to use the directory file descriptor +.I dfd +to start opening a file described by +.I path +and using the open flags in +.I flags +and using the instructions on how to open the file given in +.IR how . + +For a direct descriptor open request, the offset is specified by the +.I file_index +argument. Direct descriptors are io_uring private file descriptors. They +avoid some of the overhead associated with thread shared file tables, and +can be used in any io_uring request that takes a file descriptor. To do so, +.B IOSQE_FIXED_FILE +must be set in the SQE +.I flags +member, and the SQE +.I fd +field should use the direct descriptor value rather than the regular file +descriptor. Direct descriptors are managed like registered files. + +If the direct variant is used, the application must first have registered +a file table using +.BR io_uring_register_files (3) +of the appropriate size. Once registered, a direct accept request may use any +entry in that table, as long as it is within the size of the registered table. +If a specified entry already contains a file, the file will first be removed +from the table and closed. It's consistent with the behavior of updating an +existing file with +.BR io_uring_register_files_update (3). +Note that old kernels don't check the SQE +.I file_index +field, which is not a problem for liburing helpers, but users of the raw +io_uring interface need to zero SQEs to avoid unexpected behavior. +If +.B IORING_FILE_INDEX_ALLOC +is used as the +.I file_index +for a direct open, then io_uring will allocate a free direct descriptor in +the existing table. The allocated descriptor is returned in the CQE +.I res +field just like it would be for a non-direct open request. If no more entries +are available in the direct descriptor table, +.B -ENFILE +is returned instead. + +These functions prepare an async +.BR openat2 (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_register (2), +.BR openat2 (2) diff --git a/man/io_uring_prep_openat2_direct.3 b/man/io_uring_prep_openat2_direct.3 new file mode 120000 index 0000000..2c0e6c9 --- /dev/null +++ b/man/io_uring_prep_openat2_direct.3 @@ -0,0 +1 @@ +io_uring_prep_openat2.3
\ No newline at end of file diff --git a/man/io_uring_prep_openat_direct.3 b/man/io_uring_prep_openat_direct.3 new file mode 120000 index 0000000..67f501e --- /dev/null +++ b/man/io_uring_prep_openat_direct.3 @@ -0,0 +1 @@ +io_uring_prep_openat.3
\ No newline at end of file diff --git a/man/io_uring_prep_poll_add.3 b/man/io_uring_prep_poll_add.3 new file mode 100644 index 0000000..cb60878 --- /dev/null +++ b/man/io_uring_prep_poll_add.3 @@ -0,0 +1,72 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_poll_add 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_poll_add \- prepare a poll request +.SH SYNOPSIS +.nf +.B #include <poll.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_poll_add(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " unsigned " poll_mask ");" +.PP +.BI "void io_uring_prep_poll_multishot(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " unsigned " poll_mask ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_poll_add (3) +function prepares a poll request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +that should get polled, with the events desired specified in the +.I poll_mask +argument. + +The default behavior is a single-shot poll request. When the specified event +has triggered, a completion CQE is posted and no more events will be generated +by the poll request. +.BR io_uring_prep_multishot (3) +behaves identically in terms of events, but it persist across notifications +and will repeatedly post notifications for the same registration. A CQE +posted from a multishot poll request will have +.B IORING_CQE_F_MORE +set in the CQE +.I flags +member, indicating that the application should expect more completions from +this request. If the multishot poll request gets terminated or experiences +an error, this flag will not be set in the CQE. If this happens, the application +should not expect further CQEs from the original request and must reissue a +new one if it still wishes to get notifications on this file descriptor. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation, which is a bitmask of the +events notified. See the +.BR poll (2) +man page for details. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR poll (2), +.BR epoll_ctl (3) diff --git a/man/io_uring_prep_poll_multishot.3 b/man/io_uring_prep_poll_multishot.3 new file mode 120000 index 0000000..ac8fb8f --- /dev/null +++ b/man/io_uring_prep_poll_multishot.3 @@ -0,0 +1 @@ +io_uring_prep_poll_add.3
\ No newline at end of file diff --git a/man/io_uring_prep_poll_remove.3 b/man/io_uring_prep_poll_remove.3 new file mode 100644 index 0000000..b6f4b26 --- /dev/null +++ b/man/io_uring_prep_poll_remove.3 @@ -0,0 +1,55 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_poll_remove 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_poll_remove \- prepare a poll deletion request +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_poll_remove(struct io_uring_sqe *" sqe "," +.BI " __u64 " user_data ");" +.BI " +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_poll_remove (3) +function prepares a poll removal request. The submission queue entry +.I sqe +is setup to remove a poll request identified by +.I user_data + +Works like +.BR io_uring_prep_cancel (3) +except only looks for poll requests. Apart from that, behavior is identical. +See that man page for specific details. + +.SH RETURN VALUE +None +.SH ERRORS +These are the errors that are reported in the CQE +.I res +field. On success, +.B 0 +is returned. +.TP +.B -ENOENT +The request identified by +.I user_data +could not be located. This could be because it completed before the cancelation +request was issued, or if an invalid identifier is used. +.TP +.B -EINVAL +One of the fields set in the SQE was invalid. +.TP +.B -EALREADY +The execution state of the request has progressed far enough that cancelation +is no longer possible. This should normally mean that it will complete shortly, +either successfully, or interrupted due to the cancelation. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_prep_cancel (3) diff --git a/man/io_uring_prep_poll_update.3 b/man/io_uring_prep_poll_update.3 new file mode 100644 index 0000000..11f6346 --- /dev/null +++ b/man/io_uring_prep_poll_update.3 @@ -0,0 +1,89 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_poll_update 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_poll_update \- update an existing poll request +.SH SYNOPSIS +.nf +.B #include <poll.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_poll_update(struct io_uring_sqe *" sqe "," +.BI " __u64 " old_user_data "," +.BI " __u64 " new_user_data "," +.BI " unsigned " poll_mask "," +.BI " unsigned " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_poll_update (3) +function prepares a poll update request. The submission queue entry +.I sqe +is setup to update a poll request identified by +.IR old_user_data , +replacing it with the +.I new_user_data +information. The +.I poll_mask +arguments contains the new mask to use for the poll request, and +.I flags +argument contains modifier flags telling io_uring what fields to update. + +The +.I flags +modifier flags is a bitmask and may contain and OR'ed mask of: +.TP +.B IORING_POLL_UPDATE_EVENTS +If set, the poll update request will replace the existing events being waited +for with the ones specified in the +.I poll_mask +argument to the function. +.TP +.B IORING_POLL_UPDATE_USER_DATA +If set, the poll update request will update the existing user_data of the +request with the value passed in as the +.I new_user_data +argument. +.TP +.B IORING_POLL_ADD_MULTI +If set, this will change the poll request from a singleshot to a multishot +request. This must be used along with +.B IORING_POLL_UPDATE_EVENTS +as the event field must be updated to enable multishot. + +.SH RETURN VALUE +None +.SH ERRORS +These are the errors that are reported in the CQE +.I res +field. On success, +.B 0 +is returned. +.TP +.B -ENOENT +The request identified by +.I user_data +could not be located. This could be because it completed before the cancelation +request was issued, or if an invalid identifier is used. +.TP +.B -EINVAL +One of the fields set in the SQE was invalid. +.TP +.B -EALREADY +The execution state of the request has progressed far enough that cancelation +is no longer possible. This should normally mean that it will complete shortly, +either successfully, or interrupted due to the cancelation. +.TP +.B -ECANCELED +.B IORING_POLL_UPDATE_EVENTS +was set and an error occurred re-arming the poll request with the new mask. +The original poll request is terminated if this happens, and that termination +CQE will contain the reason for the error re-arming. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_prep_poll_add (3), +.BR io_uring_prep_poll_multishot (3) diff --git a/man/io_uring_prep_provide_buffers.3 b/man/io_uring_prep_provide_buffers.3 new file mode 100644 index 0000000..f3dded9 --- /dev/null +++ b/man/io_uring_prep_provide_buffers.3 @@ -0,0 +1,131 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_provide_buffers 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_provide_buffers \- prepare a provide buffers request +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_provide_buffers(struct io_uring_sqe *" sqe "," +.BI " void *" addr "," +.BI " int " len "," +.BI " int " nr "," +.BI " int " bgid "," +.BI " int " bid ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_provide_buffers (3) +function prepares a request for providing the kernel with buffers. The +submission queue entry +.I sqe +is setup to consume +.I len +number of buffers starting at +.I addr +and identified by the buffer group ID of +.I bgid +and numbered sequentially starting at +.IR bid . + +This function sets up a request to provide buffers to the io_uring context +that can be used by read or receive operations. This is done by filling in +the SQE +.I buf_group +field and setting +.B IOSQE_BUFFER_SELECT +in the SQE +.I flags +member. If buffer selection is used for a request, no buffer should be provided +in the address field. Instead, the group ID is set to match one that was +previously provided to the kernel. The kernel will then select a buffer from +this group for the IO operation. On successful completion of the IO request, +the CQE +.I flags +field will have +.B IORING_CQE_F_BUFFER +set and the selected buffer ID will be indicated by the upper 16-bits of the +.I flags +field. + +Different buffer group IDs can be used by the application to have different +sizes or types of buffers available. Once a buffer has been consumed for an +operation, it is no longer known to io_uring. It must be re-provided if so +desired or freed by the application if no longer needed. + +The buffer IDs are internally tracked from +.I bid +and sequentially ascending from that value. If +.B 16 +buffers are provided and start with an initial +.I bid +of 0, then the buffer IDs will range from +.BR 0..15 . +The application must be aware of this to make sense of the buffer ID passed +back in the CQE. + +Not all requests support buffer selection, as it only really makes sense for +requests that receive data from the kernel rather than write or provide data. +Currently, this mode of operation is supported for any file read or socket +receive request. Attempting to use +.B IOSQE_BUFFER_SELECT +with a command that doesn't support it will result in a CQE +.I res +error of +.BR -EINVAL . +Buffer selection will work with operations that take a +.B struct iovec +as its data destination, but only if 1 iovec is provided. +. +.SH RETURN VALUE +None +.SH ERRORS +These are the errors that are reported in the CQE +.I res +field. On success, +.I res +will contain the number of successfully provided buffers. On error, +the following errors can occur. +.TP +.B -ENOMEM +The kernel was unable to allocate memory for the request. +.TP +.B -EINVAL +One of the fields set in the SQE was invalid. +.TP +.B -E2BIG +The number of buffers provided was too big, or the +.I bid +was too big. A max value of +.B USHRT_MAX +buffers can be specified. +.TP +.B -EFAULT +Some of the user memory given was invalid for the application. +.TP +.B -EBADF +On of the descriptors located in +.I fds +didn't refer to a valid file descriptor, or one of the file descriptors in +the array referred to an io_uring instance. +.TP +.B -EOVERFLOW +The product of +.I len +and +.I nr +exceed the valid amount or overflowed, or the sum of +.I addr +and the length of buffers overflowed. +.TP +.B -EBUSY +Attempt to update a slot that is already used. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_register (2), +.BR io_uring_prep_remove_buffers (3) diff --git a/man/io_uring_prep_read.3 b/man/io_uring_prep_read.3 new file mode 100644 index 0000000..faec35f --- /dev/null +++ b/man/io_uring_prep_read.3 @@ -0,0 +1,69 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_read 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_prep_read \- prepare I/O read request +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_read(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " void *" buf "," +.BI " unsigned " nbytes "," +.BI " __u64 " offset ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_read (3) +prepares an IO read request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +to start reading +.I nbytes +into the buffer +.I buf +at the specified +.IR offset . + +On files that support seeking, if the offset is set to +.BR -1 , +the read operation commences at the file offset, and the file offset is +incremented by the number of bytes read. See +.BR read (2) +for more details. Note that for an async API, reading and updating the +current file offset may result in unpredictable behavior, unless access +to the file is serialized. It is not encouraged to use this feature, if it's +possible to provide the desired IO offset from the application or library. + +On files that are not capable of seeking, the offset is ignored. + +After the read has been prepared it can be submitted with one of the submit +functions. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_prep_readv (3), +.BR io_uring_prep_readv2 (3), +.BR io_uring_submit (3) diff --git a/man/io_uring_prep_read_fixed.3 b/man/io_uring_prep_read_fixed.3 new file mode 100644 index 0000000..d3726f2 --- /dev/null +++ b/man/io_uring_prep_read_fixed.3 @@ -0,0 +1,72 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_read 3 "February 13, 2022" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_prep_read_fixed \- prepare I/O read request with registered buffer +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_read_fixed(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " void *" buf "," +.BI " unsigned " nbytes "," +.BI " __u64 " offset "," +.BI " int " buf_index ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_read_fixed (3) +prepares an IO read request with a previously registered IO buffer. The +submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +to start reading +.I nbytes +into the buffer +.I buf +at the specified +.IR offset , +and with the buffer matching the registered index of +.IR buf_index . + +This works just like +.BR io_uring_prep_read (3) +except it requires the use of buffers that have been registered with +.BR io_uring_register_buffers (3). +The +.I buf +and +.I nbytes +arguments must fall within a region specificed by +.I buf_index +in the previously registered buffer. The buffer need not be aligned with +the start of the registered buffer. + +After the read has been prepared it can be submitted with one of the submit +functions. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_prep_read (3), +.BR io_uring_register_buffers (3) diff --git a/man/io_uring_prep_readv.3 b/man/io_uring_prep_readv.3 new file mode 100644 index 0000000..ea7afd5 --- /dev/null +++ b/man/io_uring_prep_readv.3 @@ -0,0 +1,85 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_readv 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_prep_readv \- prepare vector I/O read request +.SH SYNOPSIS +.nf +.B #include <sys/uio.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_readv(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " const struct iovec *" iovecs "," +.BI " unsigned " nr_vecs "," +.BI " __u64 " offset ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_readv (3) +prepares a vectored IO read request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +to start reading +.I nr_vecs +into the +.I iovecs +array at the specified +.IR offset . + +On files that support seeking, if the offset is set to +.BR -1 , +the read operation commences at the file offset, and the file offset is +incremented by the number of bytes read. See +.BR read (2) +for more details. Note that for an async API, reading and updating the +current file offset may result in unpredictable behavior, unless access +to the file is serialized. It is not encouraged to use this feature, if it's +possible to provide the desired IO offset from the application or library. + +On files that are not capable of seeking, the offset is ignored. + +After the write has been prepared it can be submitted with one of the submit +functions. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +Unless an application explicitly needs to pass in more than iovec, it is more +efficient to use +.BR io_uring_prep_read (3) +rather than this function, as no state has to be maintained for a +non-vectored IO request. +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_prep_read (3), +.BR io_uring_prep_readv2 (3), +.BR io_uring_submit (3) diff --git a/man/io_uring_prep_readv2.3 b/man/io_uring_prep_readv2.3 new file mode 100644 index 0000000..171a699 --- /dev/null +++ b/man/io_uring_prep_readv2.3 @@ -0,0 +1,111 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_readv2 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_prep_readv2 \- prepare vector I/O read request with flags +.SH SYNOPSIS +.nf +.B #include <sys/uio.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_readv2(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " const struct iovec *" iovecs "," +.BI " unsigned " nr_vecs "," +.BI " __u64 " offset "," +.BI " int " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_readv2 (3) +prepares a vectored IO read request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +to start reading +.I nr_vecs +into the +.I iovecs +array at the specified +.IR offset . +The behavior of the function can be controlled with the +.I flags +parameter. + +Supported values for +.I flags +are: +.TP +.B RWF_HIPRI +High priority request, poll if possible +.TP +.B RWF_DSYNC +per-IO O_DSYNC +.TP +.B RWF_SYNC +per-IO O_SYNC +.TP +.B RWF_NOWAIT +per-IO, return +.B -EAGAIN +if operation would block +.TP +.B RWF_APPEND +per-IO O_APPEND + +.P +On files that support seeking, if the offset is set to +.BR -1 , +the read operation commences at the file offset, and the file offset is +incremented by the number of bytes read. See +.BR read (2) +for more details. Note that for an async API, reading and updating the +current file offset may result in unpredictable behavior, unless access +to the file is serialized. It is not encouraged to use this feature, if it's +possible to provide the desired IO offset from the application or library. + +On files that are not capable of seeking, the offset is ignored. + +After the write has been prepared, it can be submitted with one of the submit +functions. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +Unless an application explicitly needs to pass in more than iovec, it is more +efficient to use +.BR io_uring_prep_read (3) +rather than this function, as no state has to be maintained for a +non-vectored IO request. +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_prep_read (3), +.BR io_uring_prep_readv (3), +.BR io_uring_submit (3) diff --git a/man/io_uring_prep_recv.3 b/man/io_uring_prep_recv.3 new file mode 100644 index 0000000..993e331 --- /dev/null +++ b/man/io_uring_prep_recv.3 @@ -0,0 +1,83 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_recv 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_recv \- prepare a recv request +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_recv(struct io_uring_sqe *" sqe "," +.BI " int " sockfd "," +.BI " void *" buf "," +.BI " size_t " len "," +.BI " int " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_recv (3) +function prepares a recv request. The submission +queue entry +.I sqe +is setup to use the file descriptor +.I sockfd +to start receiving the data into the buffer destination +.I buf +of size +.I size +and with modifier flags +.IR flags . + +This function prepares an async +.BR recv (2) +request. See that man page for details on the arguments specified to this +prep helper. + +After calling this function, additional io_uring internal modifier flags +may be set in the SQE +.I off +field. The following flags are supported: +.TP +.B IORING_RECVSEND_POLL_FIRST +If set, io_uring will assume the socket is currently empty and attempting to +receive data will be unsuccessful. For this case, io_uring will arm internal +poll and trigger a receive of the data when the socket has data to be read. +This initial receive attempt can be wasteful for the case where the socket +is expected to be empty, setting this flag will bypass the initial receive +attempt and go straight to arming poll. If poll does indicate that data is +ready to be received, the operation will proceed. + +Can be used with the CQE +.B IORING_CQE_F_SOCK_NONEMPTY +flag, which io_uring will set on CQEs after a +.BR recv (2) +or +.BR recvmsg (2) +operation. If set, the socket still had data to be read after the operation +completed. Both these flags are available since 5.19. +.P + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR recv (2) diff --git a/man/io_uring_prep_recvmsg.3 b/man/io_uring_prep_recvmsg.3 new file mode 100644 index 0000000..8c49411 --- /dev/null +++ b/man/io_uring_prep_recvmsg.3 @@ -0,0 +1,94 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_recvmsg 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_recvmsg \- prepare a recvmsg request +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <sys/socket.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_recvmsg(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " struct msghdr *" msg "," +.BI " unsigned " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_recvmsg (3) +function prepares a recvmsg request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +to start receiving the data indicated by +.I msg +with the +.BR recvmsg (2) +defined flags in the +.I flags +argument. + +This function prepares an async +.BR recvmsg (2) +request. See that man page for details on the arguments specified to this +prep helper. + +After calling this function, additional io_uring internal modifier flags +may be set in the SQE +.I off +field. The following flags are supported: +.TP +.B IORING_RECVSEND_POLL_FIRST +If set, io_uring will assume the socket is currently empty and attempting to +receive data will be unsuccessful. For this case, io_uring will arm internal +poll and trigger a receive of the data when the socket has data to be read. +This initial receive attempt can be wasteful for the case where the socket +is expected to be empty, setting this flag will bypass the initial receive +attempt and go straight to arming poll. If poll does indicate that data is +ready to be received, the operation will proceed. + +Can be used with the CQE +.B IORING_CQE_F_SOCK_NONEMPTY +flag, which io_uring will set on CQEs after a +.BR recv (2) +or +.BR recvmsg (2) +operation. If set, the socket still had data to be read after the operation +completed. Both these flags are available since 5.19. +.P + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR recvmsg (2) diff --git a/man/io_uring_prep_remove_buffers.3 b/man/io_uring_prep_remove_buffers.3 new file mode 100644 index 0000000..cf4f226 --- /dev/null +++ b/man/io_uring_prep_remove_buffers.3 @@ -0,0 +1,52 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_remove_buffers 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_remove_buffers \- prepare a remove buffers request +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_remove_buffers(struct io_uring_sqe *" sqe "," +.BI " int " nr "," +.BI " int " bgid ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_remove_buffers (3) +function prepares a request for removing previously supplied buffers. The +submission queue entry +.I sqe +is setup to remove +.I nr +number of buffers from the buffer group ID indicated by +.IR bgid . + +.SH RETURN VALUE +None +.SH ERRORS +These are the errors that are reported in the CQE +.I res +field. On success, +.I res +will contain the number of successfully removed buffers. On error, +the following errors can occur. +.TP +.B -ENOMEM +The kernel was unable to allocate memory for the request. +.TP +.B -EINVAL +One of the fields set in the SQE was invalid. +.TP +.B -ENOENT +No buffers exist at the specified +.I bgid +buffer group ID. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_register (2), +.BR io_uring_prep_provide_buffers (3) diff --git a/man/io_uring_prep_rename.3 b/man/io_uring_prep_rename.3 new file mode 120000 index 0000000..785b55e --- /dev/null +++ b/man/io_uring_prep_rename.3 @@ -0,0 +1 @@ +io_uring_prep_renameat.3
\ No newline at end of file diff --git a/man/io_uring_prep_renameat.3 b/man/io_uring_prep_renameat.3 new file mode 100644 index 0000000..1fc9e01 --- /dev/null +++ b/man/io_uring_prep_renameat.3 @@ -0,0 +1,96 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_renameat 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_renameat \- prepare a renameat request +.SH SYNOPSIS +.nf +.B #include <fcntl.h> +.B #include <stdio.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_renameat(struct io_uring_sqe *" sqe "," +.BI " int " olddirfd "," +.BI " const char *" oldpath "," +.BI " int " newdirfd "," +.BI " const char *" newpath "," +.BI " int " flags ");" +.PP +.BI "void io_uring_prep_rename(struct io_uring_sqe *" sqe "," +.BI " const char *" oldpath "," +.BI " const char *" newpath "," +.BI " int " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_renameat (3) +function prepares a renameat request. The submission queue entry +.I sqe +is setup to use the old directory file descriptor pointed to by +.I olddirfd +and old path pointed to by +.I oldpath +with the new directory file descriptor pointed to by +.I newdirfd +and the new path pointed to by +.I newpath +and using the specified flags in +.IR flags . + +The +.BR io_uring_prep_rename (3) +function prepares a rename request. The submission queue entry +.I sqe +is setup to use the old path pointed to by +.I oldpath +with the new path pointed to by +.IR newpath , +both relative to the current working directory and using the specified flags in +.IR flags . + +These functions prepare an async +.BR renameat2 (2) +or +.BR rename (2) +request. If +.I flags +is zero, then this call is similar to the +.BR renameat (2) +system call. See those man pages for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR renameat (2), +.BR renameat2 (2), +.BR rename (2) diff --git a/man/io_uring_prep_send.3 b/man/io_uring_prep_send.3 new file mode 100644 index 0000000..10c86ba --- /dev/null +++ b/man/io_uring_prep_send.3 @@ -0,0 +1,57 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_send 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_send \- prepare a send request +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_send(struct io_uring_sqe *" sqe "," +.BI " int " sockfd "," +.BI " const void *" buf "," +.BI " size_t " len "," +.BI " int " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_send (3) +function prepares a send request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I sockfd +to start sending the data from +.I buf +of size +.I size +and with modifier flags +.IR flags . + +This function prepares an async +.BR send (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR send (2) diff --git a/man/io_uring_prep_sendmsg.3 b/man/io_uring_prep_sendmsg.3 new file mode 100644 index 0000000..bc81d91 --- /dev/null +++ b/man/io_uring_prep_sendmsg.3 @@ -0,0 +1,69 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_sendmsg 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_sendmsg \- prepare a sendmsg request +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <sys/socket.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_sendmsg(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " const struct msghdr *" msg "," +.BI " unsigned " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_sendmsg (3) +function prepares a sendmsg request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +to start sending the data indicated by +.I msg +with the +.BR sendmsg (2) +defined flags in the +.I flags +argument. + +This function prepares an async +.BR sendmsg (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR sendmsg (2) diff --git a/man/io_uring_prep_shutdown.3 b/man/io_uring_prep_shutdown.3 new file mode 100644 index 0000000..9125e95 --- /dev/null +++ b/man/io_uring_prep_shutdown.3 @@ -0,0 +1,53 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_shutdown 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_shutdown \- prepare a shutdown request +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_shutdown(struct io_uring_sqe *" sqe "," +.BI " int " sockfd "," +.BI " int " how ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_shutdown (3) +function prepares a shutdown request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I sockfd +that should be shutdown with the +.I how +argument. + +This function prepares an async +.BR shutdown (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR shutdown (2) diff --git a/man/io_uring_prep_socket.3 b/man/io_uring_prep_socket.3 new file mode 100644 index 0000000..473f225 --- /dev/null +++ b/man/io_uring_prep_socket.3 @@ -0,0 +1,97 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_socket 3 "May 27, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_socket \- prepare a socket creation request +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_socket(struct io_uring_sqe *" sqe "," +.BI " int " domain "," +.BI " int " type "," +.BI " int " protocol "," +.BI " unsigned int " flags ");" +.PP +.BI "void io_uring_prep_socket_direct(struct io_uring_sqe *" sqe "," +.BI " int " domain "," +.BI " int " type "," +.BI " int " protocol "," +.BI " unsigned int " file_index "," +.BI " unsigned int " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_socket (3) +function prepares a socket creation request. The submission queue entry +.I sqe +is setup to use the communication domain defined by +.I domain +and use the communication type defined by +.I type +and the protocol set by +.IR protocol . +The +.I flags +argument are currently unused. + +The +.BR io_uring_prep_socket_direct (3) +works just like +.BR io_uring_prep_socket (3), +except it maps the socket to a direct descriptor rather than return a normal +file descriptor. The +.I file_index +argument should be set to the slot that should be used for this socket, or +.B IORING_FILE_INDEX_ALLOC +if io_uring should allocate a free one. + +If the direct variant is used, the application must first have registered +a file table using +.BR io_uring_register_files (3) +of the appropriate size. Once registered, a direct socket request may use any +entry in that table, as long as it is within the size of the registered table. +If a specified entry already contains a file, the file will first be removed +from the table and closed. It's consistent with the behavior of updating an +existing file with +.BR io_uring_register_files_update (3). + +For a direct descriptor socket request, the +.I file_index +argument can be set to +.BR IORING_FILE_INDEX_ALLOC , +In this case a free entry in io_uring file table will +be used automatically and the file index will be returned as CQE +.IR res . +.B -ENFILE +is otherwise returned if there is no free entries in the io_uring file table. + +These functions prepare an async +.BR socket (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR socket (2) diff --git a/man/io_uring_prep_socket_direct.3 b/man/io_uring_prep_socket_direct.3 new file mode 120000 index 0000000..15d7b7f --- /dev/null +++ b/man/io_uring_prep_socket_direct.3 @@ -0,0 +1 @@ +io_uring_prep_socket.3
\ No newline at end of file diff --git a/man/io_uring_prep_splice.3 b/man/io_uring_prep_splice.3 new file mode 100644 index 0000000..cb82ad0 --- /dev/null +++ b/man/io_uring_prep_splice.3 @@ -0,0 +1,80 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_splice 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_splice \- prepare an splice request +.SH SYNOPSIS +.nf +.B #include <fcntl.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_splice(struct io_uring_sqe *" sqe "," +.BI " int " fd_in "," +.BI " int64_t " off_in "," +.BI " int " fd_out "," +.BI " int64_t " off_out "," +.BI " unsigned int " nbytes "," +.BI " unsigned int " splice_flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_splice (3) +function prepares a splice request. The submission queue entry +.I sqe +is setup to use as input the file descriptor +.I fd_in +at offset +.IR off_in , +splicing data to the file descriptor at +.I fd_out +and at offset +.IR off_out . +.I nbytes +bytes of data should be spliced between the two descriptors. +.I splice_flags +are modifier flags for the operation. See +.BR splice (2) +for the generic splice flags. + +If the +.I fd_out +descriptor, +.B IOSQE_FIXED_FILE +can be set in the SQE to indicate that. For the input file, the io_uring +specific +.B SPLICE_F_FD_IN_FIXED +can be set in +.I splice_flags +and +.I fd_in +given as a registered file descriptor offset. + +This function prepares an async +.BR splice (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_register (2), +.BR splice (2) diff --git a/man/io_uring_prep_statx.3 b/man/io_uring_prep_statx.3 new file mode 100644 index 0000000..d9d983a --- /dev/null +++ b/man/io_uring_prep_statx.3 @@ -0,0 +1,74 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_statx 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_statx \- prepare a statx request +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <sys/stat.h> +.B #include <unistd.h> +.B #include <fcntl.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_statx(struct io_uring_sqe *" sqe "," +.BI " int " dirfd "," +.BI " const char *" path "," +.BI " int " flags "," +.BI " unsigned " mask "," +.BI " struct statx *" statxbuf ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_statx (3) +function prepares a statx request. The submission queue entry +.I sqe +is setup to use the directory file descriptor pointed to by +.I dirfd +to start a statx operation on the path identified by +.I path +and using the flags given in +.I flags +for the fields specified by +.I mask +and into the buffer located at +.IR statxbuf . + +This function prepares an async +.BR statx (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR statx (2) diff --git a/man/io_uring_prep_symlink.3 b/man/io_uring_prep_symlink.3 new file mode 120000 index 0000000..ae6f41a --- /dev/null +++ b/man/io_uring_prep_symlink.3 @@ -0,0 +1 @@ +io_uring_prep_symlinkat.3
\ No newline at end of file diff --git a/man/io_uring_prep_symlinkat.3 b/man/io_uring_prep_symlinkat.3 new file mode 100644 index 0000000..0fa7056 --- /dev/null +++ b/man/io_uring_prep_symlinkat.3 @@ -0,0 +1,85 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_symlinkat 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_symlinkat \- prepare a symlinkat request +.SH SYNOPSIS +.nf +.B #include <fcntl.h> +.B #include <unistd.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_symlinkat(struct io_uring_sqe *" sqe "," +.BI " const char *" target "," +.BI " int " newdirfd "," +.BI " const char *" linkpath ");" +.PP +.BI "void io_uring_prep_symlink(struct io_uring_sqe *" sqe "," +.BI " const char *" target "," +.BI " const char *" linkpath ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_symlinkat (3) +function prepares a symlinkat request. The submission queue entry +.I sqe +is setup to symlink the target path pointed to by +.I target +to the new destination indicated by +.I newdirfd +and +.IR linkpath . + +The +.BR io_uring_prep_symlink (3) +function prepares a symlink request. The submission queue entry +.I sqe +is setup to symlink the target path pointed to by +.I target +to the new destination indicated by +.I linkpath +relative to the the current working directory. This function prepares an async +.BR symlink (2) +request. See that man page for details. + +These functions prepare an async +.BR symlinkat (2) +or +.BR symlink (2) +request. See those man pages for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR symlinkat (2), +.BR symlink (2) diff --git a/man/io_uring_prep_sync_file_range.3 b/man/io_uring_prep_sync_file_range.3 new file mode 100644 index 0000000..830e411 --- /dev/null +++ b/man/io_uring_prep_sync_file_range.3 @@ -0,0 +1,59 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_sync_file_range 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_sync_file_range \- prepare a sync_file_range request +.SH SYNOPSIS +.nf +.B #include <fcntl.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_sync_file_range(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " unsigned " len "," +.BI " __u64 " offset "," +.BI " int " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_sync_file_range (3) +function prepares a sync_file_range request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +that should get +.I len +bytes synced started at offset +.I offset +and with modifier flags in the +.I flags +argument. + +This function prepares an async +.BR sync_file_range (2) +request. See that man page for details on the arguments. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR sync_file_range (2) diff --git a/man/io_uring_prep_tee.3 b/man/io_uring_prep_tee.3 new file mode 100644 index 0000000..44aaaf6 --- /dev/null +++ b/man/io_uring_prep_tee.3 @@ -0,0 +1,74 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_tee 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_tee \- prepare a tee request +.SH SYNOPSIS +.nf +.B #include <fcntl.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_tee(struct io_uring_sqe *" sqe "," +.BI " int " fd_in "," +.BI " int " fd_out "," +.BI " unsigned int " nbytes "," +.BI " unsigned int " splice_flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_tee (3) +function prepares a tee request. The submission queue entry +.I sqe +is setup to use as input the file descriptor +.I fd_in +and as output the file descriptor +.I fd_out +duplicating +.I nbytes +bytes worth of data. +.I splice_flags +are modifier flags for the operation. See +.BR tee (2) +for the generic splice flags. + +If the +.I fd_out +descriptor, +.B IOSQE_FIXED_FILE +can be set in the SQE to indicate that. For the input file, the io_uring +specific +.B SPLICE_F_FD_IN_FIXED +can be set and +.I fd_in +given as a registered file descriptor offset. + +This function prepares an async +.BR tee (2) +request. See that man page for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_register (2), +.BR splice (2), +.BR tee (2) diff --git a/man/io_uring_prep_timeout.3 b/man/io_uring_prep_timeout.3 new file mode 100644 index 0000000..bfb8791 --- /dev/null +++ b/man/io_uring_prep_timeout.3 @@ -0,0 +1,95 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_poll_timeout 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_timeoute \- prepare a timeout request +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_timeout(struct io_uring_sqe *" sqe "," +.BI " struct __kernel_timespec *" ts "," +.BI " unsigned " count "," +.BI " unsigned " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_timeout (3) +function prepares a timeout request. The submission queue entry +.I sqe +is setup to arm a timeout specified by +.I ts +and with a timeout count of +.I count +completion entries. The +.I flags +argument holds modifier flags for the request. + +This request type can be used as a timeout waking anyone sleeping +for events on the CQ ring. The +.I flags +argument may contain: +.TP +.B IORING_TIMEOUT_ABS +The value specified in +.I ts +is an absolute value rather than a relative one. +.TP +.B IORING_TIMEOUT_BOOTTIME +The boottime clock source should be used. +.TP +.B IORING_TIMEOUT_REALTIME +The realtime clock source should be used. +.TP +.B IORING_TIMEOUT_ETIME_SUCCESS +Consider an expired timeout a success in terms of the posted completion. +Normally a timeout that triggers would return in a +.B -ETIME +CQE +.I res +value. +.PP +The timeout completion event will trigger if either the specified timeout +has occurred, or the specified number of events to wait for have been posted +to the CQ ring. + +.SH RETURN VALUE +None +.SH ERRORS +These are the errors that are reported in the CQE +.I res +field. On success, +.B 0 +is returned. +.TP +.B -ETIME +The specified timeout occurred and triggered the completion event. +.TP +.B -EINVAL +One of the fields set in the SQE was invalid. For example, two clocksources +where given, or the specified timeout seconds or nanoseconds where < 0. +.TP +.B -EFAULT +io_uring was unable to access the data specified by +.IR ts . +.TP +.B -ECANCELED +The timeout was canceled by a removal request. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_prep_timeout_remove (3), +.BR io_uring_prep_timeout_update (3) diff --git a/man/io_uring_prep_timeout_remove.3 b/man/io_uring_prep_timeout_remove.3 new file mode 120000 index 0000000..5aebd36 --- /dev/null +++ b/man/io_uring_prep_timeout_remove.3 @@ -0,0 +1 @@ +io_uring_prep_timeout_update.3
\ No newline at end of file diff --git a/man/io_uring_prep_timeout_update.3 b/man/io_uring_prep_timeout_update.3 new file mode 100644 index 0000000..cb9ed12 --- /dev/null +++ b/man/io_uring_prep_timeout_update.3 @@ -0,0 +1,98 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_poll_timeout_update 3 "March 12, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_timeoute_update \- prepare a request to update an existing timeout +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_timeout_update(struct io_uring_sqe *" sqe "," +.BI " struct __kernel_timespec *" ts "," +.BI " __u64 " user_data "," +.BI " unsigned " flags ");" +.PP +.BI "void io_uring_prep_timeout_remove(struct io_uring_sqe *" sqe "," +.BI " __u64 " user_data "," +.BI " unsigned " flags ");" +.fi +.SH DESCRIPTION +.PP +These functions modify or cancel an existing timeout request. The submission +queue entry +.I sqe +is setup to arm a timeout update or removal specified by +.I user_data +and with modifier flags given by +.IR flags . +Additionally, the update request includes a +.I ts +structure, which contains new timeout information. + +For an update request, the +.I flags +member may contain a bitmask of the following values: +.TP +.B IORING_TIMEOUT_ABS +The value specified in +.I ts +is an absolute value rather than a relative one. +.TP +.B IORING_TIMEOUT_BOOTTIME +The boottime clock source should be used. +.TP +.B IORING_TIMEOUT_REALTIME +The realtime clock source should be used. +.TP +.B IORING_TIMEOUT_ETIME_SUCCESS +Consider an expired timeout a success in terms of the posted completion. +Normally a timeout that triggers would return in a +.B -ETIME +CQE +.I res +value. +.PP + +.SH RETURN VALUE +None +.SH ERRORS +These are the errors that are reported in the CQE +.I res +field. On success, +.B 0 +is returned. +.TP +.B -ENOENT +The timeout identified by +.I user_data +could not be found. It may be invalid, or triggered before the update or +removal request was processed. +.TP +.B -EALREADY +The timeout identified by +.I user_data +is already firing and cannot be canceled. +.TP +.B -EINVAL +One of the fields set in the SQE was invalid. For example, two clocksources +where given, or the specified timeout seconds or nanoseconds where < 0. +.TP +.B -EFAULT +io_uring was unable to access the data specified by +.IR ts . +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_prep_timeout (3) diff --git a/man/io_uring_prep_unlink.3 b/man/io_uring_prep_unlink.3 new file mode 120000 index 0000000..80f86d2 --- /dev/null +++ b/man/io_uring_prep_unlink.3 @@ -0,0 +1 @@ +io_uring_prep_unlinkat.3
\ No newline at end of file diff --git a/man/io_uring_prep_unlinkat.3 b/man/io_uring_prep_unlinkat.3 new file mode 100644 index 0000000..ba2633c --- /dev/null +++ b/man/io_uring_prep_unlinkat.3 @@ -0,0 +1,82 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_unlinkat 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_prep_unlinkat \- prepare an unlinkat request +.SH SYNOPSIS +.nf +.B #include <fcntl.h> +.B #include <unistd.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_unlinkat(struct io_uring_sqe *" sqe "," +.BI " int " dirfd "," +.BI " const char *" path "," +.BI " int " flags ");" +.PP +.BI "void io_uring_prep_unlink(struct io_uring_sqe *" sqe "," +.BI " const char *" path "," +.BI " int " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_unlinkat (3) +function prepares an unlinkat request. The submission queue entry +.I sqe +is setup to use the directory file descriptor pointed to by +.I dirfd +to start an unlinkat operation on the path identified by +.I path +and using the flags given in +.IR flags . + +The +.BR io_uring_prep_unlink (3) +function prepares an unlink request. The submission queue entry +.I sqe +is setup to start an unlinkat operation on the path identified by +.I path +relative to the current working directory and using the flags given in +.IR flags . + +These functions prepare an async +.BR unlinkat (2) +or +.BR unlink (2) +request. See those man pages for details. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR unlinkat (2), +.BR unlink (2) diff --git a/man/io_uring_prep_write.3 b/man/io_uring_prep_write.3 new file mode 100644 index 0000000..791a5f1 --- /dev/null +++ b/man/io_uring_prep_write.3 @@ -0,0 +1,67 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_write 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_prep_write \- prepare I/O write request +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_write(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " const void *" buf "," +.BI " unsigned " nbytes "," +.BI " __u64 " offset ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_write (3) +prepares an IO write request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +to start writing +.I nbytes +from the buffer +.I buf +at the specified +.IR offset . + +On files that support seeking, if the offset is set to +.BR -1 , +the write operation commences at the file offset, and the file offset is +incremented by the number of bytes written. See +.BR write (2) +for more details. Note that for an async API, reading and updating the +current file offset may result in unpredictable behavior, unless access +to the file is serialized. It is not encouraged to use this feature if it's +possible to provide the desired IO offset from the application or library. + +On files that are not capable of seeking, the offset is ignored. + +After the write has been prepared, it can be submitted with one of the submit +functions. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3) diff --git a/man/io_uring_prep_write_fixed.3 b/man/io_uring_prep_write_fixed.3 new file mode 100644 index 0000000..5dab4a6 --- /dev/null +++ b/man/io_uring_prep_write_fixed.3 @@ -0,0 +1,72 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_write 3 "February 13, 2022" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_prep_write_fixed \- prepare I/O write request with registered buffer +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_write_fixed(struct io_uring_sqe *" sqe "," +.BI " int " fd ", +.BI " const void *" buf "," +.BI " unsigned " nbytes "," +.BI " __u64 " offset "," +.BI " int " buf_index ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_write_fixed (3) +prepares an IO write request with a previously registered IO buffer. The +submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +to start writing +.I nbytes +from the buffer +.I buf +at the specified +.I offset +and with the buffer matching the registered index of +.IR buf_index . + +This works just like +.BR io_uring_prep_write (3) +except it requires the use of buffers that have been registered with +.BR io_uring_register_buffers (3). +The +.I buf +and +.I nbytes +arguments must fall within a region specificed by +.I buf_index +in the previously registered buffer. The buffer need not be aligned with +the start of the registered buffer. + +After the read has been prepared it can be submitted with one of the submit +functions. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH SEE ALSO +.BR io_uring_prep_write (3), +.BR io_uring_register_buffers (3) diff --git a/man/io_uring_prep_writev.3 b/man/io_uring_prep_writev.3 new file mode 100644 index 0000000..9fb83d9 --- /dev/null +++ b/man/io_uring_prep_writev.3 @@ -0,0 +1,85 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_writev 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_prep_writev \- prepare vector I/O write request +.SH SYNOPSIS +.nf +.B #include <sys/uio.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_writev(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " const struct iovec *" iovecs "," +.BI " unsigned " nr_vecs "," +.BI " __u64 " offset ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_writev (3) +prepares a vectored IO write request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +to start writing +.I nr_vecs +from the +.I iovecs +array at the specified +.IR offset . + +On files that support seeking, if the offset is set to +.BR -1 , +the write operation commences at the file offset, and the file offset is +incremented by the number of bytes written. See +.BR write (2) +for more details. Note that for an async API, reading and updating the +current file offset may result in unpredictable behavior, unless access +to the file is serialized. It is not encouraged to use this feature if it's +possible to provide the desired IO offset from the application or library. + +On files that are not capable of seeking, the offset is ignored. + +After the write has been prepared it can be submitted with one of the submit +functions. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +Unless an application explicitly needs to pass in more than iovec, it is more +efficient to use +.BR io_uring_prep_write (3) +rather than this function, as no state has to be maintained for a +non-vectored IO request. +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_prep_write (3), +.BR io_uring_prep_writev2 (3), +.BR io_uring_submit (3) diff --git a/man/io_uring_prep_writev2.3 b/man/io_uring_prep_writev2.3 new file mode 100644 index 0000000..5093596 --- /dev/null +++ b/man/io_uring_prep_writev2.3 @@ -0,0 +1,111 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_prep_writev2 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_prep_writev2 \- prepare vector I/O write request with flags +.SH SYNOPSIS +.nf +.B #include <sys/uio.h> +.B #include <liburing.h> +.PP +.BI "void io_uring_prep_writev2(struct io_uring_sqe *" sqe "," +.BI " int " fd "," +.BI " const struct iovec *" iovecs "," +.BI " unsigned " nr_vecs "," +.BI " __u64 " offset "," +.BI " int " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_writev2 (3) +prepares a vectored IO write request. The submission queue entry +.I sqe +is setup to use the file descriptor +.I fd +to start writing +.I nr_vecs +from the +.I iovecs +array at the specified +.IR offset . +The behavior of the function can be controlled with the +.I flags +parameter. + +Supported values for +.I flags +are: +.TP +.B RWF_HIPRI +High priority request, poll if possible +.TP +.B RWF_DSYNC +per-IO O_DSYNC +.TP +.B RWF_SYNC +per-IO O_SYNC +.TP +.B RWF_NOWAIT +per-IO, return +.B -EAGAIN +if operation would block +.TP +.B RWF_APPEND +per-IO O_APPEND + +.P +On files that support seeking, if the offset is set to +.BR -1 , +the write operation commences at the file offset, and the file offset is +incremented by the number of bytes written. See +.BR write (2) +for more details. Note that for an async API, reading and updating the +current file offset may result in unpredictable behavior, unless access +to the file is serialized. It is not encouraged to use this feature if it's +possible to provide the desired IO offset from the application or library. + +On files that are not capable of seeking, the offset is ignored. + +After the write has been prepared, it can be submitted with one of the submit +functions. + +.SH RETURN VALUE +None +.SH ERRORS +The CQE +.I res +field will contain the result of the operation. See the related man page for +details on possible values. Note that where synchronous system calls will return +.B -1 +on failure and set +.I errno +to the actual error value, io_uring never uses +.IR errno . +Instead it returns the negated +.I errno +directly in the CQE +.I res +field. +.SH NOTES +Unless an application explicitly needs to pass in more than iovec, it is more +efficient to use +.BR io_uring_prep_write (3) +rather than this function, as no state has to be maintained for a +non-vectored IO request. +As with any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_prep_write (3), +.BR io_uring_prep_writev (3), +.BR io_uring_submit (3) diff --git a/man/io_uring_queue_exit.3 b/man/io_uring_queue_exit.3 index 294b5f3..00f8ae9 100644 --- a/man/io_uring_queue_exit.3 +++ b/man/io_uring_queue_exit.3 @@ -5,14 +5,13 @@ .\" .TH io_uring_queue_exit 3 "July 10, 2020" "liburing-0.7" "liburing Manual" .SH NAME -io_uring_queue_exit - tear down io_uring submission and completion queues +io_uring_queue_exit \- tear down io_uring submission and completion queues .SH SYNOPSIS .nf -.BR "#include <liburing.h>" +.B #include <liburing.h> .PP -.BI "void io_uring_queue_exit(struct io_uring * ring );" +.BI "void io_uring_queue_exit(struct io_uring *" ring ");" .fi -.PP .SH DESCRIPTION .PP .BR io_uring_queue_exit (3) diff --git a/man/io_uring_queue_init.3 b/man/io_uring_queue_init.3 index 1980fa4..086b70f 100644 --- a/man/io_uring_queue_init.3 +++ b/man/io_uring_queue_init.3 @@ -5,40 +5,85 @@ .\" .TH io_uring_queue_init 3 "July 10, 2020" "liburing-0.7" "liburing Manual" .SH NAME -io_uring_queue_init - setup io_uring submission and completion queues +io_uring_queue_init \- setup io_uring submission and completion queues .SH SYNOPSIS .nf -.BR "#include <liburing.h>" +.B #include <liburing.h> .PP -.BI "int io_uring_queue_init(unsigned " entries ", struct io_uring *" ring , -.BI " unsigned " flags ); -.fi +.BI "int io_uring_queue_init(unsigned " entries "," +.BI " struct io_uring *" ring "," +.BI " unsigned " flags ");" .PP +.BI "int io_uring_queue_init_params(unsigned " entries "," +.BI " struct io_uring *" ring "," +.BI " struct io_uring_params *" params ");" +.fi .SH DESCRIPTION .PP -The io_uring_queue_init() function executes the io_uring_setup syscall to -initialize the submission and completion queues in the kernel with at least +The +.BR io_uring_queue_init (3) +function executes the +.BR io_uring_setup (2) +system call to initialize the submission and completion queues in the kernel +with at least .I entries -entries and then maps the resulting file descriptor to memory shared between the -application and the kernel. +entries in the submission queue and then maps the resulting file descriptor to +memory shared between the application and the kernel. -On success io_uring_queue_init() returns 0 and +By default, the CQ ring will have twice the number of entries as specified by +.I entries +for the SQ ring. This is adequate for regular file or storage workloads, but +may be too small networked workloads. The SQ ring entries do not impose a limit +on the number of in-flight requests that the ring can support, it merely limits +the number that can be submitted to the kernel in one go (batch). if the CQ +ring overflows, e.g. more entries are generated than fits in the ring before the +application can reap them, then the ring enters a CQ ring overflow state. This +is indicated by +.B IORING_SQ_CQ_OVERFLOW +being set in the SQ ring flags. Unless the kernel runs out of available memory, +entries are not dropped, but it is a much slower completion path and will slow +down request processing. For that reason it should be avoided and the CQ +ring sized appropriately for the workload. Setting +.I cq_entries +in +.I struct io_uring_params +will tell the kernel to allocate this many entries for the CQ ring, independent +of the SQ ring size in given in +.IR entries . +If the value isn't a power of 2, it will be rounded up to the nearest power of +2. + +On success, +.BR io_uring_queue_init (3) +returns 0 and .I ring will point to the shared memory containing the io_uring queues. On failure --errno is returned. +.BR -errno +is returned. .I flags -will be passed through to the io_uring_setup syscall (see +will be passed through to the io_uring_setup syscall (see .BR io_uring_setup (2)). +If the +.BR io_uring_queue_init_params (3) +variant is used, then the parameters indicated by +.I params +will be passed straight through to the +.BR io_uring_setup (2) +system call. + On success, the resources held by .I ring should be released via a corresponding call to .BR io_uring_queue_exit (3). .SH RETURN VALUE .BR io_uring_queue_init (3) -returns 0 on success and -errno on failure. +returns 0 on success and +.BR -errno +on failure. .SH SEE ALSO .BR io_uring_setup (2), +.BR io_uring_register_ring_fd (3), .BR mmap (2), .BR io_uring_queue_exit (3) diff --git a/man/io_uring_queue_init_params.3 b/man/io_uring_queue_init_params.3 new file mode 120000 index 0000000..c91609e --- /dev/null +++ b/man/io_uring_queue_init_params.3 @@ -0,0 +1 @@ +io_uring_queue_init.3
\ No newline at end of file diff --git a/man/io_uring_register.2 b/man/io_uring_register.2 index 5326a87..1e91caf 100644 --- a/man/io_uring_register.2 +++ b/man/io_uring_register.2 @@ -88,14 +88,107 @@ then issuing a new call to .BR io_uring_register () with the new buffers. -Note that registering buffers will wait for the ring to idle. If the application -currently has requests in-flight, the registration will wait for those to -finish before proceeding. +Note that before 5.13 registering buffers would wait for the ring to idle. +If the application currently has requests in-flight, the registration will +wait for those to finish before proceeding. An application need not unregister buffers explicitly before shutting down the io_uring instance. Available since 5.1. .TP +.B IORING_REGISTER_BUFFERS2 +Register buffers for I/O. Similar to +.B IORING_REGISTER_BUFFERS +but aims to have a more extensible ABI. + +.I arg +points to a +.I struct io_uring_rsrc_register, +and +.I nr_args +should be set to the number of bytes in the structure. + +.PP +.in +8n +.EX +struct io_uring_rsrc_register { + __u32 nr; + __u32 resv; + __u64 resv2; + __aligned_u64 data; + __aligned_u64 tags; +}; + +.EE +.in +.PP + +.in +8n + +The +.I data +field contains a pointer to a +.I struct iovec +array of +.I nr +entries. +The +.I tags +field should either be 0, then tagging is disabled, or point to an array +of +.I nr +"tags" (unsigned 64 bit integers). If a tag is zero, then tagging for this +particular resource (a buffer in this case) is disabled. Otherwise, after the +resource had been unregistered and it's not used anymore, a CQE will be +posted with +.I user_data +set to the specified tag and all other fields zeroed. + +Note that resource updates, e.g. +.B IORING_REGISTER_BUFFERS_UPDATE, +don't necessarily deallocate resources by the time it returns, but they might +be held alive until all requests using it complete. + +Available since 5.13. + +.TP +.B IORING_REGISTER_BUFFERS_UPDATE +Updates registered buffers with new ones, either turning a sparse entry into +a real one, or replacing an existing entry. + +.I arg +must contain a pointer to a struct io_uring_rsrc_update2, which contains +an offset on which to start the update, and an array of +.I struct iovec. +.I tags +points to an array of tags. +.I nr +must contain the number of descriptors in the passed in arrays. +See +.B IORING_REGISTER_BUFFERS2 +for the resource tagging description. + +.PP +.in +8n +.EX + +struct io_uring_rsrc_update2 { + __u32 offset; + __u32 resv; + __aligned_u64 data; + __aligned_u64 tags; + __u32 nr; + __u32 resv2; +}; +.EE +.in +.PP + +.in +8n + +Available since 5.13. + +.TP .B IORING_UNREGISTER_BUFFERS This operation takes no argument, and .I arg @@ -128,25 +221,60 @@ See .B IORING_REGISTER_FILES_UPDATE for how to update files in place. -Note that registering files will wait for the ring to idle. If the application -currently has requests in-flight, the registration will wait for those to -finish before proceeding. See +Note that before 5.13 registering files would wait for the ring to idle. +If the application currently has requests in-flight, the registration will +wait for those to finish before proceeding. See .B IORING_REGISTER_FILES_UPDATE for how to update an existing set without that limitation. Files are automatically unregistered when the io_uring instance is -torn down. An application need only unregister if it wishes to +torn down. An application needs only unregister if it wishes to register a new set of fds. Available since 5.1. .TP +.B IORING_REGISTER_FILES2 +Register files for I/O. Similar to +.B IORING_REGISTER_FILES. + +.I arg +points to a +.I struct io_uring_rsrc_register, +and +.I nr_args +should be set to the number of bytes in the structure. + +The +.I data +field contains a pointer to an array of +.I nr +file descriptors (signed 32 bit integers). +.I tags +field should either be 0 or or point to an array of +.I nr +"tags" (unsigned 64 bit integers). See +.B IORING_REGISTER_BUFFERS2 +for more info on resource tagging. + +Note that resource updates, e.g. +.B IORING_REGISTER_FILES_UPDATE, +don't necessarily deallocate resources, they might be held until all requests +using that resource complete. + +Available since 5.13. + +.TP .B IORING_REGISTER_FILES_UPDATE This operation replaces existing files in the registered file set with new -ones, either turning a sparse entry (one where fd is equal to -1) into a -real one, removing an existing entry (new one is set to -1), or replacing -an existing entry with a new existing entry. +ones, either turning a sparse entry (one where fd is equal to +.B -1 +) into a real one, removing an existing entry (new one is set to +.B -1 +), or replacing an existing entry with a new existing entry. .I arg -must contain a pointer to a struct io_uring_files_update, which contains +must contain a pointer to a +.I struct io_uring_files_update, +which contains an offset on which to start the update, and an array of file descriptors to use for the update. .I nr_args @@ -158,6 +286,32 @@ File descriptors can be skipped if they are set to Skipping an fd will not touch the file associated with the previous fd at that index. Available since 5.12. +.TP +.B IORING_REGISTER_FILES_UPDATE2 +Similar to IORING_REGISTER_FILES_UPDATE, replaces existing files in the +registered file set with new ones, either turning a sparse entry (one where +fd is equal to +.B -1 +) into a real one, removing an existing entry (new one is set to +.B -1 +), or replacing an existing entry with a new existing entry. + +.I arg +must contain a pointer to a +.I struct io_uring_rsrc_update2, +which contains +an offset on which to start the update, and an array of file descriptors to +use for the update stored in +.I data. +.I tags +points to an array of tags. +.I nr +must contain the number of descriptors in the passed in arrays. +See +.B IORING_REGISTER_BUFFERS2 +for the resource tagging description. + +Available since 5.13. .TP .B IORING_UNREGISTER_FILES @@ -174,7 +328,13 @@ registered through this operation. .I arg must contain a pointer to the eventfd file descriptor, and .I nr_args -must be 1. Available since 5.2. +must be 1. Note that while io_uring generally takes care to avoid spurious +events, they can occur. Similarly, batched completions of CQEs may only trigger +a single eventfd notification even if multiple CQEs are posted. The application +should make no assumptions on number of events being available having a direct +correlation to eventfd notifications posted. An eventfd notification must thus +only be treated as a hint to check the CQ ring for completions. Available since +5.2. An application can temporarily disable notifications, coming through the registered eventfd, by setting the @@ -292,11 +452,140 @@ must be specified in the call to Available since 5.10. +.TP +.B IORING_REGISTER_IOWQ_AFF +By default, async workers created by io_uring will inherit the CPU mask of its +parent. This is usually all the CPUs in the system, unless the parent is being +run with a limited set. If this isn't the desired outcome, the application +may explicitly tell io_uring what CPUs the async workers may run on. +.I arg +must point to a +.B cpu_set_t +mask, and +.I nr_args +the byte size of that mask. + +Available since 5.14. + +.TP +.B IORING_UNREGISTER_IOWQ_AFF +Undoes a CPU mask previously set with +.B IORING_REGISTER_IOWQ_AFF. +Must not have +.I arg +or +.I nr_args +set. + +Available since 5.14. + +.TP +.B IORING_REGISTER_IOWQ_MAX_WORKERS +By default, io_uring limits the unbounded workers created to the maximum +processor count set by +.I RLIMIT_NPROC +and the bounded workers is a function of the SQ ring size and the number +of CPUs in the system. Sometimes this can be excessive (or too little, for +bounded), and this command provides a way to change the count per ring (per NUMA +node) instead. + +.I arg +must be set to an +.I unsigned int +pointer to an array of two values, with the values in the array being set to +the maximum count of workers per NUMA node. Index 0 holds the bounded worker +count, and index 1 holds the unbounded worker count. On successful return, the +passed in array will contain the previous maximum valyes for each type. If the +count being passed in is 0, then this command returns the current maximum values +and doesn't modify the current setting. +.I nr_args +must be set to 2, as the command takes two values. + +Available since 5.15. + +.TP +.B IORING_REGISTER_RING_FDS +Whenever +.BR io_uring_enter (2) +is called to submit request or wait for completions, the kernel must grab a +reference to the file descriptor. If the application using io_uring is threaded, +the file table is marked as shared, and the reference grab and put of the file +descriptor count is more expensive than it is for a non-threaded application. + +Similarly to how io_uring allows registration of files, this allow registration +of the ring file descriptor itself. This reduces the overhead of the +.BR io_uring_enter (2) +system call. + +.I arg +must be set to an unsigned int pointer to an array of type +.I struct io_uring_rsrc_register +of +.I nr_args +number of entries. The +.B data +field of this struct must point to an io_uring file descriptor, and the +.B offset +field can be either +.B -1 +or an explicit offset desired for the registered file descriptor value. If +.B -1 +is used, then upon successful return of this system call, the field will +contain the value of the registered file descriptor to be used for future +.BR io_uring_enter (2) +system calls. + +On successful completion of this request, the returned descriptors may be used +instead of the real file descriptor for +.BR io_uring_enter (2), +provided that +.B IORING_ENTER_REGISTERED_RING +is set in the +.I flags +for the system call. This flag tells the kernel that a registered descriptor +is used rather than a real file descriptor. + +Each thread or process using a ring must register the file descriptor directly +by issuing this request.o + +The maximum number of supported registered ring descriptors is currently +limited to +.B 16. + +Available since 5.18. + +.TP +.B IORING_UNREGISTER_RING_FDS +Unregister descriptors previously registered with +.B IORING_REGISTER_RING_FDS. + +.I arg +must be set to an unsigned int pointer to an array of type +.I struct io_uring_rsrc_register +of +.I nr_args +number of entries. Only the +.B offset +field should be set in the structure, containing the registered file descriptor +offset previously returned from +.B IORING_REGISTER_RING_FDS +that the application wishes to unregister. + +Note that this isn't done automatically on ring exit, if the thread or task +that previously registered a ring file descriptor isn't exiting. It is +recommended to manually unregister any previously registered ring descriptors +if the ring is closed and the task persists. This will free up a registration +slot, making it available for future use. + +Available since 5.18. + .SH RETURN VALUE On success, .BR io_uring_register () -returns 0. On error, -1 is returned, and +returns 0. On error, +.B -1 +is returned, and .I errno is set accordingly. diff --git a/man/io_uring_register_buf_ring.3 b/man/io_uring_register_buf_ring.3 new file mode 100644 index 0000000..9e520bf --- /dev/null +++ b/man/io_uring_register_buf_ring.3 @@ -0,0 +1,139 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_register_buf_ring 3 "May 18, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_register_buf_ring \- register buffer ring for provided buffers +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_register_buf_ring(struct io_uring *" ring ", +.BI " struct io_uring_buf_reg *" reg ", +.BI " unsigned int " flags ");" +.BI " +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_register_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 +.B IOSQE_BUFFER_SELECT +set in the SQE +.IR 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 +.I reg +argument must be filled in with the appropriate information. It looks as +follows: +.PP +.in +4n +.EX +struct io_uring_buf_reg { + __u64 ring_addr; + __u32 ring_entries; + __u16 bgid; + __u16 pad; + __u64 resv[3]; +}; +.EE +.in +.PP +The +.I ring_addr +field must contain the address to the memory allocated to fit this ring. +The memory must be page aligned and hence allocated appropriately using eg +.BR posix_memalign (3) +or similar. The size of the ring is the product of +.I ring_entries +and the size of +.IR "struct io_uring_buf" . +.I ring_entries +is the desired size of the ring, and must be a power-of-2 in size. +.I bgid +is the buffer group ID associated with this ring. SQEs that select a buffer +has a buffer group associated with them in their +.I buf_group +field, and the associated CQE will have +.B IORING_CQE_F_BUFFER +set in their +.I flags +member, which will also contain the specific ID of the buffer seleted. The rest +of the fields are reserved and must be cleared to zero. + +The +.I flags +argument is currently unused and must be set to zero. + +A shared buffer ring looks as follows: +.PP +.in +4n +.EX +struct io_uring_buf_ring { + union { + struct { + __u64 resv1; + __u32 resv2; + __u16 resv3; + __u16 tail; + }; + struct io_uring_buf bufs[0]; + }; +}; +.EE +.in +.PP +where +.I tail +is the index at which the application can insert new buffers for consumption +by requests, and +.I struct io_uring_buf +is buffer definition: +.PP +.in +4n +.EX +struct io_uring_buf { + __u64 addr; + __u32 len; + __u16 bid; + __u16 resv; +}; +.EE +.in +.PP +where +.I addr +is the address for the buffer, +.I len +is the length of the buffer in bytes, and +.I bid +is the buffer ID that will be returned in the CQE once consumed. + +Reserved fields must not be touched. Applications must use +.BR io_uring_buf_ring_init (3) +to initialise the buffer ring. Applications may use +.BR io_uring_buf_ring_add (3) +and +.BR io_uring_buf_ring_advance (3) +or +.BR io_uring_buf_ring_advance (3) +to provide buffers, which will set these fields and update the tail. + +Available since 5.19. + +.SH RETURN VALUE +On success +.BR io_uring_register_buf_ring (3) +returns 0. On failure it returns +.BR -errno . +.SH SEE ALSO +.BR io_uring_buf_ring_init (3), +.BR io_uring_buf_ring_add (3), +.BR io_uring_buf_ring_advance (3), +.BR io_uring_buf_ring_cq_advance (3) 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) diff --git a/man/io_uring_register_eventfd.3 b/man/io_uring_register_eventfd.3 new file mode 100644 index 0000000..5cbe72a --- /dev/null +++ b/man/io_uring_register_eventfd.3 @@ -0,0 +1,51 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_register_eventfd 3 "April 16, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_register_eventfd \- register an eventfd with a ring +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_register_eventfd(struct io_uring *" ring "," +.BI " int " fd ");" +.PP +.BI "int io_uring_register_eventfd_async(struct io_uring *" ring "," +.BI " int " fd ");" +.PP +.BI "int io_uring_unregister_eventfd(struct io_uring *" ring ");" +.fi +.SH DESCRIPTION +.PP +.BR io_uring_register_eventfd (3) +registers the eventfd file descriptor +.I fd +with the ring identified by +.IR ring . + +Whenever completions are posted to the CQ ring, an eventfd notification +is generated with the registered eventfd descriptor. If +.BR io_uring_register_eventfd_async (3) +is used, only events that completed out-of-line will trigger a notification. + +It notifications are no longer desired, +.BR io_uring_unregister_eventfd (3) +may be called to remove the eventfd registration. No eventfd argument is +needed, as a ring can only have a single eventfd registered. + +.SH NOTES +While io_uring generally takes care to avoid spurious events, they can occur. +Similarly, batched completions of CQEs may only trigger a single eventfd +notification even if multiple CQEs are posted. The application should make no +assumptions on number of events being available having a direct correlation to +eventfd notifications posted. An eventfd notification must thus only be treated +as a hint to check the CQ ring for completions. +.SH RETURN VALUE +Returns 0 on success, or +or +.BR -errno +on error. +.SH SEE ALSO +.BR eventfd (2) diff --git a/man/io_uring_register_eventfd_async.3 b/man/io_uring_register_eventfd_async.3 new file mode 120000 index 0000000..6659957 --- /dev/null +++ b/man/io_uring_register_eventfd_async.3 @@ -0,0 +1 @@ +io_uring_register_eventfd.3
\ No newline at end of file diff --git a/man/io_uring_register_files.3 b/man/io_uring_register_files.3 new file mode 100644 index 0000000..0a9ccc3 --- /dev/null +++ b/man/io_uring_register_files.3 @@ -0,0 +1,50 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_register_files 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_register_files \- register file descriptors +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_register_files(struct io_uring *" ring "," +.BI " const int *" files "," +.BI " unsigned " nr_files ");" +.PP +.BI "int io_uring_register_files_sparse(struct io_uring *" ring "," +.BI " unsigned " nr_files ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_register_files (3) +function registers +.I nr_files +number of file descriptors defined by the array +.I files +belonging to the +.I ring +for subsequent operations. + +The +.BR io_uring_register_files_sparse (3) +function registers an empty file table of +.I nr_files +number of file descriptors. The sparse variant is available in kernels 5.19 +and later. + +Registering a file table is a prerequisite for using any request that uses +direct descriptors. + +.SH RETURN VALUE +On success +.BR io_uring_register_files (3) +and +.BR io_uring_register_files_sparse (3) +return 0. On failure they return +.BR -errno . +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_unregister_files (3) diff --git a/man/io_uring_register_iowq_aff.3 b/man/io_uring_register_iowq_aff.3 new file mode 100644 index 0000000..e782914 --- /dev/null +++ b/man/io_uring_register_iowq_aff.3 @@ -0,0 +1,61 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_register_iowq_aff 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_register_iowq_aff \- register async worker CPU affinities +.SH SYNOPSIS +.nf +.B #include <sched.h> +.B #include <liburing.h> +.PP +.BI "int io_uring_register_iowq_aff(struct io_uring *" ring "," +.BI " size_t " cpusz "," +.BI " const cpu_set_t *" mask "); +.PP +.BI "void io_uring_unregister_iowq_aff(struct io_uring *" ring ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_prep_register_iowq_aff (3) +function registers a set of CPU affinities to be used by the io_uring async +workers. By default, io_uring async workers are allowed to run on any CPU in +the system. If this function is called with +.I ring +set to the ring in question and +.I mask +set to a pointer to a +.B cpu_set_t +value and +.I cpusz +set to the size of the CPU set, then async workers will only be allowed to run +on the CPUs specified in the mask. Existing workers may need to hit a schedule +point before they are migrated. + +For unregistration, +.BR io_uring_unregister_iowq_aff (3) +may be called to restore CPU affinities to the default. + +.SH RETURN VALUE +Returns +.B 0 +on success, or any of the following values in case of error. +.TP +.B -EFAULT +The kernel was unable to copy the memory pointer to by +.I mask +as it was invalid. +.TP +.B -ENOMEM +The kernel was unable to allocate memory for the new CPU mask. +.TP +.B -EINVAL +.I cpusz +or +.I mask +was NULL/0, or any other value specified was invalid. +.SH SEE ALSO +.BR io_uring_queue_init (3), +.BR io_uring_register (2) diff --git a/man/io_uring_register_iowq_max_workers.3 b/man/io_uring_register_iowq_max_workers.3 new file mode 100644 index 0000000..2557e21 --- /dev/null +++ b/man/io_uring_register_iowq_max_workers.3 @@ -0,0 +1,71 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_register_iowq_max_workers 3 "March 13, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_register_iowq_max_workers \- modify the maximum allowed async workers +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_register_iowq_max_workers(struct io_uring *" ring "," +.BI " unsigned int *" values ");" +.fi +.SH DESCRIPTION +.PP +io_uring async workers are split into two types: +.TP +.B Bounded +These workers have a bounded execution time. Examples of that are filesystem +reads, which normally complete in a relatively short amount of time. In case +of disk failures, they are still bounded by a timeout operation that will +abort them if exceeded. +.TP +.B Unbounded +Work items here may take an indefinite amount of time to complete. Examples +include doing IO to sockets, pipes, or any other non-regular type of file. + +.PP +By default, the amount of bounded IO workers is limited to how many SQ entries +the ring was setup with, or 4 times the number of online CPUs in the system, +whichever is smaller. Unbounded workers are only limited by the process task +limit, as indicated by the rlimit +.B RLIMIT_NPROC +limit. + +This can be modified by calling +.B io_uring_register_iowq_max_workers +with +.I ring +set to the ring in question, and +.I values +pointing to an array of two values. The first element should contain the number +of desired bounded workers, and the second element should contain the number +of desired unbounded workers. These are both maximum values, io_uring will +not maintain a high count of idle workers, they are reaped when they are not +necessary anymore. + +If called with both values set to 0, the existing values are returned. + +.SH RETURN VALUE +Returns +.B 0 +on success, with +.I values +containing the previous values for the settings. On error, any of the following +may be returned. +.TP +.B -EFAULT +The kernel was unable to copy the memory pointer to by +.I values +as it was invalid. +.TP +.B -EINVAL +.I values +was +.B NULL +or the new values exceeded the maximum allowed value. +.SH SEE ALSO +.BR io_uring_queue_init (3), +.BR io_uring_register (2) diff --git a/man/io_uring_register_ring_fd.3 b/man/io_uring_register_ring_fd.3 new file mode 100644 index 0000000..e70c551 --- /dev/null +++ b/man/io_uring_register_ring_fd.3 @@ -0,0 +1,49 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_register_ring_fd 3 "March 11, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_register_ring_fd \- register a ring file descriptor +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_register_ring_fd(struct io_uring *" ring ");" +.fi +.SH DESCRIPTION +.PP +.BR io_uring_register_ring_fd (3) +registers the file descriptor of the ring. + +Whenever +.BR io_uring_enter (2) +is called to submit request or wait for completions, the kernel must grab a +reference to the file descriptor. If the application using io_uring is threaded, +the file table is marked as shared, and the reference grab and put of the file +descriptor count is more expensive than it is for a non-threaded application. + +Similarly to how io_uring allows registration of files, this allow registration +of the ring file descriptor itself. This reduces the overhead of the +.BR io_uring_enter (2) +system call. + +If an application using liburing is threaded, then an application should call +this function to register the ring descriptor when a ring is set up. See NOTES +for restrictions when a ring is shared. + +.SH NOTES +When the ring descriptor is registered, it is stored internally in the +.I struct io_uring +structure. For applications that share a ring between threads, for example +having one thread do submits and another reap events, then this optimization +cannot be used as each thread may have a different index for the registered +ring fd. +.SH RETURN VALUE +Returns 1 on success, indicating that one file descriptor was registered, +or +.BR -errno +on error. +.SH SEE ALSO +.BR io_uring_unregister_ring_fd (3), +.BR io_uring_register_files (3) diff --git a/man/io_uring_setup.2 b/man/io_uring_setup.2 index cb8eba9..75c69ff 100644 --- a/man/io_uring_setup.2 +++ b/man/io_uring_setup.2 @@ -37,7 +37,8 @@ struct io_uring_params { __u32 sq_thread_cpu; __u32 sq_thread_idle; __u32 features; - __u32 resv[4]; + __u32 wq_fd; + __u32 resv[3]; struct io_sqring_offsets sq_off; struct io_cqring_offsets cq_off; }; @@ -170,7 +171,7 @@ then it will be clamped at .B IORING_MAX_CQ_ENTRIES . .TP .B IORING_SETUP_ATTACH_WQ -This flag should be set in conjunction with +This flag should be set in conjunction with .IR "struct io_uring_params.wq_fd" being set to an existing io_uring ring file descriptor. When set, the io_uring instance being created will share the asynchronous worker @@ -183,6 +184,61 @@ In this state, restrictions can be registered, but submissions are not allowed. See .BR io_uring_register (2) for details on how to enable the ring. Available since 5.10. +.TP +.B IORING_SETUP_SUBMIT_ALL +Normally io_uring stops submitting a batch of request, if one of these requests +results in an error. This can cause submission of less than what is expected, +if a request ends in error while being submitted. If the ring is created with +this flag, +.BR io_uring_enter (2) +will continue submitting requests even if it encounters an error submitting +a request. CQEs are still posted for errored request regardless of whether or +not this flag is set at ring creation time, the only difference is if the +submit sequence is halted or continued when an error is observed. Available +since 5.18. +.TP +.B IORING_SETUP_COOP_TASKRUN +By default, io_uring will interrupt a task running in userspace when a +completion event comes in. This is to ensure that completions run in a timely +manner. For a lot of use cases, this is overkill and can cause reduced +performance from both the inter-processor interrupt used to do this, the +kernel/user transition, the needless interruption of the tasks userspace +activities, and reduced batching if completions come in at a rapid rate. Most +applications don't need the forceful interruption, as the events are processed +at any kernel/user transition. The exception are setups where the application +uses multiple threads operating on the same ring, where the application +waiting on completions isn't the one that submitted them. For most other +use cases, setting this flag will improve performance. Available since 5.19. +.TP +.B IORING_SETUP_TASKRUN_FLAG +Used in conjunction with +.B IORING_SETUP_COOP_TASKRUN, +this provides a flag, +.B IORING_SQ_TASKRUN, +which is set in the SQ ring +.I flags +whenever completions are pending that should be processed. liburing will check +for this flag even when doing +.BR io_uring_peek_cqe (3) +and enter the kernel to process them, and applications can do the same. This +makes +.B IORING_SETUP_TASKRUN_FLAG +safe to use even when applications rely on a peek style operation on the CQ +ring to see if anything might be pending to reap. Available since 5.19. +.TP +.B IORING_SETUP_SQE128 +If set, io_uring will use 128-byte SQEs rather than the normal 64-byte sized +variant. This is a requirement for using certain request types, as of 5.19 +only the +.B IORING_OP_URING_CMD +passthrough command for NVMe passthrough needs this. Available since 5.19. +.TP +.B IORING_SETUP_CQE32 +If set, io_uring will use 32-byte CQEs rather than the normal 32-byte sized +variant. This is a requirement for using certain request types, as of 5.19 +only the +.B IORING_OP_URING_CMD +passthrough command for NVMe passthrough needs this. Available since 5.19. .PP If no flags are specified, the io_uring instance is setup for interrupt driven I/O. I/O may be submitted using @@ -202,27 +258,30 @@ If this flag is set, the two SQ and CQ rings can be mapped with a single .I mmap(2) call. The SQEs must still be allocated separately. This brings the necessary .I mmap(2) -calls down from three to two. +calls down from three to two. Available since kernel 5.4. .TP .B IORING_FEAT_NODROP If this flag is set, io_uring supports never dropping completion events. If a completion event occurs and the CQ ring is full, the kernel stores the event internally until such a time that the CQ ring has room for more entries. If this overflow condition is entered, attempting to submit more -IO with fail with the +IO will fail with the .B -EBUSY error value, if it can't flush the overflown events to the CQ ring. If this happens, the application must reap events from the CQ ring and attempt the -submit again. +submit again. Available since kernel 5.5. .TP .B IORING_FEAT_SUBMIT_STABLE If this flag is set, applications can be certain that any data for -async offload has been consumed when the kernel has consumed the SQE. +async offload has been consumed when the kernel has consumed the SQE. Available +since kernel 5.5. .TP .B IORING_FEAT_RW_CUR_POS If this flag is set, applications can specify .I offset -== -1 with +== +.B -1 +with .B IORING_OP_{READV,WRITEV} , .B IORING_OP_{READ,WRITE}_FIXED @@ -234,10 +293,13 @@ and .I pwritev2(2) with .I offset -== -1. It'll use (and update) the current file position. This obviously comes +== +.B -1. +It'll use (and update) the current file position. This obviously comes with the caveat that if the application has multiple reads or writes in flight, then the end result will not be as expected. This is similar to threads sharing -a file descriptor and doing IO using the current file position. +a file descriptor and doing IO using the current file position. Available since +kernel 5.6. .TP .B IORING_FEAT_CUR_PERSONALITY If this flag is set, then io_uring guarantees that both sync and async @@ -253,7 +315,7 @@ still register different personalities through io_uring_register(2) with .B IORING_REGISTER_PERSONALITY -and specify the personality to use in the sqe. +and specify the personality to use in the sqe. Available since kernel 5.6. .TP .B IORING_FEAT_FAST_POLL If this flag is set, then io_uring supports using an internal poll mechanism @@ -262,20 +324,81 @@ write data to a file no longer need to be punted to an async thread for handling, instead they will begin operation when the file is ready. This is similar to doing poll + read/write in userspace, but eliminates the need to do so. If this flag is set, requests waiting on space/data consume a lot less -resources doing so as they are not blocking a thread. +resources doing so as they are not blocking a thread. Available since kernel +5.7. .TP .B IORING_FEAT_POLL_32BITS If this flag is set, the .B IORING_OP_POLL_ADD command accepts the full 32-bit range of epoll based flags. Most notably .B EPOLLEXCLUSIVE -which allows exclusive (waking single waiters) behavior. +which allows exclusive (waking single waiters) behavior. Available since kernel +5.9. .TP .B IORING_FEAT_SQPOLL_NONFIXED If this flag is set, the .B IORING_SETUP_SQPOLL feature no longer requires the use of fixed files. Any normal file descriptor -can be used for IO commands without needing registration. +can be used for IO commands without needing registration. Available since +kernel 5.11. +.TP +.B IORING_FEAT_ENTER_EXT_ARG +If this flag is set, then the +.BR io_uring_enter (2) +system call supports passing in an extended argument instead of just the +.IR "sigset_t" +of earlier kernels. This. +extended argument is of type +.IR "struct io_uring_getevents_arg" +and allows the caller to pass in both a +.IR "sigset_t" +and a timeout argument for waiting on events. The struct layout is as follows: +.TP +.in +8n +.EX +struct io_uring_getevents_arg { + __u64 sigmask; + __u32 sigmask_sz; + __u32 pad; + __u64 ts; +}; +.EE + +and a pointer to this struct must be passed in if +.B IORING_ENTER_EXT_ARG +is set in the flags for the enter system call. Available since kernel 5.11. +.TP +.B IORING_FEAT_NATIVE_WORKERS +If this flag is set, io_uring is using native workers for its async helpers. +Previous kernels used kernel threads that assumed the identity of the +original io_uring owning task, but later kernels will actively create what +looks more like regular process threads instead. Available since kernel +5.12. +.TP +.B IORING_FEAT_RSRC_TAGS +If this flag is set, then io_uring supports a variety of features related +to fixed files and buffers. In particular, it indicates that registered +buffers can be updated in-place, whereas before the full set would have to +be unregistered first. Available since kernel 5.13. +.TP +.B IORING_FEAT_CQE_SKIP +If this flag is set, then io_uring supports setting +.B IOSQE_CQE_SKIP_SUCCESS +in the submitted SQE, indicating that no CQE should be generated for this +SQE if it executes normally. If an error happens processing the SQE, a +CQE with the appropriate error value will still be generated. Available since +kernel 5.17. +.TP +.B IORING_FEAT_LINKED_FILE +If this flag is set, then io_uring supports sane assignment of files for SQEs +that have dependencies. For example, if a chain of SQEs are submitted with +.B IOSQE_IO_LINK, +then kernels without this flag will prepare the file for each link upfront. +If a previous link opens a file with a known index, eg if direct descriptors +are used with open or accept, then file assignment needs to happen post +execution of that SQE. If this flag is set, then the kernel will defer +file assignment until execution of a given request is started. Available since +kernel 5.17. .PP The rest of the fields in the @@ -425,7 +548,9 @@ or .BR io_uring_enter (2) system calls. -On error, -1 is returned and +On error, +.B -1 +is returned and .I errno is set appropriately. .PP diff --git a/man/io_uring_sq_ready.3 b/man/io_uring_sq_ready.3 new file mode 100644 index 0000000..9927388 --- /dev/null +++ b/man/io_uring_sq_ready.3 @@ -0,0 +1,31 @@ +.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_sq_ready "January 25, 2022" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_sq_ready \- number of unconsumed or unsubmitted entries in the SQ ring +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "unsigned io_uring_sq_ready(const struct io_uring *" ring ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_sq_ready (3) +function retuns the number of unconsumed (if SQPOLL) or unsubmitted entries +that exist in the SQ ring belonging to the +.I ring +param. + +Usage of this function only applies if the ring has been setup with +.B IORING_SETUP_SQPOLL, +where request submissions, and hence consumption from the SQ ring, happens +through a polling thread. + +.SH RETURN VALUE +Returns the number of unconsumed or unsubmitted entries in the SQ ring. +.SH SEE ALSO +.BR io_uring_cq_ready (3) diff --git a/man/io_uring_sq_space_left.3 b/man/io_uring_sq_space_left.3 new file mode 100644 index 0000000..b5b2e21 --- /dev/null +++ b/man/io_uring_sq_space_left.3 @@ -0,0 +1,25 @@ +.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_sq_space-left "January 25, 2022" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_sq_space_left \- free space in the SQ ring +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "unsigned io_uring_sq_space_left(const struct io_uring *" ring ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_sq_space_left (3) +function retuns how much space is left in the SQ ring belonging to the +.I ring +param. + +.SH RETURN VALUE +Returns the number of availables entries in the SQ ring. +.SH SEE ALSO +.BR io_uring_sq_ready (3) diff --git a/man/io_uring_sqe_set_data.3 b/man/io_uring_sqe_set_data.3 new file mode 100644 index 0000000..274a892 --- /dev/null +++ b/man/io_uring_sqe_set_data.3 @@ -0,0 +1,48 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_sqe_set_data 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_sqe_set_data \- set user data for submission queue event +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_sqe_set_data(struct io_uring_sqe *" sqe "," +.BI " void *" user_data ");" +.BI " +.BI "void io_uring_sqe_set_data64(struct io_uring_sqe *" sqe "," +.BI " __u64 " data ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_sqe_set_data (3) +function stores a +.I user_data +pointer with the submission queue entry +.IR sqe . + +The +.BR io_uring_sqe_set_data64 (3) +function stores a 64-bit +.I data +value with the submission queue entry +.IR sqe . + +After the caller has requested a submission queue entry (SQE) with +.BR io_uring_get_sqe (3) , +they can associate a data pointer or value with the SQE. Once the completion +arrives, the function +.BR io_uring_cqe_get_data (3) +or +.BR io_uring_cqe_get_data64 (3) +can be called to retrieve the data pointer or value associated with the +submitted request. + +.SH RETURN VALUE +None +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_cqe_get_data (3) diff --git a/man/io_uring_sqe_set_data64.3 b/man/io_uring_sqe_set_data64.3 new file mode 120000 index 0000000..8bbd692 --- /dev/null +++ b/man/io_uring_sqe_set_data64.3 @@ -0,0 +1 @@ +io_uring_sqe_set_data.3
\ No newline at end of file diff --git a/man/io_uring_sqe_set_flags.3 b/man/io_uring_sqe_set_flags.3 new file mode 100644 index 0000000..75e836b --- /dev/null +++ b/man/io_uring_sqe_set_flags.3 @@ -0,0 +1,86 @@ +.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_sqe_set_flags "January 25, 2022" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_sqe_set_flags \- set flags for submission queue entry +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "void io_uring_sqe_set_flags(struct io_uring_sqe *" sqe "," +.BI " unsigned " flags ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_sqe_set_flags (3) +function allows the caller to change the behavior of the submission queue entry +by specifying flags. It enables the +.I flags +belonging to the +.I sqe +submission queue entry param. + +.I flags +is a bit mask of 0 or more of the following values ORed together: +.TP +.B IOSQE_FIXED_FILE +The file descriptor in the SQE refers to the index of a previously registered +file or direct file descriptor, not a normal file descriptor. +.TP +.B IOSQE_ASYNC +Normal operation for io_uring is to try and issue an sqe as non-blocking first, +and if that fails, execute it in an async manner. To support more efficient +overlapped operation of requests that the application knows/assumes will +always (or most of the time) block, the application can ask for an sqe to be +issued async from the start. Note that this flag immediately causes the SQE +to be offloaded to an async helper thread with no initial non-blocking attempt. +This may be less efficient and should not be used sporadically. +.TP +.B IOSQE_IO_LINK +When this flag is specified, the SQE forms a link with the next SQE in the +submission ring. That next SQE will not be started before the previous request +completes. This, in effect, forms a chain of SQEs, which can be arbitrarily +long. The tail of the chain is denoted by the first SQE that does not have this +flag set. Chains are not supported across submission boundaries. Even if the +last SQE in a submission has this flag set, it will still terminate the current +chain. This flag has no effect on previous SQE submissions, nor does it impact +SQEs that are outside of the chain tail. This means that multiple chains can be +executing in parallel, or chains and individual SQEs. Only members inside the +chain are serialized. A chain of SQEs will be broken if any request in that +chain ends in error. +.TP +.B IOSQE_IO_HARDLINK +Like +.B IOSQE_IO_LINK , +except the links aren't severed if an error or unexpected result occurs. +.TP +.B IOSQE_IO_DRAIN +When this flag is specified, the SQE will not be started before previously +submitted SQEs have completed, and new SQEs will not be started before this +one completes. +.TP +.B IOSQE_CQE_SKIP_SUCCESS +Request that no CQE be generated for this request, if it completes successfully. +This can be useful in cases where the application doesn't need to know when +a specific request completed, if it completed succesfully. +.TP +.B IOSQE_BUFFER_SELECT +If set, and if the request types supports it, select an IO buffer from the +indicated buffer group. This can be used with requests that read or receive +data from a file or socket, where buffer selection is deferred until the kernel +is ready to transfer data, instead of when the IO is originally submitted. The +application must also set the +.I buf_group +field in the SQE, indicating which previously registered buffer group to select +a buffer from. + +.SH RETURN VALUE +None +.SH SEE ALSO +.BR io_uring_submit (3), +.BR io_uring_register (3) +.BR io_uring_register_buffers (3) +.BR io_uring_register_buf_ring (3) diff --git a/man/io_uring_sqring_wait.3 b/man/io_uring_sqring_wait.3 new file mode 100644 index 0000000..d70cf40 --- /dev/null +++ b/man/io_uring_sqring_wait.3 @@ -0,0 +1,34 @@ +.\" Copyright (C) 2022 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_sqring_wait "January 25, 2022" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_sqring_wait \- wait for free space in the SQ ring +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_sqring_wait(struct io_uring *" ring ");" +.fi +.SH DESCRIPTION +.PP +The function +.BR io_uring_sqring_wait (3) +allows the caller to wait for space to free up in the SQ ring belonging to the +.I ring +param, which happens when the kernel side thread +has consumed one or more entries. If the SQ ring is currently non-full, +no action is taken. + +This feature can only be used when the ring has been setup with +.B IORING_SETUP_SQPOLL +and hence is using an offloaded approach to request submissions. + +.SH RETURN VALUE +On success it returns the free space. If the kernel does not support the +feature, -EINVAL is returned. +.SH SEE ALSO +.BR io_uring_submit (3), +.BR io_uring_wait_cqe (3), +.BR io_uring_wait_cqes (3) diff --git a/man/io_uring_submit.3 b/man/io_uring_submit.3 new file mode 100644 index 0000000..f871b89 --- /dev/null +++ b/man/io_uring_submit.3 @@ -0,0 +1,46 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_submit 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_submit \- submit requests to the submission queue +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_submit(struct io_uring *" ring ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_submit (3) +function submits the next events to the submission queue belonging to the +.IR ring . + +After the caller retrieves a submission queue entry (SQE) with +.BR io_uring_get_sqe (3) +and prepares the SQE using one of the provided helpers, it can be submitted with +.BR io_uring_submit (3) . + +.SH RETURN VALUE +On success +.BR io_uring_submit (3) +returns the number of submitted submission queue entries. On failure it returns +.BR -errno . +.SH NOTES +For any request that passes in data in a struct, that data must remain +valid until the request has been successfully submitted. It need not remain +valid until completion. Once a request has been submitted, the in-kernel +state is stable. Very early kernels (5.4 and earlier) required state to be +stable until the completion occurred. Applications can test for this +behavior by inspecting the +.B IORING_FEAT_SUBMIT_STABLE +flag passed back from +.BR io_uring_queue_init_params (3). +In general, the man pages for the individual prep helpers will have a note +mentioning this fact as well, if required for the given command. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit_and_wait (3), +.BR io_uring_submit_and_wait_timeout (3) diff --git a/man/io_uring_submit_and_wait.3 b/man/io_uring_submit_and_wait.3 new file mode 100644 index 0000000..1c9eb62 --- /dev/null +++ b/man/io_uring_submit_and_wait.3 @@ -0,0 +1,38 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_submit_and_wait 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_submit_and_wait \- submit requests to the submission queue and wait for completion +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_submit_and_wait(struct io_uring *" ring "," +.BI " unsigned " wait_nr ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_submit_and_wait (3) +function submits the next events to the submission queue belonging to the +.I ring +and waits for +.I wait_nr +completion events. + +After the caller retrieves a submission queue entry (SQE) with +.BR io_uring_get_sqe (3) +and prepares the SQE, it can be submitted with +.BR io_uring_submit_and_wait (3) . + +.SH RETURN VALUE +On success +.BR io_uring_submit_and_wait (3) +returns the number of submitted submission queue entries. On failure it returns +.BR -errno . +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_submit_and_wait_timeout (3) diff --git a/man/io_uring_submit_and_wait_timeout.3 b/man/io_uring_submit_and_wait_timeout.3 new file mode 100644 index 0000000..80fe889 --- /dev/null +++ b/man/io_uring_submit_and_wait_timeout.3 @@ -0,0 +1,54 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_submit_and_wait_timeout 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_submit_and_wait_timeout \- submit requests to the submission queue and +wait for the completion with timeout +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_submit_and_wait_timeout(struct io_uring *" ring "," +.BI " struct io_uring_cqe **" cqe_ptr "," +.BI " unsigned " wait_nr "," +.BI " struct __kernel_timespec *" ts "," +.BI " sigset_t *" sigmask ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_submit_and_wait_timeout (3) +function submits the next events to the submission queue belonging to the +.I ring +and waits for +.I wait_nr +completion events or until the timeout +.I ts +expires. The completion events are stored in the +.I cqe_ptr +array. The +.I sigmask +specifies the set of signals to block. The prevailing signal mask is restored +before returning. + +After the caller retrieves a submission queue entry (SQE) with +.BR io_uring_get_sqe (3) +and prepares the SQE, it can be submitted with +.BR io_uring_submit_and_wait_timeout (3) . + +.SH RETURN VALUE +On success +.BR io_uring_submit_and_wait_timeout (3) +returns the number of submitted submission queue entries. On failure it returns +.BR -errno . +The most common failure case is not receiving a completion within the specified +timeout, +.B -ETIME +is returned in this case. +.SH SEE ALSO +.BR io_uring_get_sqe (3), +.BR io_uring_submit (3), +.BR io_uring_submit_and_wait (3), +.BR io_uring_wait_cqe (3) diff --git a/man/io_uring_unregister_buf_ring.3 b/man/io_uring_unregister_buf_ring.3 new file mode 100644 index 0000000..ee87e86 --- /dev/null +++ b/man/io_uring_unregister_buf_ring.3 @@ -0,0 +1,30 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_unregister_buf_ring 3 "May 18, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_unregister_buf_ring \- unregister a previously registered buffer ring +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_unregister_buf_ring(struct io_uring *" ring ", +.BI " int " bgid ");" +.BI " +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_unregister_buf_ring (3) +function unregisters a previously registered shared buffer ring indicated by +.IR bgid . + +.SH RETURN VALUE +On success +.BR io_uring_unregister_buf_ring (3) +returns 0. On failure it returns +.BR -errno . +.SH SEE ALSO +.BR io_uring_register_buf_ring (3), +.BR io_uring_buf_ring_free (3) diff --git a/man/io_uring_unregister_buffers.3 b/man/io_uring_unregister_buffers.3 new file mode 100644 index 0000000..f066679 --- /dev/null +++ b/man/io_uring_unregister_buffers.3 @@ -0,0 +1,27 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_unregister_buffers 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_unregister_buffers \- unregister buffers for fixed buffer operations +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_unregister_buffers(struct io_uring *" ring ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_unregister_buffers (3) +function unregisters the fixed buffers previously registered to the +.IR ring . + +.SH RETURN VALUE +On success +.BR io_uring_unregister_buffers (3) +returns 0. On failure it returns +.BR -errno . +.SH SEE ALSO +.BR io_uring_register_buffers (3) diff --git a/man/io_uring_unregister_eventfd.3 b/man/io_uring_unregister_eventfd.3 new file mode 120000 index 0000000..6659957 --- /dev/null +++ b/man/io_uring_unregister_eventfd.3 @@ -0,0 +1 @@ +io_uring_register_eventfd.3
\ No newline at end of file diff --git a/man/io_uring_unregister_files.3 b/man/io_uring_unregister_files.3 new file mode 100644 index 0000000..c468d08 --- /dev/null +++ b/man/io_uring_unregister_files.3 @@ -0,0 +1,27 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_unregister_files 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_unregister_files \- unregister file descriptors +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_unregister_files(struct io_uring *" ring ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_unregister_files (3) +function unregisters the file descriptors previously registered to the +.IR ring . + +.SH RETURN VALUE +On success +.BR io_uring_unregister_files (3) +returns 0. On failure it returns +.BR -errno . +.SH SEE ALSO +.BR io_uring_register_files (3) diff --git a/man/io_uring_unregister_iowq_aff.3 b/man/io_uring_unregister_iowq_aff.3 new file mode 120000 index 0000000..c29bd44 --- /dev/null +++ b/man/io_uring_unregister_iowq_aff.3 @@ -0,0 +1 @@ +io_uring_register_iowq_aff.3
\ No newline at end of file diff --git a/man/io_uring_unregister_ring_fd.3 b/man/io_uring_unregister_ring_fd.3 new file mode 100644 index 0000000..85aca14 --- /dev/null +++ b/man/io_uring_unregister_ring_fd.3 @@ -0,0 +1,32 @@ +.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_unregister_ring_fd 3 "March 11, 2022" "liburing-2.2" "liburing Manual" +.SH NAME +io_uring_unregister_ring_fd \- unregister a ring file descriptor +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_unregister_ring_fd(struct io_uring *" ring ");" +.fi +.SH DESCRIPTION +.PP +.BR io_uring_unregister_ring_fd (3) +unregisters the file descriptor of the ring. + +Unregisters a ring descriptor previously registered with the task. This is +done automatically when +.BR io_uring_queue_exit (3) +is called, but can also be done to free up space for new ring registrations. +For more information on ring descriptor registration, see +.BR io_uring_register_ring_fd (3) + +.SH RETURN VALUE +Returns 1 on success, indicating that one file descriptor was unregistered, or +.BR -errno +on error. +.SH SEE ALSO +.BR io_uring_register_ring_fd (3), +.BR io_uring_register_files (3) diff --git a/man/io_uring_wait_cqe.3 b/man/io_uring_wait_cqe.3 new file mode 100644 index 0000000..c115f6f --- /dev/null +++ b/man/io_uring_wait_cqe.3 @@ -0,0 +1,40 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_wait_cqe 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_wait_cqe \- wait for one io_uring completion event +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_wait_cqe(struct io_uring *" ring "," +.BI " struct io_uring_cqe **" cqe_ptr ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_wait_cqe (3) +function waits for an IO completion from the queue belonging to the +.I ring +param, waiting for it if necessary. If an event is already available in +the ring when invoked, no waiting will occur. The +.I cqe_ptr +param is filled in on success. + +After the caller has submitted a request with +.BR io_uring_submit (3), +the application can retrieve the completion with +.BR io_uring_wait_cqe (3). + +.SH RETURN VALUE +On success +.BR io_uring_wait_cqe (3) +returns 0 and the cqe_ptr parm is filled in. On failure it returns +.BR -errno . +The return value indicates the result of waiting for a CQE, and it has no +relation to the CQE result itself. +.SH SEE ALSO +.BR io_uring_submit (3), +.BR io_uring_wait_cqes (3) diff --git a/man/io_uring_wait_cqe_nr.3 b/man/io_uring_wait_cqe_nr.3 new file mode 100644 index 0000000..5a4a5d5 --- /dev/null +++ b/man/io_uring_wait_cqe_nr.3 @@ -0,0 +1,43 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_wait_cqe_nr 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_wait_cqe_nr \- wait for one or more io_uring completion events +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_wait_cqe_nr(struct io_uring *" ring "," +.BI " struct io_uring_cqe **" cqe_ptr "," +.BI " unsigned " wait_nr ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_wait_cqe_nr (3) +function returns +.I wait_nr +IO completion events from the queue belonging to the +.I ring +param, waiting for it if necessary. If the requested number of events are +already available in the ring when invoked, no waiting will occur. The +.I cqe_ptr +param is filled in on success. + +After the caller has submitted a request with +.BR io_uring_submit (3), +the application can retrieve the completion with +.BR io_uring_wait_cqe (3). + +.SH RETURN VALUE +On success +.BR io_uring_wait_cqe_nr (3) +returns 0 and the cqe_ptr parm is filled in. On failure it returns +.BR -errno . +The return value indicates the result of waiting for a CQE, and it has no +relation to the CQE result itself. +.SH SEE ALSO +.BR io_uring_submit (3), +.BR io_uring_wait_cqes (3) diff --git a/man/io_uring_wait_cqe_timeout.3 b/man/io_uring_wait_cqe_timeout.3 new file mode 100644 index 0000000..965fc32 --- /dev/null +++ b/man/io_uring_wait_cqe_timeout.3 @@ -0,0 +1,53 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_wait_cqe_timeout 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_wait_cqe_timeout \- wait for one io_uring completion event with timeout +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_wait_cqe_timeout(struct io_uring *" ring "," +.BI " struct io_uring_cqe **" cqe_ptr "," +.BI " struct __kernel_timespec *" ts ");" +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_wait_cqe_timeout (3) +function waits for one IO completion to be available from the queue belonging +to the +.I ring +param, waiting for it if necessary or until the timeout +.I ts +expires. If an event is already available in the ring when invoked, no waiting +will occur. + +The +.I cqe_ptr +param is filled in on success. + +If +.I ts +is specified and an older kernel without +.B IORING_FEAT_EXT_ARG +is used, the application does not need to call +.BR io_uring_submit (3) +before calling +.BR io_uring_wait_cqes (3). +For newer kernels with that feature flag set, there is no implied submit +when waiting for a request. + +.SH RETURN VALUE +On success +.BR io_uring_wait_cqes (3) +returns 0 and the cqe_ptr parm is filled in. On failure it returns +.BR -errno . +The return value indicates the result of waiting for a CQE, and it has no +relation to the CQE result itself. +.SH SEE ALSO +.BR io_uring_submit (3), +.BR io_uring_wait_cqe_timeout (3), +.BR io_uring_wait_cqe (3) diff --git a/man/io_uring_wait_cqes.3 b/man/io_uring_wait_cqes.3 new file mode 100644 index 0000000..b771ebe --- /dev/null +++ b/man/io_uring_wait_cqes.3 @@ -0,0 +1,56 @@ +.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com> +.\" +.\" SPDX-License-Identifier: LGPL-2.0-or-later +.\" +.TH io_uring_wait_cqes 3 "November 15, 2021" "liburing-2.1" "liburing Manual" +.SH NAME +io_uring_wait_cqes \- wait for one or more io_uring completion events +.SH SYNOPSIS +.nf +.B #include <liburing.h> +.PP +.BI "int io_uring_wait_cqes(struct io_uring *" ring "," +.BI " struct io_uring_cqe **" cqe_ptr "," +.BI " unsigned " wait_nr "," +.BI " struct __kernel_timespec *" ts "," +.BI " sigset_t *" sigmask "); +.fi +.SH DESCRIPTION +.PP +The +.BR io_uring_wait_cqes (3) +function returns +.I wait_nr +IO completions from the queue belonging to the +.I ring +param, waiting for them if necessary or until the timeout +.I ts +expires. The +.I sigmask +specifies the set of signals to block. The prevailing signal mask is restored +before returning. + +The +.I cqe_ptr +param is filled in on success. + +If +.I ts +is specified and an older kernel without +.B IORING_FEAT_EXT_ARG +is used, the application does not need to call +.BR io_uring_submit (3) +before calling +.BR io_uring_wait_cqes (3). +For newer kernels with that feature flag set, there is no implied submit +when waiting for a request. + +.SH RETURN VALUE +On success +.BR io_uring_wait_cqes (3) +returns 0 and the cqe_ptr parm is filled in. On failure it returns +.BR -errno . +.SH SEE ALSO +.BR io_uring_submit (3), +.BR io_uring_wait_cqe_timeout (3), +.BR io_uring_wait_cqe (3) |