---
name: "lio_listio"
section: "2freebsd"
platform: "linux"
package: "freebsd-manpages"
version: "12.2-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/lio_listio/2freebsd"
---

# lio\_listio(2freebsd)

list directed I/O (REALTIME)

## NAME

**lio\_listio** – list directed I/O (REALTIME)

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

**#include \<aio.h\>**

*int*\

**lio\_listio**(*int mode*, *struct aiocb \* const list\[\]*, *int nent*, *struct sigevent \*sig*);

## DESCRIPTION

The **lio\_listio**() function initiates a list of I/O requests with a single function call. The *list* argument is an array of pointers to *aiocb* structures describing each operation to perform, with *nent* elements. NULL elements are ignored.

The *aio\_lio\_opcode* field of each *aiocb* specifies the operation to be performed. The following operations are supported:

- LIO\_READ

  Read data as if by a call to [aio\_read(2)](/aio_read/2.md).

- LIO\_NOP

  No operation.

- LIO\_WRITE

  Write data as if by a call to [aio\_write(2)](/aio_write/2.md).

If the *mode* argument is LIO\_WAIT, **lio\_listio**() does not return until all the requested operations have been completed. If *mode* is LIO\_NOWAIT, *sig* can be used to request asynchronous notification when all operations have completed. If *sig* is NULL, no notification is sent.

For SIGEV\_KEVENT notifications, the posted kevent will contain:

| | |
| --- | --- |
| **Member** | **Value** |
| *ident* | *list* |
| *filter* | EVFILT\_LIO |
| *udata* |  |

For SIGEV\_SIGNO and SIGEV\_THREAD\_ID notifications, the information for the queued signal will include SI\_ASYNCIO in the *si\_code* field and the value stored in *sig-\>sigev\_value* in the *si\_value* field.

For SIGEV\_THREAD notifications, the value stored in *sig-\>sigev\_value* is passed to the *sig-\>sigev\_notify\_function* as described in [sigevent(3)](/sigevent/3.md).

The order in which the requests are carried out is not specified; in particular, there is no guarantee that they will be executed in the order 0, 1, ..., *nent*-1.

## RETURN VALUES

If *mode* is LIO\_WAIT, the **lio\_listio**() function returns 0 if the operations completed successfully, otherwise -1.

If *mode* is LIO\_NOWAIT, the **lio\_listio**() function returns 0 if the operations are successfully queued, otherwise -1.

## ERRORS

The **lio\_listio**() function will fail if:

- \[EAGAIN\]

  There are not enough resources to enqueue the requests.

- \[EAGAIN\]

  The request would cause the system-wide limit {AIO\_MAX} to be exceeded.

- \[EINVAL\]

  The *mode* argument is neither LIO\_WAIT nor LIO\_NOWAIT, or *nent* is greater than {AIO\_LISTIO\_MAX}.

- \[EINVAL\]

  The asynchronous notification method in *sig-\>sigev\_notify* is invalid or not supported.

- \[EINTR\]

  A signal interrupted the system call before it could be completed.

- \[EIO\]

  One or more requests failed.

In addition, the **lio\_listio**() function may fail for any of the reasons listed for [aio\_read(2)](/aio_read/2.md) and [aio\_write(2)](/aio_write/2.md).

If **lio\_listio**() succeeds, or fails with an error code of EAGAIN, EINTR, or EIO, some of the requests may have been initiated. The caller should check the error status of each *aiocb* structure individually by calling [aio\_error(2)](/aio_error/2.md).

## SEE ALSO

[aio\_error(2)](/aio_error/2.md), [aio\_read(2)](/aio_read/2.md), [aio\_write(2)](/aio_write/2.md), [read(2)](/read/2.md), [write(2)](/write/2.md), [sigevent(3)](/sigevent/3.md), [siginfo(3)](/siginfo/3.md), [aio(4)](/aio/4.md)

## STANDARDS

The **lio\_listio**() function is expected to conform to IEEE Std 1003.1-2001 (“POSIX.1”).

## HISTORY

The **lio\_listio**() system call first appeared in FreeBSD 3.0.