system/freebsd-src
system/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src synced 2024-07-09 04:36:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document aio_read2/aio_write2

Browse Source 
Reviewed by:	jhb
Discussed with:	asomers
Sponsored by:	The FreeBSD Foundation
MFC after:	1 week
Differential revision:	https://reviews.freebsd.org/D43448
This commit is contained in:
Konstantin Belousov 2024-02-03 20:12:59 +02:00
parent 8dfc788b84
commit a52cb4c480
3 changed files with 124 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
lib/libsys/Makefile.sys
View File

@ -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

81
lib/libsys/aio_read.2
View File

@ -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_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
will read
and
.Fn aio_readv
calls, the read begins at the offset
.Fa iocb->aio_offset .
.Pp
The
.Fn aio_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

78
lib/libsys/aio_write.2
View File

@ -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 .