summaryrefslogtreecommitdiffstats
path: root/man3/aio_read.3
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:40:15 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:40:15 +0000
commit399644e47874bff147afb19c89228901ac39340e (patch)
tree1c4c0b733f4c16b5783b41bebb19194a9ef62ad1 /man3/aio_read.3
parentInitial commit. (diff)
downloadmanpages-399644e47874bff147afb19c89228901ac39340e.tar.xz
manpages-399644e47874bff147afb19c89228901ac39340e.zip
Adding upstream version 6.05.01.upstream/6.05.01
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man3/aio_read.3')
-rw-r--r--man3/aio_read.3160
1 files changed, 160 insertions, 0 deletions
diff --git a/man3/aio_read.3 b/man3/aio_read.3
new file mode 100644
index 0000000..909d444
--- /dev/null
+++ b/man3/aio_read.3
@@ -0,0 +1,160 @@
+'\" t
+.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH aio_read 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+aio_read \- asynchronous read
+.SH LIBRARY
+Real-time library
+.RI ( librt ", " \-lrt )
+.SH SYNOPSIS
+.nf
+.B "#include <aio.h>"
+.PP
+.BI "int aio_read(struct aiocb *" aiocbp );
+.fi
+.SH DESCRIPTION
+The
+.BR aio_read ()
+function queues the I/O request described by the buffer pointed to by
+.IR aiocbp .
+This function is the asynchronous analog of
+.BR read (2).
+The arguments of the call
+.PP
+.in +4n
+.EX
+read(fd, buf, count)
+.EE
+.in
+.PP
+correspond (in order) to the fields
+.IR aio_fildes ,
+.IR aio_buf ,
+and
+.I aio_nbytes
+of the structure pointed to by
+.IR aiocbp .
+(See
+.BR aio (7)
+for a description of the
+.I aiocb
+structure.)
+.PP
+The data is read starting at the absolute position
+.IR aiocbp\->aio_offset ,
+regardless of the file offset.
+After the call,
+the value of the file offset is unspecified.
+.PP
+The "asynchronous" means that this call returns as soon as the
+request has been enqueued; the read may or may not have completed
+when the call returns.
+One tests for completion using
+.BR aio_error (3).
+The return status of a completed I/O operation can be obtained by
+.BR aio_return (3).
+Asynchronous notification of I/O completion can be obtained by setting
+.I aiocbp\->aio_sigevent
+appropriately; see
+.BR sigevent (7)
+for details.
+.PP
+If
+.B _POSIX_PRIORITIZED_IO
+is defined, and this file supports it,
+then the asynchronous operation is submitted at a priority equal
+to that of the calling process minus
+.IR aiocbp\->aio_reqprio .
+.PP
+The field
+.I aiocbp\->aio_lio_opcode
+is ignored.
+.PP
+No data is read from a regular file beyond its maximum offset.
+.SH RETURN VALUE
+On success, 0 is returned.
+On error, the request is not enqueued, \-1
+is returned, and
+.I errno
+is set to indicate the error.
+If an error is detected only later, it will
+be reported via
+.BR aio_return (3)
+(returns status \-1) and
+.BR aio_error (3)
+(error status\[em]whatever one would have gotten in
+.IR errno ,
+such as
+.BR EBADF ).
+.SH ERRORS
+.TP
+.B EAGAIN
+Out of resources.
+.TP
+.B EBADF
+.I aio_fildes
+is not a valid file descriptor open for reading.
+.TP
+.B EINVAL
+One or more of
+.IR aio_offset ,
+.IR aio_reqprio ,
+or
+.I aio_nbytes
+are invalid.
+.TP
+.B ENOSYS
+.BR aio_read ()
+is not implemented.
+.TP
+.B EOVERFLOW
+The file is a regular file, we start reading before end-of-file
+and want at least one byte, but the starting position is past
+the maximum offset for this file.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR aio_read ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+glibc 2.1.
+POSIX.1-2001.
+.SH NOTES
+It is a good idea to zero out the control block before use.
+The control block must not be changed while the read operation
+is in progress.
+The buffer area being read into
+.\" or the control block of the operation
+must not be accessed during the operation or undefined results may occur.
+The memory areas involved must remain valid.
+.PP
+Simultaneous I/O operations specifying the same
+.I aiocb
+structure produce undefined results.
+.SH EXAMPLES
+See
+.BR aio (7).
+.SH SEE ALSO
+.BR aio_cancel (3),
+.BR aio_error (3),
+.BR aio_fsync (3),
+.BR aio_return (3),
+.BR aio_suspend (3),
+.BR aio_write (3),
+.BR lio_listio (3),
+.BR aio (7)