io_submit(2)

NOM
io_submit - Soumettre un bloc d'entrées-sorties asynchrones

BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)

SYNOPSIS
#include <linux/aio_abi.h>
#include <sys/syscall.h>    /* Definition of SYS_* constants */
#include <unistd.h>

int syscall(SYS_io_submit, aio_context_t ctx_id,
            long n, struct iocb *iocbpp[n]);

DESCRIPTION
Note: you probably want to use the io_setup(3) wrapper function provided by libaio; see VERSIONS.

The io_submit() system call queues n I/O request blocks for processing in the AIO context ctx_id. The iocbpp argument should be an array of n AIO control blocks, which will be submitted to context ctx_id.

La structure iocb (bloc de contrôle d'E/S) définie dans linux/aio_abi.h spécifie les paramètres contrôlant les opérations d'E/S.

    #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;
    };

Les membres de cette structure sont les suivants :

aio_data
    Ces données sont copiées dans le champ data de la structure io_event à la complétion des E/S (voir io_getevents(2)).

aio_key
    Il s'agit d'un champ interne utilisé par le noyau. Il ne doit pas être modifié après un appel à io_submit().

aio_rw_flags
    Cela définit les options R/W passées avec la structure. Les valeurs acceptées sont :

    RWF_APPEND (depuis Linux 4.16)
        Ajouter des données à la fin du fichier. Voir la description de l'option du même nom dans pwritev2(2) ainsi que la description de O_APPEND dans open(2). Le champ aio_offset est ignoré. Le décalage du fichier est inchangé.

    RWF_DSYNC (depuis Linux 4.13)
        Opération d'écriture complète respectant l'intégrité des données d'E/S synchronisées. Voir la description de l'option du même nom dans pwritev2(2) ainsi que celle de O_DSYNC dans open(2).

    RWF_HIPRI (depuis Linux 4.13)
        Requête de haute priorité, scruter (« poll ») si possible

    RWF_NOWAIT (depuis Linux 4.14)
        Ne pas attendre si les E/S bloquent pour les opérations telles que les allocations de blocs de fichiers, la purge de pages sales (« dirty »), les verrous mutex ou un périphérique de bloc congestionné dans le noyau. Si une de ces conditions est remplie, le bloc de contrôle est renvoyé immédiatement avec la valeur de retour -EAGAIN dans le champ res de la structure io_event (voir io_getevents(2)).

    RWF_SYNC (depuis Linux 4.13)
        Opération d'écriture complète respectant l'intégrité des données d'E/S synchronisées. Voir la description de l'option du même nom dans pwritev2(2) ainsi que celle de O_SYNC dans open(2).

    RWF_NOAPPEND (since Linux 6.9)
        Do not honor O_APPEND open(2) flag. See the description of RWF_NOAPPEND in pwritev2(2).

    RWF_ATOMIC (since Linux 6.11)
        Write a block of data such that a write will never be torn from power fail or similar. See the description of RWF_ATOMIC in pwritev2(2). For usage with IOCB_CMD_PWRITEV, the upper vector limit is stx_atomic_write_segments_max. See STATX_WRITE_ATOMIC and stx_atomic_write_segments_max description in statx(2).

aio_lio_opcode
    Cela définit le type d'E/S à exécuter par la structure iocb. Les valeurs acceptées sont définies par l'enum spécifiée dans 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
    Cela définit la priorité des requêtes.

aio_fildes
    Le descripteur du fichier sur lequel les opérations d'E/S sont à réaliser.

aio_buf
    Le tampon utilisé pour le transfert de données des opérations de lecture ou d'écriture.

aio_nbytes
    La taille du tampon pointé par aio_buf.

aio_offset
    La position dans le fichier où les opérations d'E/S sont à réaliser.

aio_flags
    Il s'agit de l'ensemble d'attributs associés à la structure iocb. Les valeurs acceptées sont :

    IOCB_FLAG_RESFD
        Le contrôle asynchrone des E/S doit signaler le descripteur de fichier mentionné dans aio_resfd à la complétion.

    IOCB_FLAG_IOPRIO (depuis Linux 4.18)
        Interpréter le champ aio_reqprio comme une IOPRIO_VALUE telle que définie par linux/ioprio.h.

aio_resfd
    Le descripteur de fichier à signaler en cas de fin d'opération d'E/S asynchrone.

VALEUR RENVOYÉE
On success, io_submit() returns the number of iocbs submitted (which may be less than n, or 0 if n is zero).

En cas d'erreur, la valeur de retour est -1 et errno est définie pour préciser l'erreur.

ERREURS

EAGAIN
    Pas assez de ressources pour enregistrer un iocb.

EBADF
    Le descripteur de fichier dans le premier iocb n’est pas valable.

EFAULT
    L'une des structures de données pointe sur une zone invalide.

EINVAL
    Le contexte indiqué par ctx_id est invalide.

EINVAL
    n is less than 0.

EINVAL
    The iocb at *iocbpp[0] is not properly initialized.

EINVAL
    The operation specified is invalid for the file descriptor in the iocb.

EINVAL
    The value in the aio_reqprio field is invalid.

ENOSYS
    io_submit() n'est pas implémenté dans cette architecture.

EPERM
    Le champ aio_reqprio est positionné avec la classe IOPRIO_CLASS_RT, mais le contexte soumettant n'a pas la capacité CAP_SYS_ADMIN.

VERSIONS
libaio (https://pagure.io/libaio) provides a wrapper function with the same name, but different prototype and return value. You probably want to use that wrapper.

NORMES
Linux.

HISTORIQUE
Linux 2.5.

VOIR AUSSI
io_cancel(2), io_destroy(2), io_getevents(2), io_setup(2), io_submit(3), aio(7)

TRADUCTION
La traduction française de cette page de manuel a été créée par Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org> et Jean-Philippe MENGUAL <jpmengual@debian.org>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 (https://www.gnu.org/licenses/gpl-3.0.html) concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à debian-l10n-french@lists.debian.org.