| .TH io_submit 2 2002-09-02 "Linux 2.4" "Linux AIO" |
| .SH NAME |
| io_submit \- submit io requests |
| .SH SYNOPSIS |
| .B #include <errno.h> |
| .br |
| .B #include <libaio.h> |
| .LP |
| .BI "int io_submit(io_context_t " ctx ", long " nr ", struct iocb *" iocbs "[]);" |
| .SH DESCRIPTION |
| .B io_submit |
| submits to the io_context |
| .I ctx |
| up to |
| .I nr |
| I/O requests pointed to by the vector |
| .IR iocbs . |
| |
| The |
| .B iocb |
| structure is defined as something like |
| .sp |
| .RS |
| .nf |
| struct iocb { |
| void *data; |
| .\" unsigned key; |
| short aio_lio_opcode; |
| short aio_reqprio; |
| int aio_fildes; |
| }; |
| .fi |
| .RE |
| .sp |
| .I data |
| is a an opaque pointer which will upon completion be returned in the |
| .B io_event |
| structure by |
| .BR io_getevents (2). |
| .\" and io_wait(2) |
| Callers will typically use this to point directly or indirectly to a |
| callback function. |
| .sp |
| .I aio_lio_opcode |
| is the I/O operation requested. Callers will typically set this and the |
| arguments to the I/O operation calling the |
| .BR io_prep_ (3) |
| function corresponding to the operation. |
| .sp |
| .I aio_reqprio |
| is the priority of the request. Higher values have more priority; the |
| normal priority is 0. |
| .sp |
| .I aio_fildes |
| is the file descriptor for the I/O operation. |
| Callers will typically set this and the |
| arguments to the I/O operation calling the |
| .BR io_prep_ *(3) |
| function corresponding to the operation. |
| .sp |
| The caller may not modify the contents or resubmit a submitted |
| .B iocb |
| structure until after the operation completes or is canceled. |
| The implementation of |
| .BR io_submit (2) |
| is permitted to modify reserved fields of the |
| .B iocb |
| structure. |
| .SH "RETURN VALUES" |
| If able to submit at least one iocb, |
| .B io_submit |
| returns the number of iocbs submitted successfully. Otherwise, |
| .RI - error |
| is returned, where |
| .I error |
| is one of the Exxx values defined in the Errors section. |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| .I iocbs |
| referenced data outside of the program's accessible address space. |
| .TP |
| .B EINVAL |
| .I nr |
| is negative, |
| .I ctx |
| refers to an uninitialized aio context, the iocb pointed to by |
| .IR iocbs [0] |
| is improperly initialized or specifies an unsupported operation. |
| .TP |
| .B EBADF |
| The iocb pointed to by |
| .IR iocbs [0] |
| contains a file descriptor that does not exist. |
| .TP |
| .B EAGAIN |
| Insufficient resources were available to queue any operations. |
| .SH "SEE ALSO" |
| .BR io_setup (2), |
| .BR io_destroy (2), |
| .BR io_getevents (2), |
| .\".BR io_wait (2), |
| .BR io_prep_pread (3), |
| .BR io_prep_pwrite (3), |
| .BR io_prep_fsync (3), |
| .BR io_prep_fdsync (3), |
| .BR io_prep_noop (3), |
| .BR io_cancel (2), |
| .BR errno (3) |
