| .\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> |
| .\" |
| .\" SPDX-License-Identifier: LGPL-2.0-or-later |
| .\" |
| .TH io_uring_prep_msg_ring 3 "Mar 16, 2023" "liburing-2.4" "liburing Manual" |
| .SH NAME |
| io_uring_prep_msg_ring_fd \- send a direct descriptor to another ring |
| .SH SYNOPSIS |
| .nf |
| .B #include <liburing.h> |
| .PP |
| .BI "void io_uring_prep_msg_ring_fd(struct io_uring_sqe *" sqe "," |
| .BI " int " fd "," |
| .BI " int " source_fd "," |
| .BI " int " target_fd "," |
| .BI " __u64 " data "," |
| .BI " unsigned int " flags ");" |
| .PP |
| .BI "void io_uring_prep_msg_ring_fd_alloc(struct io_uring_sqe *" sqe "," |
| .BI " int " fd "," |
| .BI " int " source_fd "," |
| .BI " __u64 " data "," |
| .BI " unsigned int " flags ");" |
| .fi |
| .SH DESCRIPTION |
| .PP |
| .BR io_uring_prep_msg_ring_fd (3) |
| prepares an SQE to send a direct file descriptor to another ring. The submission |
| queue entry |
| .I sqe |
| is setup to use the file descriptor |
| .IR fd , |
| which must identify a target io_uring context, to send the locally registered |
| file descriptor with value |
| .I source_fd |
| to the destination ring into index |
| .I target_fd |
| and passing |
| .I data |
| as the user data in the target CQE with the request modifier flags set by |
| .IR flags . |
| Currently there are no valid flag modifiers, this field must contain |
| .BR 0 . |
| |
| .BR io_uring_prep_msg_ring_fd_alloc (3) |
| is similar to |
| .BR io_uring_prep_msg_ring_fd (3) , |
| but doesn't specify a target index for the direct descriptor. Instead, this |
| index is allocated in the target ring and returned in the CQE |
| .IR res |
| field. |
| |
| .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 -EINVAL |
| Target ring is identical to the source ring. |
| .TP |
| .B -EBADFD |
| The descriptor passed in |
| .I fd |
| does not refer to an io_uring file descriptor, or the ring is in a disabled |
| state. |
| .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. |
| .TP |
| .B -ENFILE |
| The direct descriptor table in the target ring was full, no new descriptors |
| could be successfully allocated. |
