| .\" 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) |