From nobody Sun Feb 11 01:54:39 2024 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4TXVyS5TKGz5966w; Sun, 11 Feb 2024 01:54:40 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4TXVyR54xTz4B3s; Sun, 11 Feb 2024 01:54:39 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1707616479; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=yhiAc4Sk51DTmTvnNpMToi8v+Z2goWMzG6gYmhJXcbc=; b=i21GYUcIjp3S4ojCHJYa+SW6yQxOYhqNY8fgB6AVHpoc50G8fwkbkkHddpI/7dQnYEzvK6 To9B7qMjLuhkKh8Da1f1HtDqmV2xVn8+Gc7fIfQBIx04ThsCFPjLktg2AUGpMIuD0IHb6T kSa0Glw1kvXdbGsGBH9sTkclegpDnvqoqVdwjUe2va4Q8tw78Fu8z7s0qLfk8C/CDtpo8K rAGb99JTAodgqRYDWH/x6SJSw+JRkKMtKor8+UdyOOTfPpZnUuilgjUFPP7GnF8gLdN8tC u+3VM4nrdFUguDS8JlDDzFgWF+aMOHBEVJgi4D3Juq7cFPIAdjoqib8xUfTY+w== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1707616479; a=rsa-sha256; cv=none; b=YMLldG2Yc9ShFyFkKJvM/09JDBUnAgTR5kXJPsDjqG5wlbnCf8Xm1VWMNwSo/rTU/v6Gq1 GeSBuqppehEqlMkUXMleOwZxtApUZ9VneMKurL/zZn7L3vFBSraEBhcnFWJTyxvfHiT9nO m/mmQOLYG1V6nGOUDUixkZ7lNswzrF6nZvmZg03w8DME4cvF8Tp9CL4drJRR+kQB8A2Uqj 5YbLovZbaJ0/VWlVgAWtf65FnB19UeGsSVSdo3KEtf/Z0WYHY+5mjM/FJLX0BIOjkHAYlO QI3ySMDzdLNmCHBrEY/DHlhh8o/0fCmpeyZTpxQ9sVmT6+8xYQGMZ6zFF7XJ5Q== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1707616479; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=yhiAc4Sk51DTmTvnNpMToi8v+Z2goWMzG6gYmhJXcbc=; b=KpH0leMXVCYZWBuW0/ncdXYd6YAQ8f7yieO3tD2m9FvBVdiGo3Wj1NcCNxuiy8/QNVT9gC IjRbjLnAAPLY8+/4h5zwAVZrO4Q1cAJBq4/vISFeKlYYaKKWwiOenwqAdzk+CGMigsCWM2 18cVKdOtPlwacEy4tIsK/11M2OF3iFn2ngvotHe9amMAzJQrH6swMZdgxjQPhItaSV+Y5b 9RYdjxNu0Ll3unpXvDVyC0BbROxQEZe2YbZG92Azifaze1fQjsTnGPZArEC+xwCiyFzu6s Yzd5rScOxHeoa59dstO/1Y/+iVsalMKjUO23jU9RbFW/mSEE5YIi6nYK51J0EQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4TXVyR3pYSzgNw; Sun, 11 Feb 2024 01:54:39 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.17.1/8.17.1) with ESMTP id 41B1sdYf090264; Sun, 11 Feb 2024 01:54:39 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 41B1sdiY090261; Sun, 11 Feb 2024 01:54:39 GMT (envelope-from git) Date: Sun, 11 Feb 2024 01:54:39 GMT Message-Id: <202402110154.41B1sdiY090261@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Konstantin Belousov Subject: git: a52cb4c480f2 - main - Document aio_read2/aio_write2 List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-main@freebsd.org X-BeenThere: dev-commits-src-main@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: kib X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: a52cb4c480f270fc7158a0f58179f7b80d8a5b3c Auto-Submitted: auto-generated The branch main has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=a52cb4c480f270fc7158a0f58179f7b80d8a5b3c commit a52cb4c480f270fc7158a0f58179f7b80d8a5b3c Author: Konstantin Belousov AuthorDate: 2024-02-03 18:12:59 +0000 Commit: Konstantin Belousov CommitDate: 2024-02-11 01:54:16 +0000 Document aio_read2/aio_write2 Reviewed by: jhb Discussed with: asomers Sponsored by: The FreeBSD Foundation MFC after: 1 week Differential revision: https://reviews.freebsd.org/D43448 --- lib/libsys/Makefile.sys | 6 ++-- lib/libsys/aio_read.2 | 79 +++++++++++++++++++++++++++++++++++++------------ lib/libsys/aio_write.2 | 78 ++++++++++++++++++++++++++++++++++++------------ 3 files changed, 123 insertions(+), 40 deletions(-) diff --git a/lib/libsys/Makefile.sys b/lib/libsys/Makefile.sys index f88a107f9eb8..b45aa3cf1aaf 100644 --- a/lib/libsys/Makefile.sys +++ b/lib/libsys/Makefile.sys @@ -383,8 +383,10 @@ MAN+= \ sleep.3 \ usleep.3 -MLINKS+=aio_read.2 aio_readv.2 -MLINKS+=aio_write.2 aio_writev.2 +MLINKS+=aio_read.2 aio_readv.2 \ + aio_read.2 aio_read2.2 +MLINKS+=aio_write.2 aio_writev.2 \ + aio_write.2 aio_write2.2 MLINKS+=accept.2 accept4.2 MLINKS+=access.2 eaccess.2 \ access.2 faccessat.2 diff --git a/lib/libsys/aio_read.2 b/lib/libsys/aio_read.2 index 092315e70c91..3a9601754c06 100644 --- a/lib/libsys/aio_read.2 +++ b/lib/libsys/aio_read.2 @@ -22,11 +22,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd November 15, 2023 +.Dd February 1, 2024 .Dt AIO_READ 2 .Os .Sh NAME .Nm aio_read , +.Nm aio_read2 , .Nm aio_readv .Nd asynchronous read from a file (REALTIME) .Sh LIBRARY @@ -35,21 +36,34 @@ .In aio.h .Ft int .Fn aio_read "struct aiocb *iocb" +.Ft int +.Fn aio_read2 "struct aiocb *iocb" "int flags" .In sys/uio.h .Ft int .Fn aio_readv "struct aiocb *iocb" .Sh DESCRIPTION The -.Fn aio_read +.Fn aio_read , +.Fn aio_read2 and .Fn aio_readv system calls allow the calling process to read from the descriptor -.Fa iocb->aio_fildes -beginning at the offset +.Fa iocb->aio_fildes . +The syscalls return immediately after the read request has +been enqueued to the descriptor; the read may or may not have +completed at the time the call returns. +.Pp +For the +.Fn aio_read +and +.Fn aio_readv +calls, the read begins at the offset .Fa iocb->aio_offset . +.Pp +The .Fn aio_read -will read +call will read .Fa iocb->aio_nbytes into the buffer pointed to by .Fa iocb->aio_buf , @@ -60,10 +74,6 @@ reads the data into the buffers specified by the members of the .Fa iocb->aio_iov array. -Both syscalls return immediately after the read request has -been enqueued to the descriptor; the read may or may not have -completed at the time the call returns. -.Pp For .Fn aio_readv the @@ -72,6 +82,33 @@ structure is defined in .Xr readv 2 . .Pp The +.Fn aio_read2 +call takes the +.Fa flags +argument. +If +.Fa flags +is passed as zero, the call behaves identically to +.Fn aio_read . +The following flags can be specified by logical or: +.Bl -tag -width AIO_OP2_VECTORED +.It AIO_OP2_FOFFSET +The read occurs at the file descriptor offset, +which is advanced by the operation as done by the +.Xr read 2 +syscall. +The +.Fa iocb->aio_offset +field is ignored. +.It AIO_OP2_VECTORED +Similar to +.Fn aio_readv , +the read buffers are specified by the +.Fa aiocb->aio_iov +array. +.El +.Pp +The .Fa iocb pointer may be subsequently used as an argument to .Fn aio_return @@ -103,9 +140,8 @@ operation has completed. .Pp The asynchronous I/O control buffer .Fa iocb -should be zeroed before the -.Fn aio_read -call to avoid passing bogus context information to the kernel. +should be zeroed before the system +calls to avoid passing bogus context information to the kernel. .Pp Modifications of the Asynchronous I/O Control Block structure or the buffer contents are not allowed while the request is queued. @@ -116,12 +152,13 @@ is past the offset maximum for .Fa iocb->aio_fildes , no I/O will occur. .Sh RETURN VALUES -.Rv -std aio_read aio_readv +.Rv -std aio_read aio_read2 aio_readv .Sh DIAGNOSTICS None. .Sh ERRORS The -.Fn aio_read +.Fn aio_read , +.Fn aio_read2 , and .Fn aio_readv system calls will fail if: @@ -149,10 +186,7 @@ or system call is made, or asynchronously, at any time thereafter. If they are detected at call time, -.Fn aio_read -or -.Fn aio_readv -returns -1 and sets +The calls return -1 and set .Va errno appropriately; otherwise the .Fn aio_return @@ -226,8 +260,11 @@ system call is expected to conform to the .St -p1003.1 standard. The +.Fn aio_read2 +and .Fn aio_readv -system call is a FreeBSD extension, and should not be used in portable code. +system calls are FreeBSD extensions, +and should not be used in portable code. .Sh HISTORY The .Fn aio_read @@ -237,6 +274,10 @@ The .Fn aio_readv system call first appeared in .Fx 13.0 . +The +.Fn aio_read2 +system call first appeared in +.Fx 14.1 . .Sh AUTHORS This manual page was written by diff --git a/lib/libsys/aio_write.2 b/lib/libsys/aio_write.2 index 32ad53019ed2..f59406b8ab36 100644 --- a/lib/libsys/aio_write.2 +++ b/lib/libsys/aio_write.2 @@ -22,11 +22,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd November 15, 2023 +.Dd February 1, 2024 .Dt AIO_WRITE 2 .Os .Sh NAME .Nm aio_write , +.Nm aio_write2 , .Nm aio_writev .Nd asynchronous write to a file (REALTIME) .Sh LIBRARY @@ -35,19 +36,27 @@ .In aio.h .Ft int .Fn aio_write "struct aiocb *iocb" +.Ft int +.Fn aio_write2 "struct aiocb *iocb" "int flags" .In sys/uio.h .Ft int .Fn aio_writev "struct aiocb *iocb" .Sh DESCRIPTION The -.Fn aio_write +.Fn aio_write , +.Fn aio_write2 , and .Fn aio_writev system calls allow the calling process to write to the descriptor .Fa iocb->aio_fildes . +The syscalls return immediately after the write request has been enqueued +to the descriptor; the write may or may not have completed at the time +the call returns. +.Pp +The .Fn aio_write -will write +call will write .Fa iocb->aio_nbytes from the buffer pointed to by .Fa iocb->aio_buf , @@ -58,9 +67,7 @@ gathers the data from the buffers specified by the members of the .Fa iocb->aio_iov array. -Both syscalls return immediately after the write request has been enqueued -to the descriptor; the write may or may not have completed at the time -the call returns. +.Pp If the request could not be enqueued, generally due to invalid arguments, the call returns without having enqueued the request. @@ -80,11 +87,42 @@ write operations append to the file in the same order as the calls were made. If .Dv O_APPEND -is not set for the file descriptor, the write operation will occur at +is not set for the file descriptor, the write operation for +.Fn aio_write +will occur at the absolute position from the beginning of the file plus .Fa iocb->aio_offset . .Pp The +.Fn aio_write2 +call takes the +.Fa flags +argument. +If +.Fa flags +is passed as zero, the call behaves identically to +.Fn aio_write . +The following flags can be specified by logical or: +.Bl -tag -width AIO_OP2_VECTORED +.It AIO_OP2_FOFFSET +The write for non +.Dv O_APPEND +file descriptors occurs at the file descriptor offset, +which is advanced by the operation as done by the +.Xr write 2 +syscall. +The +.Fa iocb->aio_offset +field is ignored. +.It AIO_OP2_VECTORED +Similar to +.Fn aio_writev , +the write buffers are specified by the +.Fa aiocb->aio_iov +array. +.El +.Pp +The .Fa iocb pointer may be subsequently used as an argument to .Fn aio_return @@ -114,10 +152,7 @@ operation has completed. The asynchronous I/O control buffer .Fa iocb should be zeroed before the -.Fn aio_write -or -.Fn aio_writev -system call to avoid passing bogus context information to the kernel. +system calls to avoid passing bogus context information to the kernel. .Pp Modifications of the Asynchronous I/O Control Block structure or the buffer contents are not allowed while the request is queued. @@ -131,7 +166,8 @@ no I/O will occur. .Rv -std aio_write aio_writev .Sh ERRORS The -.Fn aio_write +.Fn aio_write , +.Fn aio_write2 , and .Fn aio_writev system calls will fail if: @@ -153,16 +189,13 @@ are unsafe and unsafe asynchronous I/O operations are disabled. .El .Pp The following conditions may be synchronously detected when the -.Fn aio_write +.Fn aio_write , +.Fn aio_write2 , or .Fn aio_writev system call is made, or asynchronously, at any time thereafter. If they -are detected at call time, -.Fn aio_write -or -.Fn aio_writev -returns -1 and sets +are detected at call time, the calls return -1 and set .Va errno appropriately; otherwise the .Fn aio_return @@ -229,8 +262,11 @@ is expected to conform to the standard. .Pp The +.Fn aio_write2 +and .Fn aio_writev -system call is a FreeBSD extension, and should not be used in portable code. +system calls are FreeBSD extensions, +and should not be used in portable code. .Sh HISTORY The .Fn aio_write @@ -240,6 +276,10 @@ The .Fn aio_writev system call first appeared in .Fx 13.0 . +The +.Fn aio_write2 +system call first appeared in +.Fx 14.1 . .Sh AUTHORS This manual page was written by .An Wes Peters Aq Mt wes@softweyr.com .