IO_SUBMIT - Linux手册页

时间:2019-08-20 17:58:53  来源:igfitidea点击:

Linux程序员手册 第2部分
更新日期: 2020-04-11

名称

io_submit-提交异步I / O块进行处理

语法

#include <linux/aio_abi.h>          /* Defines needed types */

int io_submit(io_context_t ctx_id, long nr, struct iocb **iocbpp);

注意:此系统调用没有glibc包装器。请参阅注释。

说明

io_submit()系统调用将nr个I / O请求块排队,以便在AIO上下文ctx_id中进行处理。 iocbpp参数应为nr个AIO控制块的数组,并将其提交给上下文ctx_id。

linux / aio_abi.h中定义的iocb(I / O控制块)结构定义了控制I / O操作的参数。

#include <linux/aio_abi.h>

struct iocb {
    __u64   aio_data;
    __u32   PADDED(aio_key, aio_rw_flags);
    __u16   aio_lio_opcode;
    __s16   aio_reqprio;
    __u32   aio_fildes;
    __u64   aio_buf;
    __u64   aio_nbytes;
    __s64   aio_offset;
    __u64   aio_reserved2;
    __u32   aio_flags;
    __u32   aio_resfd;
};

此结构的字段如下:

aio_data
I / O完成后,此数据将复制到io_event结构的数据字段中(请参阅io_getevents(2))。
aio_key
这是内核使用的内部字段。调用io_submit()后不要修改此字段。
aio_rw_flags
This defines the R/W flags passed with structure. The valid values are:
RWF_APPEND(since Linux 4.16)
将数据追加到文件末尾。请参见pwritev2(2)中同名标记的描述以及open(2)中O_APPEND的描述。 aio_offset字段将被忽略。文件偏移量未更改。
RWF_DSYNC(since Linux 4.13)
根据同步I / O数据完整性的要求,写操作完成。请参见pwritev2(2)中同名标记的描述以及open(2)中O_DSYNC的描述。
RWF_HIPRI(since Linux 4.13)
高优先级请求,如果可能,请轮询
RWF_NOWAIT(since Linux 4.14)
如果I / O将阻塞诸如文件块分配,脏页刷新,互斥锁或内核内部拥塞的块设备之类的操作,请不要等待。如果满足这些条件中的任何一个,则立即在io_event结构的res字段中以-EAGAIN的返回值返回控制块(请参见io_getevents(2))。
RWF_SYNC(since Linux 4.13)
根据同步I / O文件完整性的要求,写操作完成。请参见pwritev2(2)中同名标记的描述以及open(2)中O_SYNC的描述。
aio_lio_opcode
这定义了iocb结构要执行的I / O类型。有效值由linux / aio_abi.h中定义的枚举定义:
enum {
    IOCB_CMD_PREAD = 0,
    IOCB_CMD_PWRITE = 1,
    IOCB_CMD_FSYNC = 2,
    IOCB_CMD_FDSYNC = 3,
    IOCB_CMD_POLL = 5,
    IOCB_CMD_NOOP = 6,
    IOCB_CMD_PREADV = 7,
    IOCB_CMD_PWRITEV = 8,
};
aio_reqprio
这定义了请求优先级。
aio_fildes
要对其执行I / O操作的文件描述符。
aio_buf
这是用于传输数据以进行读或写操作的缓冲区。
aio_nbytes
这是aio_buf指向的缓冲区的大小。
aio_offset
这是要执行I / O操作的文件偏移量。
aio_flags
This is the set of flags associated with the iocb

structure.
The valid values are:

IOCB_FLAG_RESFD
异步I / O控制必须在完成后用信号通知aio_resfd中提到的文件描述符。
IOCB_FLAG_IOPRIO(since Linux 4.18)
将aio_reqprio字段解释为linux / ioprio.h定义的IOPRIO_VALUE。
aio_resfd
在异步I / O完成时发出信号的文件描述符。

返回值

成功时,io_submit()返回提交的iocb的数量(可以小于nr,如果nr为零,则为0)。有关故障返回的信息,请参见"注意"。

错误说明

EAGAIN
没有足够的资源来排队任何iocb。
EBADF
第一个iocb中指定的文件描述符无效。
EFAULT
数据结构之一指向无效数据。
EINVAL
ctx_id指定的AIO上下文无效。 nr小于0。* iocbpp [0]处的iocb未正确初始化,指定的操作对iocb中的文件描述符无效,或者aio_reqprio字段中的值无效。
ENOSYS
io_submit()未在此体系结构上实现。
EPERM
使用IOPRIO_CLASS_RT类设置了aio_reqprio字段,但是提交上下文不具有CAP_SYS_ADMIN功能。

版本

异步I / O系统调用首先出现在Linux 2.5中。

遵循规范

io_submit()是特定于Linux的,不应在旨在可移植的程序中使用。

备注

Glibc没有为该系统调用提供包装函数。您可以使用syscall(2)调用它。但是,您可能想使用libaio提供的io_submit()包装函数。

请注意,libaio包装器函数对ctx_id参数使用其他类型(io_context_t)。还要注意,libaio包装器没有遵循通常的C库约定来指示错误:错误时,它返回一个否定的错误号(ERRORS中列出的值之一的负数)。如果通过syscall(2)调用系统调用,则返回值遵循指示错误的常规约定:-1,而errno设置为指示错误的(正)值。

另外参见

io_cancel(2),io_destroy(2),io_getevents(2),io_setup(2),aio(7)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本,请访问https://www.kernel.org/doc/man-pages/