Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/sys/aio_read.2
Show All 18 Lines | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" 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. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd August 19, 2016 | .Dd December 13, 2020 | ||||
.Dt AIO_READ 2 | .Dt AIO_READ 2 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm aio_read | .Nm aio_read , | ||||
.Nm aio_readv | |||||
.Nd asynchronous read from a file (REALTIME) | .Nd asynchronous read from a file (REALTIME) | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libc | .Lb libc | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.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_readv "struct aiocb *iocb" | |||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Fn aio_read | .Fn aio_read | ||||
system call allows the calling process to read | and | ||||
.Fa iocb->aio_nbytes | .Fn aio_readv | ||||
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 | beginning at the offset | ||||
.Fa iocb->aio_offset | .Fa iocb->aio_offset . | ||||
into the buffer pointed to by | .Fn aio_read | ||||
.Fa iocb->aio_buf . | will read | ||||
The call returns immediately after the read request has | .Fa iocb->aio_nbytes | ||||
from the buffer pointed to by | |||||
.Fa iocb->aio_buf , | |||||
whereas | |||||
.Fn aio_readv | |||||
reads the data into the | |||||
.Fa iocb->aio_iovcnt | |||||
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 | been enqueued to the descriptor; the read may or may not have | ||||
completed at the time the call returns. | completed at the time the call returns. | ||||
.Pp | .Pp | ||||
For | |||||
.Fn aio_readv | |||||
the | |||||
.Fa iovec | |||||
structure is defined in | |||||
.Xr readv 2 . | |||||
.Pp | |||||
If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it, | If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it, | ||||
then the enqueued operation is submitted at a priority equal to that | then the enqueued operation is submitted at a priority equal to that | ||||
of the calling process minus | of the calling process minus | ||||
.Fa iocb->aio_reqprio . | .Fa iocb->aio_reqprio . | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fa iocb->aio_lio_opcode | .Fa iocb->aio_lio_opcode | ||||
argument | argument | ||||
is ignored by the | is ignored by the | ||||
.Fn aio_read | .Fn aio_read | ||||
system call. | and | ||||
.Fn aio_readv | |||||
system calls. | |||||
.Pp | .Pp | ||||
The | 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 | ||||
and | and | ||||
.Fn aio_error | .Fn aio_error | ||||
in order to determine return or error status for the enqueued operation | in order to determine return or error status for the enqueued operation | ||||
Show All 30 Lines | |||||
buffer contents are not allowed while the request is queued. | buffer contents are not allowed while the request is queued. | ||||
.Pp | .Pp | ||||
If the file offset in | If the file offset in | ||||
.Fa iocb->aio_offset | .Fa iocb->aio_offset | ||||
is past the offset maximum for | 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 | .Rv -std aio_read aio_readv | ||||
.Sh DIAGNOSTICS | .Sh DIAGNOSTICS | ||||
None. | None. | ||||
.Sh ERRORS | .Sh ERRORS | ||||
The | The | ||||
.Fn aio_read | .Fn aio_read | ||||
system call will fail if: | and | ||||
.Fn aio_readv | |||||
system calls will fail if: | |||||
.Bl -tag -width Er | .Bl -tag -width Er | ||||
.It Bq Er EAGAIN | .It Bq Er EAGAIN | ||||
The request was not queued because of system resource limitations. | The request was not queued because of system resource limitations. | ||||
.It Bq Er EINVAL | .It Bq Er EINVAL | ||||
The asynchronous notification method in | The asynchronous notification method in | ||||
.Fa iocb->aio_sigevent.sigev_notify | .Fa iocb->aio_sigevent.sigev_notify | ||||
is invalid or not supported. | is invalid or not supported. | ||||
.It Bq Er EOPNOTSUPP | .It Bq Er EOPNOTSUPP | ||||
Asynchronous read operations on the file descriptor | Asynchronous read operations on the file descriptor | ||||
.Fa iocb->aio_fildes | .Fa iocb->aio_fildes | ||||
are unsafe and unsafe asynchronous I/O operations are disabled. | 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_read | .Fn aio_read | ||||
or | |||||
.Fn aio_readv | |||||
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 | .Fn aio_read | ||||
or | |||||
.Fn aio_readv | |||||
returns -1 and sets | returns -1 and sets | ||||
.Va errno | .Va errno | ||||
appropriately; otherwise the | appropriately; otherwise the | ||||
.Fn aio_return | .Fn aio_return | ||||
system call must be called, and will return -1, and | system call must be called, and will return -1, and | ||||
.Fn aio_error | .Fn aio_error | ||||
must be called to determine the actual value that would have been | must be called to determine the actual value that would have been | ||||
returned in | returned in | ||||
▲ Show 20 Lines • Show All 57 Lines • ▼ Show 20 Lines | |||||
.Xr siginfo 3 , | .Xr siginfo 3 , | ||||
.Xr aio 4 | .Xr aio 4 | ||||
.Sh STANDARDS | .Sh STANDARDS | ||||
The | The | ||||
.Fn aio_read | .Fn aio_read | ||||
system call is expected to conform to the | system call is expected to conform to the | ||||
.St -p1003.1 | .St -p1003.1 | ||||
standard. | standard. | ||||
The | |||||
.Fn aio_readv | |||||
system call is a FreeBSD extension, and should not be used in portable code. | |||||
.Sh HISTORY | .Sh HISTORY | ||||
The | The | ||||
.Fn aio_read | .Fn aio_read | ||||
system call first appeared in | system call first appeared in | ||||
.Fx 3.0 . | .Fx 3.0 . | ||||
The | |||||
.Fn aio_readv | |||||
system call first appeared in | |||||
.Fx 13.0 . | |||||
.Sh AUTHORS | .Sh AUTHORS | ||||
This | This | ||||
manual page was written by | manual page was written by | ||||
.An Terry Lambert Aq Mt terry@whistle.com . | .An Terry Lambert Aq Mt terry@whistle.com . | ||||
.Sh BUGS | .Sh BUGS | ||||
Invalid information in | Invalid information in | ||||
.Fa iocb->_aiocb_private | .Fa iocb->_aiocb_private | ||||
may confuse the kernel. | may confuse the kernel. |