mirror of
https://github.com/freebsd/freebsd-src
synced 2024-10-15 12:54:27 +00:00
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
This commit is contained in:
parent
8dfc788b84
commit
a52cb4c480
|
@ -383,8 +383,10 @@ MAN+= \
|
||||||
sleep.3 \
|
sleep.3 \
|
||||||
usleep.3
|
usleep.3
|
||||||
|
|
||||||
MLINKS+=aio_read.2 aio_readv.2
|
MLINKS+=aio_read.2 aio_readv.2 \
|
||||||
MLINKS+=aio_write.2 aio_writev.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+=accept.2 accept4.2
|
||||||
MLINKS+=access.2 eaccess.2 \
|
MLINKS+=access.2 eaccess.2 \
|
||||||
access.2 faccessat.2
|
access.2 faccessat.2
|
||||||
|
|
|
@ -22,11 +22,12 @@
|
||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||||
.\" SUCH DAMAGE.
|
.\" SUCH DAMAGE.
|
||||||
.\"
|
.\"
|
||||||
.Dd November 15, 2023
|
.Dd February 1, 2024
|
||||||
.Dt AIO_READ 2
|
.Dt AIO_READ 2
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
.Nm aio_read ,
|
.Nm aio_read ,
|
||||||
|
.Nm aio_read2 ,
|
||||||
.Nm aio_readv
|
.Nm aio_readv
|
||||||
.Nd asynchronous read from a file (REALTIME)
|
.Nd asynchronous read from a file (REALTIME)
|
||||||
.Sh LIBRARY
|
.Sh LIBRARY
|
||||||
|
@ -35,21 +36,34 @@
|
||||||
.In aio.h
|
.In aio.h
|
||||||
.Ft int
|
.Ft int
|
||||||
.Fn aio_read "struct aiocb *iocb"
|
.Fn aio_read "struct aiocb *iocb"
|
||||||
|
.Ft int
|
||||||
|
.Fn aio_read2 "struct aiocb *iocb" "int flags"
|
||||||
.In sys/uio.h
|
.In sys/uio.h
|
||||||
.Ft int
|
.Ft int
|
||||||
.Fn aio_readv "struct aiocb *iocb"
|
.Fn aio_readv "struct aiocb *iocb"
|
||||||
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
||||||
The
|
The
|
||||||
.Fn aio_read
|
.Fn aio_read ,
|
||||||
|
.Fn aio_read2
|
||||||
and
|
and
|
||||||
.Fn aio_readv
|
.Fn aio_readv
|
||||||
system calls allow the calling process to read
|
system calls allow the calling process to read
|
||||||
from the descriptor
|
from the descriptor
|
||||||
.Fa iocb->aio_fildes
|
.Fa iocb->aio_fildes .
|
||||||
beginning at the offset
|
The syscalls return immediately after the read request has
|
||||||
.Fa iocb->aio_offset .
|
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
|
.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
|
.Fa iocb->aio_nbytes
|
||||||
into the buffer pointed to by
|
into the buffer pointed to by
|
||||||
.Fa iocb->aio_buf ,
|
.Fa iocb->aio_buf ,
|
||||||
|
@ -60,10 +74,6 @@ reads the data into the
|
||||||
buffers specified by the members of the
|
buffers specified by the members of the
|
||||||
.Fa iocb->aio_iov
|
.Fa iocb->aio_iov
|
||||||
array.
|
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
|
For
|
||||||
.Fn aio_readv
|
.Fn aio_readv
|
||||||
the
|
the
|
||||||
|
@ -72,6 +82,33 @@ structure is defined in
|
||||||
.Xr readv 2 .
|
.Xr readv 2 .
|
||||||
.Pp
|
.Pp
|
||||||
The
|
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
|
.Fa iocb
|
||||||
pointer may be subsequently used as an argument to
|
pointer may be subsequently used as an argument to
|
||||||
.Fn aio_return
|
.Fn aio_return
|
||||||
|
@ -103,9 +140,8 @@ operation has completed.
|
||||||
.Pp
|
.Pp
|
||||||
The asynchronous I/O control buffer
|
The asynchronous I/O control buffer
|
||||||
.Fa iocb
|
.Fa iocb
|
||||||
should be zeroed before the
|
should be zeroed before the system
|
||||||
.Fn aio_read
|
calls to avoid passing bogus context information to the kernel.
|
||||||
call to avoid passing bogus context information to the kernel.
|
|
||||||
.Pp
|
.Pp
|
||||||
Modifications of the Asynchronous I/O Control Block structure or the
|
Modifications of the Asynchronous I/O Control Block structure or the
|
||||||
buffer contents are not allowed while the request is queued.
|
buffer contents are not allowed while the request is queued.
|
||||||
|
@ -116,12 +152,13 @@ is past the offset maximum for
|
||||||
.Fa iocb->aio_fildes ,
|
.Fa iocb->aio_fildes ,
|
||||||
no I/O will occur.
|
no I/O will occur.
|
||||||
.Sh RETURN VALUES
|
.Sh RETURN VALUES
|
||||||
.Rv -std aio_read aio_readv
|
.Rv -std aio_read aio_read2 aio_readv
|
||||||
.Sh DIAGNOSTICS
|
.Sh DIAGNOSTICS
|
||||||
None.
|
None.
|
||||||
.Sh ERRORS
|
.Sh ERRORS
|
||||||
The
|
The
|
||||||
.Fn aio_read
|
.Fn aio_read ,
|
||||||
|
.Fn aio_read2 ,
|
||||||
and
|
and
|
||||||
.Fn aio_readv
|
.Fn aio_readv
|
||||||
system calls will fail if:
|
system calls will fail if:
|
||||||
|
@ -149,10 +186,7 @@ or
|
||||||
system call is made, or asynchronously, at any time thereafter.
|
system call is made, or asynchronously, at any time thereafter.
|
||||||
If they
|
If they
|
||||||
are detected at call time,
|
are detected at call time,
|
||||||
.Fn aio_read
|
The calls return -1 and set
|
||||||
or
|
|
||||||
.Fn aio_readv
|
|
||||||
returns -1 and sets
|
|
||||||
.Va errno
|
.Va errno
|
||||||
appropriately; otherwise the
|
appropriately; otherwise the
|
||||||
.Fn aio_return
|
.Fn aio_return
|
||||||
|
@ -226,8 +260,11 @@ system call is expected to conform to the
|
||||||
.St -p1003.1
|
.St -p1003.1
|
||||||
standard.
|
standard.
|
||||||
The
|
The
|
||||||
|
.Fn aio_read2
|
||||||
|
and
|
||||||
.Fn aio_readv
|
.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
|
.Sh HISTORY
|
||||||
The
|
The
|
||||||
.Fn aio_read
|
.Fn aio_read
|
||||||
|
@ -237,6 +274,10 @@ The
|
||||||
.Fn aio_readv
|
.Fn aio_readv
|
||||||
system call first appeared in
|
system call first appeared in
|
||||||
.Fx 13.0 .
|
.Fx 13.0 .
|
||||||
|
The
|
||||||
|
.Fn aio_read2
|
||||||
|
system call first appeared in
|
||||||
|
.Fx 14.1 .
|
||||||
.Sh AUTHORS
|
.Sh AUTHORS
|
||||||
This
|
This
|
||||||
manual page was written by
|
manual page was written by
|
||||||
|
|
|
@ -22,11 +22,12 @@
|
||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||||
.\" SUCH DAMAGE.
|
.\" SUCH DAMAGE.
|
||||||
.\"
|
.\"
|
||||||
.Dd November 15, 2023
|
.Dd February 1, 2024
|
||||||
.Dt AIO_WRITE 2
|
.Dt AIO_WRITE 2
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
.Nm aio_write ,
|
.Nm aio_write ,
|
||||||
|
.Nm aio_write2 ,
|
||||||
.Nm aio_writev
|
.Nm aio_writev
|
||||||
.Nd asynchronous write to a file (REALTIME)
|
.Nd asynchronous write to a file (REALTIME)
|
||||||
.Sh LIBRARY
|
.Sh LIBRARY
|
||||||
|
@ -35,19 +36,27 @@
|
||||||
.In aio.h
|
.In aio.h
|
||||||
.Ft int
|
.Ft int
|
||||||
.Fn aio_write "struct aiocb *iocb"
|
.Fn aio_write "struct aiocb *iocb"
|
||||||
|
.Ft int
|
||||||
|
.Fn aio_write2 "struct aiocb *iocb" "int flags"
|
||||||
.In sys/uio.h
|
.In sys/uio.h
|
||||||
.Ft int
|
.Ft int
|
||||||
.Fn aio_writev "struct aiocb *iocb"
|
.Fn aio_writev "struct aiocb *iocb"
|
||||||
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
||||||
The
|
The
|
||||||
.Fn aio_write
|
.Fn aio_write ,
|
||||||
|
.Fn aio_write2 ,
|
||||||
and
|
and
|
||||||
.Fn aio_writev
|
.Fn aio_writev
|
||||||
system calls allow the calling process to write
|
system calls allow the calling process to write
|
||||||
to the descriptor
|
to the descriptor
|
||||||
.Fa iocb->aio_fildes .
|
.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
|
.Fn aio_write
|
||||||
will write
|
call will write
|
||||||
.Fa iocb->aio_nbytes
|
.Fa iocb->aio_nbytes
|
||||||
from the buffer pointed to by
|
from the buffer pointed to by
|
||||||
.Fa iocb->aio_buf ,
|
.Fa iocb->aio_buf ,
|
||||||
|
@ -58,9 +67,7 @@ gathers the data from the
|
||||||
buffers specified by the members of the
|
buffers specified by the members of the
|
||||||
.Fa iocb->aio_iov
|
.Fa iocb->aio_iov
|
||||||
array.
|
array.
|
||||||
Both syscalls return immediately after the write request has been enqueued
|
.Pp
|
||||||
to the descriptor; the write may or may not have completed at the time
|
|
||||||
the call returns.
|
|
||||||
If the request could not be enqueued, generally due
|
If the request could not be enqueued, generally due
|
||||||
to invalid arguments, the call returns without having enqueued the
|
to invalid arguments, the call returns without having enqueued the
|
||||||
request.
|
request.
|
||||||
|
@ -80,11 +87,42 @@ write operations append to the file in the same order as the calls were
|
||||||
made.
|
made.
|
||||||
If
|
If
|
||||||
.Dv O_APPEND
|
.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
|
the absolute position from the beginning of the file plus
|
||||||
.Fa iocb->aio_offset .
|
.Fa iocb->aio_offset .
|
||||||
.Pp
|
.Pp
|
||||||
The
|
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
|
.Fa iocb
|
||||||
pointer may be subsequently used as an argument to
|
pointer may be subsequently used as an argument to
|
||||||
.Fn aio_return
|
.Fn aio_return
|
||||||
|
@ -114,10 +152,7 @@ operation has completed.
|
||||||
The asynchronous I/O control buffer
|
The asynchronous I/O control buffer
|
||||||
.Fa iocb
|
.Fa iocb
|
||||||
should be zeroed before the
|
should be zeroed before the
|
||||||
.Fn aio_write
|
system calls to avoid passing bogus context information to the kernel.
|
||||||
or
|
|
||||||
.Fn aio_writev
|
|
||||||
system call to avoid passing bogus context information to the kernel.
|
|
||||||
.Pp
|
.Pp
|
||||||
Modifications of the Asynchronous I/O Control Block structure or the
|
Modifications of the Asynchronous I/O Control Block structure or the
|
||||||
buffer contents are not allowed while the request is queued.
|
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
|
.Rv -std aio_write aio_writev
|
||||||
.Sh ERRORS
|
.Sh ERRORS
|
||||||
The
|
The
|
||||||
.Fn aio_write
|
.Fn aio_write ,
|
||||||
|
.Fn aio_write2 ,
|
||||||
and
|
and
|
||||||
.Fn aio_writev
|
.Fn aio_writev
|
||||||
system calls will fail if:
|
system calls will fail if:
|
||||||
|
@ -153,16 +189,13 @@ are unsafe and unsafe asynchronous I/O operations are disabled.
|
||||||
.El
|
.El
|
||||||
.Pp
|
.Pp
|
||||||
The following conditions may be synchronously detected when the
|
The following conditions may be synchronously detected when the
|
||||||
.Fn aio_write
|
.Fn aio_write ,
|
||||||
|
.Fn aio_write2 ,
|
||||||
or
|
or
|
||||||
.Fn aio_writev
|
.Fn aio_writev
|
||||||
system call is made, or asynchronously, at any time thereafter.
|
system call is made, or asynchronously, at any time thereafter.
|
||||||
If they
|
If they
|
||||||
are detected at call time,
|
are detected at call time, the calls return -1 and set
|
||||||
.Fn aio_write
|
|
||||||
or
|
|
||||||
.Fn aio_writev
|
|
||||||
returns -1 and sets
|
|
||||||
.Va errno
|
.Va errno
|
||||||
appropriately; otherwise the
|
appropriately; otherwise the
|
||||||
.Fn aio_return
|
.Fn aio_return
|
||||||
|
@ -229,8 +262,11 @@ is expected to conform to the
|
||||||
standard.
|
standard.
|
||||||
.Pp
|
.Pp
|
||||||
The
|
The
|
||||||
|
.Fn aio_write2
|
||||||
|
and
|
||||||
.Fn aio_writev
|
.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
|
.Sh HISTORY
|
||||||
The
|
The
|
||||||
.Fn aio_write
|
.Fn aio_write
|
||||||
|
@ -240,6 +276,10 @@ The
|
||||||
.Fn aio_writev
|
.Fn aio_writev
|
||||||
system call first appeared in
|
system call first appeared in
|
||||||
.Fx 13.0 .
|
.Fx 13.0 .
|
||||||
|
The
|
||||||
|
.Fn aio_write2
|
||||||
|
system call first appeared in
|
||||||
|
.Fx 14.1 .
|
||||||
.Sh AUTHORS
|
.Sh AUTHORS
|
||||||
This manual page was written by
|
This manual page was written by
|
||||||
.An Wes Peters Aq Mt wes@softweyr.com .
|
.An Wes Peters Aq Mt wes@softweyr.com .
|
||||||
|
|
Loading…
Reference in a new issue