Page MenuHomeFreeBSD
Differential D27624 Diff 80884 lib/libc/sys/aio_write.2

Changeset View

Standalone View

View Options

lib/libc/sys/aio_write.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 November 29, 2020
.Dt AIO_WRITE 2 .Dt AIO_WRITE 2
.Os .Os
.Sh NAME .Sh NAME
.Nm aio_write .Nm aio_write ,
.Nm aio_writev
.Nd asynchronous write to a file (REALTIME) .Nd asynchronous write to 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_write "struct aiocb *iocb" .Fn aio_write "struct aiocb *iocb"
.Ft int
.Fn aio_writev "struct aiocb *iocb"
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Fn aio_write .Fn aio_write
system call allows the calling process to write and
.Fa iocb->aio_nbytes .Fn aio_writev
from the buffer pointed to by system calls allow the calling process to write
.Fa iocb->aio_buf
to the descriptor to the descriptor
.Fa iocb->aio_fildes . .Fa iocb->aio_fildes .
The call returns immediately after the write request has been enqueued .Fn aio_write
will write
.Fa iocb->aio_nbytes
from the buffer pointed to by
.Fa iocb->aio_buf ,
whereas
.Fn aio_writev
gathers the data from the
.Fa iocb->aio_iovcnt
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 to the descriptor; the write may or may not have completed at the time
the call returns. 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.
.Pp .Pp
For
jhbUnsubmitted
Done
Inline Actions

I think you can Xr writev(2) here for the description of struct iovec instead of duplicating it. Regardless of which approach, aio_readv(2) and aio_writev(2) should be consistent.

jhb: I think you can Xr writev(2) here for the description of `struct iovec` instead of duplicating…
.Fn aio_writev
the
.Fa iovec
structure is defined in
.Xr writev 2 .
.Pp
If If
.Dv O_APPEND .Dv O_APPEND
is set for is set for
.Fa iocb->aio_fildes , .Fa iocb->aio_fildes ,
.Fn aio_write write operations append to the file in the same order as the calls were
jhbUnsubmitted
Done
Inline Actions

Maybe "write operations append to the file..."?

jhb: Maybe "write operations append to the file..."?
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 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
If If
bcrUnsubmitted
Done
Inline Actions

No need for an extra line break here, continue to write after "system call".

bcr: No need for an extra line break here, continue to write after "system call".
.Dv _POSIX_PRIORITIZED_IO .Dv _POSIX_PRIORITIZED_IO
is defined, and the descriptor supports it, then the enqueued is defined, and the descriptor supports it, then the enqueued
operation is submitted at a priority equal to that of the calling operation is submitted at a priority equal to that of the calling
process minus process minus
.Fa iocb->aio_reqprio . .Fa iocb->aio_reqprio .
.Pp .Pp
The The
.Fa iocb .Fa iocb
Show All 21 Lines
.Fa iocb->aio_buf .Fa iocb->aio_buf
member of that structure references must remain valid until the member of that structure references must remain valid until the
operation has completed. 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
.Fn aio_write .Fn aio_write
or
.Fn aio_writev
system call to avoid passing bogus context information to the kernel. 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.
.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_write .Rv -std aio_write aio_writev
.Sh ERRORS .Sh ERRORS
The The
.Fn aio_write .Fn aio_write
system call will fail if: and
.Fn aio_writev
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 write operations on the file descriptor Asynchronous write 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_write .Fn aio_write
or
.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,
.Fn aio_write .Fn aio_write
or
.Fn aio_writev
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 49 Lines • ▼ Show 20 Lines
.Xr aio 4 .Xr aio 4
.Sh STANDARDS .Sh STANDARDS
The The
.Fn aio_write .Fn aio_write
system call system call
is expected to conform to the is expected to conform to the
.St -p1003.1 .St -p1003.1
standard. standard.
.Pp
The
.Fn aio_writev
system call is a FreeBSD extension, and should not be used in portable code.
.Sh HISTORY .Sh HISTORY
The The
.Fn aio_write .Fn aio_write
system call first appeared in system call first appeared in
.Fx 3.0 . .Fx 3.0 .
The
.Fn aio_writev
system call first appeared in
.Fx 13.0 .
.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 .
.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.