aio_write(2)

NAME

aio_write - asynchronous write to a file (REALTIME)

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <aio.h>
int
aio_write(struct aiocb *iocb);

DESCRIPTION

The aio_write() system call allows the calling process to

write

iocb->aio_nbytes from the buffer pointed to by iocb->aio_buf

to the

descriptor iocb->aio_fildes. The call returns 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. If the re

quest could

not be enqueued, generally due to invalid arguments, the

call returns

without having enqueued the request.

If O_APPEND is set for iocb->aio_fildes, aio_write() opera

tions append to

the file in the same order as the calls were made. If O_AP

PEND is not

set for the file descriptor, the write operation will occur

at the absolute position from the beginning of the file plus

iocb->aio_offset.

If _POSIX_PRIORITIZED_IO is defined, and the descriptor sup

ports it, then

the enqueued operation is submitted at a priority equal to

that of the

calling process minus iocb->aio_reqprio.

The iocb pointer may be subsequently used as an argument to

aio_return()

and aio_error() in order to determine return or error status

for the

enqueued operation while it is in progress.

If the request is successfully enqueued, the value of

iocb->aio_offset

can be modified during the request as context, so this value

must not be

referenced after the request is enqueued.

RESTRICTIONS

The Asynchronous I/O Control Block structure pointed to by

iocb and the

buffer that the iocb->aio_buf member of that structure ref

erences must

remain valid until the operation has completed. For this

reason, use of

auto (stack) variables for these objects is discouraged.

The asynchronous I/O control buffer iocb should be zeroed

before the

aio_write() system call to avoid passing bogus context in

formation to the

kernel.

Modifications of the Asynchronous I/O Control Block struc

ture or the

buffer contents after the request has been enqueued, but be

fore the

request has completed, are not allowed.

If the file offset in iocb->aio_offset is past the offset

maximum for

iocb->aio_fildes, no I/O will occur.

RETURN VALUES

The aio_write() function returns the value 0 if successful;

otherwise the

value -1 is returned and the global variable errno is set to

indicate the

error.

ERRORS

The aio_write() system call will fail if:

[EAGAIN] The request was not queued because of

system resource

limitations.

[ENOSYS] The aio_write() system call is not sup

ported.

The following conditions may be synchronously detected when

the

aio_write() system call is made, or asynchronously, at any

time thereafter. If they are detected at call time, aio_write() re

turns -1 and

sets errno appropriately; otherwise the aio_return() system

call must be

called, and will return -1, and aio_error() must be called

to determine

the actual value that would have been returned in errno.

[EBADF] The iocb->aio_fildes argument is invalid,

or is not

opened for writing.

[EINVAL] The offset iocb->aio_offset is not valid,

the priority

specified by iocb->aio_reqprio is not a

valid priority, or the number of bytes specified by

iocb->aio_nbytes is not valid.

If the request is successfully enqueued, but subsequently

canceled or an

error occurs, the value returned by the aio_return() system

call is per

the write(2) system call, and the value returned by the

aio_error() system call is either one of the error returns from the

write(2) system

call, or one of:

[EBADF] The iocb->aio_fildes argument is invalid

for writing.

[ECANCELED] The request was explicitly canceled via a

call to

aio_cancel().

[EINVAL] The offset iocb->aio_offset would be in

valid.

SEE ALSO

aio_cancel(2), aio_error(2), aio_return(2), aio_suspend(2),

STANDARDS

The aio_write() system call is expected to conform to the

IEEE Std 1003.1

(``POSIX.1'') standard.

HISTORY

The aio_write() system call first appeared in FreeBSD 3.0.

AUTHORS

This manual page was written by Wes Peters <wes@soft

weyr.com>.

BUGS

Invalid information in iocb->_aiocb_private may confuse the

kernel.

BSD June 2, 1999

BSD