man: add man page for io_uring_prep_socket()

Includes the _direct() variant as well.

Signed-off-by: Jens Axboe <axboe@kernel.dk>

2 files changed, 97 insertions, 0 deletions

diff --git a/man/io_uring_prep_socket.3 b/man/io_uring_prep_socket.3
new file mode 100644
index 0000000..41d33ec
--- /dev/null
+++ b/man/io_uring_prep_socket.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_socket 3 "May 27, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_socket  - prepare a socket creation request
+.fi
+.SH SYNOPSIS
+.nf
+.BR "#include <sys/socket.h>"
+.BR "#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 ");"
+.BI "
+.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 ");"
+.PP
+.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
+.I 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.
+
+This function prepares an async
+.BR socket (2)
+request. See that man page for details.
+
+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
+.B 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
+.I res.
+.B -ENFILE
+is otherwise returned if there is no free entries in the io_uring file table.
+
+.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
+.I errno.
+Instead it returns the negated
+.I errno
+directly in the CQE
+.I res
+field.
+.SH SEE ALSO
+.BR io_uring_get_sqe (3), io_uring_submit (3), 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