AIO(7)

💖 AIO(7) 💖

okay bestie, welcome to the Miscellaneous Information Manual — this is aio, the whole ✨vibe✨ of POSIX asynchronous I/O. grab a boba, we're going in 🧋

---

🌸 NAME 🌸

aio — POSIX asynchronous I/O overview

---

🦋 DESCRIPTION 🦋

so the POSIX asynchronous I/O (AIO) interface lets your app kick off one or more I/O operations that just... happen in the background, lowkey doing their thing while you move on with your life. asynchronously, as the professionals say 💅

and the slay part? you get to choose how you find out when it's done:

• by delivery of a signal
• by instantiation of a thread
• or honestly?? no notification at all 😌 silent, mysterious, iconic

---

✨ the function lineup ✨

the POSIX AIO interface is made up of these besties:

• aio_read(3) — enqueue a read request. this is the asynchronous analog of read(2). 🍓
• aio_write(3) — enqueue a write request. this is the asynchronous analog of write(2). ✍️
• aio_fsync(3) — enqueue a sync request for the I/O operations on a file descriptor. this is the asynchronous analog of fsync(2) and fdatasync(2). 🔄
• aio_error(3) — obtain the error status of an enqueued I/O request. 🚨
• aio_return(3) — obtain the return status of a completed I/O request. 📬
• aio_suspend(3) — suspend the caller until one or more of a specified set of I/O requests completes. 😴
• aio_cancel(3) — attempt to cancel outstanding I/O requests on a specified file descriptor. 🙅♀️
• lio_listio(3) — enqueue multiple I/O requests using a single function call. the efficiency queen 👑

---

🎀 the aiocb structure 🎀

the aiocb ("asynchronous I/O control block") structure defines the parameters that control an I/O operation. an argument of this type gets used with all of the functions we just listed. no cap.

here's the whole thing, verbatim, do not touch:

#include <aiocb.h>

struct aiocb {
    /* The order of these fields is implementation-dependent */

    int             aio_fildes;     /* File descriptor */
    off_t           aio_offset;     /* File offset */
    volatile void  *aio_buf;        /* Location of buffer */
    size_t          aio_nbytes;     /* Length of transfer */
    int             aio_reqprio;    /* Request priority */
    struct sigevent aio_sigevent;   /* Notification method */
    int             aio_lio_opcode; /* Operation to be performed;
                                       lio_listio() only */

    /* Various implementation-internal fields not shown */
};

/* Operation codes for 'aio_lio_opcode': */

enum { LIO_READ, LIO_WRITE, LIO_NOP };

---

💜 field by field, let's unpack 💜

• aio_fildes — the file descriptor on which the I/O operation is to be performed. like, where the drama happens.
• aio_offset — this is the file offset at which the I/O operation is to be performed. 📍
• aio_buf — this is the buffer used to transfer data for a read or write operation.
• aio_nbytes — this is the size of the buffer pointed to by aio_buf.
• aio_reqprio — this field specifies a value that is subtracted from the calling thread's real-time priority in order to determine the priority for execution of this I/O request (see pthread_setschedparam(3)). the specified value must be between 0 and the value returned by sysconf(_SC_AIO_PRIO_DELTA_MAX). heads up: this field is ignored for file synchronization operations. 🙈
• aio_sigevent — this field is a structure that specifies how the caller is to be notified when the asynchronous I/O operation completes. possible values for aio_sigevent.sigev_notify are SIGEV_NONE, SIGEV_SIGNAL, and SIGEV_THREAD. see sigevent(3type) for further details. 👀
• aio_lio_opcode — the type of operation to be performed; used only for lio_listio(3).

---

🌈 and a lil glibc bonus 🌈

in addition to the standard functions listed above, the GNU C library provides the following extension to the POSIX AIO API:

• aio_init(3) — set parameters for tuning the behavior of the glibc POSIX AIO implementation. ✨

---

💀 ERRORS 💀

• EINVAL — the aio_reqprio field of the aiocb structure was less than 0, or was greater than the limit returned by the call sysconf(_SC_AIO_PRIO_DELTA_MAX). out of range, bestie, absolutely not.

---

👑 STANDARDS 👑

POSIX.1-2008. 📜

---

🦕 HISTORY 🦕

POSIX.1-2001. glibc 2.1. throwback era 🫶

---

⚠️ NOTES ⚠️

fr fr, zero out the control block buffer before use (see memset(3)). it's just a good idea, bestie.

the control block buffer and the buffer pointed to by aio_buf must not be changed while the I/O operation is in progress. these buffers must remain valid until the I/O operation completes. no touching. hands off. 🙅♀️

simultaneous asynchronous read or write operations using the same aiocb structure yield undefined results. so like... don't. 😭

the current Linux POSIX AIO implementation is provided in user space by glibc. this has a number of limitations, most notably that maintaining multiple threads to perform I/O operations is expensive and scales poorly. 💸

work has been in progress for some time on a kernel state-machine-based implementation of asynchronous I/O (see io_submit(2), io_setup(2), io_cancel(2), io_destroy(2), io_getevents(2)), but this implementation hasn't yet matured to the point where the POSIX AIO implementation can be completely reimplemented using the kernel system calls. it's giving "work in progress", and we respect the journey 🧚

✨ EXAMPLES ✨

ok so bestie, the little program below is literally the whole vibe — it opens every file you name in its command-line arguments, then queues a request on each resulting file descriptor using aio_read(3). 🎀

Then it just... loops. Periodically checking on every I/O operation that's still in progress with aio_error(3). Every single I/O request is set up to ping you by delivering a signal, which is iconic honestly. And once all the I/O requests are done, the program grabs their status with aio_return(3). 💅

The SIGQUIT signal — that's the one you get by typing Ctrl+</kbd> — makes the program ask for cancelation of each outstanding request using aio_cancel(3). slay that cancel button fr fr.

Here's what it might look like when we run it. In this example the program queues two requests to standard input, and they get satisfied by two lines of input containing "abc" and "x".

$ ./a.out /dev/stdin /dev/stdin;
opened /dev/stdin on descriptor 3
opened /dev/stdin on descriptor 4
aio_error():
    for request 0 (descriptor 3): In progress
    for request 1 (descriptor 4): In progress
abc
I/O completion signal received
aio_error():
    for request 0 (descriptor 3): I/O succeeded
    for request 1 (descriptor 4): In progress
aio_error():
    for request 1 (descriptor 4): In progress
x
I/O completion signal received
aio_error():
    for request 1 (descriptor 4): I/O succeeded
All I/O requests completed
aio_return():
    for request 0 (descriptor 3): 4
    for request 1 (descriptor 4): 2

🌸 Program source 🌸

here's the whole thing, bestie, straight up. no cap:

#include <err.h>
#include <fcntl.h>
#include <stdlib.h>
#include <unistd.h>
#include <stdio.h>
#include <errno.h>
#include <aio.h>
#include <signal.h>

#define BUF_SIZE 20     /* Size of buffers for read operations */

struct ioRequest {      /* Application-defined structure for tracking
                           I/O requests */
    int           reqNum;
    int           status;
    struct aiocb *aiocbp;
};

static volatile sig_atomic_t gotSIGQUIT = 0;
                        /* On delivery of SIGQUIT, we attempt to
                           cancel all outstanding I/O requests */

static void             /* Handler for SIGQUIT */
quitHandler(int sig)
{
    gotSIGQUIT = 1;
}

#define IO_SIGNAL SIGUSR1   /* Signal used to notify I/O completion */

static void                 /* Handler for I/O completion signal */
aioSigHandler(int sig, siginfo_t *si, void *ucontext)
{
    if (si->si_code == SI_ASYNCIO) {
        write(STDOUT_FILENO, "I/O completion signal received\n", 31);

        /* The corresponding ioRequest structure would be available as
               struct ioRequest *ioReq = si->si_value.sival_ptr;
           and the file descriptor would then be available via
               ioReq->aiocbp->aio_fildes */
    }
}

int
main(int argc, char *argv[])
{
    struct sigaction sa;
    int s;
    int numReqs;        /* Total number of queued I/O requests */
    int openReqs;       /* Number of I/O requests still in progress */

    if (argc < 2) {
        fprintf(stderr, "Usage: %s <pathname> <pathname>...\n",
                argv[0]);
        exit(EXIT_FAILURE);
    }

    numReqs = argc - 1;

    /* Allocate our arrays.  */

    struct ioRequest *ioList = calloc(numReqs, sizeof(*ioList));
    if (ioList == NULL)
        err(EXIT_FAILURE, "calloc");

    struct aiocb *aiocbList = calloc(numReqs, sizeof(*aiocbList));
    if (aiocbList == NULL)
        err(EXIT_FAILURE, "calloc");

    /* Establish handlers for SIGQUIT and the I/O completion signal.  */

    sa.sa_flags = SA_RESTART;
    sigemptyset(&sa.sa_mask);

    sa.sa_handler = quitHandler;
    if (sigaction(SIGQUIT, &sa, NULL) == -1)
        err(EXIT_FAILURE, "sigaction");

    sa.sa_flags = SA_RESTART | SA_SIGINFO;
    sa.sa_sigaction = aioSigHandler;
    if (sigaction(IO_SIGNAL, &sa, NULL) == -1)
        err(EXIT_FAILURE, "sigaction");

    /* Open each file specified on the command line, and queue
       a read request on the resulting file descriptor.  */

    for (size_t j = 0; j < numReqs; j++) {
        ioList[j].reqNum = j;
        ioList[j].status = EINPROGRESS;
        ioList[j].aiocbp = &aiocbList[j];

        ioList[j].aiocbp->aio_fildes = open(argv[j + 1], O_RDONLY);
        if (ioList[j].aiocbp->aio_fildes == -1)
            err(EXIT_FAILURE, "open");
        printf("opened %s on descriptor %d\n", argv[j + 1],
                ioList[j].aiocbp->aio_fildes);

        ioList[j].aiocbp->aio_buf = malloc(BUF_SIZE);
        if (ioList[j].aiocbp->aio_buf == NULL)
            err(EXIT_FAILURE, "malloc");

        ioList[j].aiocbp->aio_nbytes = BUF_SIZE;
        ioList[j].aiocbp->aio_reqprio = 0;
        ioList[j].aiocbp->aio_offset = 0;
        ioList[j].aiocbp->aio_sigevent.sigev_notify = SIGEV_SIGNAL;
        ioList[j].aiocbp->aio_sigevent.sigev_signo = IO_SIGNAL;
        ioList[j].aiocbp->aio_sigevent.sigev_value.sival_ptr =
                                &ioList[j];

        s = aio_read(ioList[j].aiocbp);
        if (s == -1)
            err(EXIT_FAILURE, "aio_read");
    }

    openReqs = numReqs;

    /* Loop, monitoring status of I/O requests.  */

    while (openReqs > 0) {
        sleep(3);       /* Delay between each monitoring step */

        if (gotSIGQUIT) {

            /* On receipt of SIGQUIT, attempt to cancel each of the
               outstanding I/O requests, and display status returned
               from the cancelation requests.  */

            printf("got SIGQUIT; canceling I/O requests: \n");

            for (size_t j = 0; j < numReqs; j++) {
                if (ioList[j].status == EINPROGRESS) {
                    printf("    Request %zu on descriptor %d:", j,
                            ioList[j].aiocbp->aio_fildes);
                    s = aio_cancel(ioList[j].aiocbp->aio_fildes,
                            ioList[j].aiocbp);
                    if (s == AIO_CANCELED)
                        printf("I/O canceled\n");
                    else if (s == AIO_NOTCANCELED)
                        printf("I/O not canceled\n");
                    else if (s == AIO_ALLDONE)
                        printf("I/O all done\n");
                    else
                        perror("aio_cancel");
                }
            }

            gotSIGQUIT = 0;
        }

        /* Check the status of each I/O request that is still
           in progress.  */

        printf("aio_error():\n");
        for (size_t j = 0; j < numReqs; j++) {
            if (ioList[j].status == EINPROGRESS) {
                printf("    for request %zu (descriptor %d): ",
                        j, ioList[j].aiocbp->aio_fildes);
                ioList[j].status = aio_error(ioList[j].aiocbp);

                switch (ioList[j].status) {
                case 0:
                    printf("I/O succeeded\n");
                    break;
                case EINPROGRESS:
                    printf("In progress\n");
                    break;
                case ECANCELED:
                    printf("Canceled\n");
                    break;
                default:
                    perror("aio_error");
                    break;
                }

                if (ioList[j].status != EINPROGRESS)
                    openReqs--;
            }
        }
    }

    printf("All I/O requests completed\n");

    /* Check status return of all I/O requests.  */

    printf("aio_return():\n");
    for (size_t j = 0; j < numReqs; j++) {
        ssize_t s;

        s = aio_return(ioList[j].aiocbp);
        printf("    for request %zu (descriptor %d): %zd\n",
                j, ioList[j].aiocbp->aio_fildes, s);
    }

    exit(EXIT_SUCCESS);
}

---

👑 SEE ALSO 👑

go read these next bestie, they're the whole friend group:

• io_cancel(2), io_destroy(2), io_getevents(2), io_setup(2), io_submit(2),
• aio_cancel(3), aio_error(3), aio_init(3), aio_read(3), aio_return(3),
• aio_write(3), lio_listio(3)

and one academic baddie for the girlies who like papers:

• "Asynchronous I/O Support in Linux 2.5", Bhattacharya, Pratt, Pulavarty, and Morgan, Proceedings of the Linux Symposium, 2003, https: //www.kernel.org/doc/ols/2003/ols2003-pages-351-366.pdf

---

ok that's the whole page bestie, we did it 💖 this was Linux man-pages 6.20, dated 2026-02-08, and it lives under the name AIO(7). go forth and async, you absolute icon 🦋✨