--- name: "dispatch_io_read" section: "3" platform: "macos" package: "libdispatch" version: "1542.100.32" release: "macOS 26.5" platforms: ["linux", "macos"] url: "https://new.carta.tech/dispatch_io_read" --- # dispatch\_io\_read(3) submit read and write operations to dispatch I/O channels ## NAME **dispatch\_io\_read**, **dispatch\_io\_write** – submit read and write operations to dispatch I/O channels ## SYNOPSIS **#include \** *void*\ **dispatch\_io\_read**(*dispatch\_io\_t channel*, *off\_t offset*, *size\_t length*, *dispatch\_queue\_t queue*, *void (^handler)(bool done, dispatch\_data\_t data, int error)*); *void*\ **dispatch\_io\_write**(*dispatch\_io\_t channel*, *off\_t offset*, *dispatch\_data\_t data*, *dispatch\_queue\_t queue*, *void (^handler)(bool done, dispatch\_data\_t data, int error)*); ## DESCRIPTION The dispatch I/O framework is an API for asynchronous read and write I/O operations. It is an application of the ideas and idioms present in the [dispatch(3)](/dispatch/3.md) framework to device I/O. Dispatch I/O enables an application to more easily avoid blocking I/O operations and allows it to more directly express its I/O requirements than by using the raw POSIX file API. Dispatch I/O will make a best effort to optimize how and when asynchronous I/O operations are performed based on the capabilities of the targeted device. This page provides details on how to read from and write to dispatch I/O channels. Creation and configuration of these channels is covered in the [dispatch\_io\_create(3)](/dispatch_io_create/3.md) page. The dispatch I/O framework also provides the convenience functions [dispatch\_read(3)](/dispatch_read/3.md) and dispatch\_write(3) for uses that do not require the full functionality provided by I/O channels. ## FUNDAMENTALS The **dispatch\_io\_read**() and **dispatch\_io\_write**() functions are used to perform asynchronous read and write operations on dispatch I/O channels. They can be thought of as asynchronous versions of the [fread(3)](/fread/3.md) and [fwrite(3)](/fwrite/3.md) functions in the standard C library. ## READ OPERATIONS The **dispatch\_io\_read**() function schedules an I/O read operation on the specified dispatch I/O *channel*. As results from the read operation become available, the provided *handler* block will be submitted to the specified *queue*. The block will be passed a dispatch data object representing the data that has been read since the handler's previous invocation. The *offset* parameter indicates where the read operation should begin. For a channel of DISPATCH\_IO\_RANDOM type it is interpreted relative to the position of the file pointer when the channel was created, for a channel of DISPATCH\_IO\_STREAM type it is ignored and the read operation will begin at the current file pointer position. The *length* parameter indicates the number of bytes that should be read from the I/O channel. Pass SIZE\_MAX to keep reading until EOF is encountered (for a channel created from a disk-based file this happens when reading past the end of the physical file). ## WRITE OPERATIONS The **dispatch\_io\_write**() function schedules an I/O write operation on the specified dispatch I/O *channel*. As the write operation progresses, the provided *handler* block will be submitted to the specified *queue*. The block will be passed a dispatch data object representing the data that remains to be written as part of this I/O operation. The *offset* parameter indicates where the write operation should begin. It is interpreted as for read operations above. The *data* parameter specifies the location and amount of data to be written, encapsulated as a dispatch data object. The object is retained by the system until the write operation is complete. ## I/O HANDLER BLOCKS Dispatch I/O handler blocks submitted to a channel via the **dispatch\_io\_read**() or **dispatch\_io\_write**() functions will be executed one or more times depending on system load and the channel's configuration settings (see [dispatch\_io\_create(3)](/dispatch_io_create/3.md) for details). The handler block need not be reentrant safe, no new I/O handler instance is submitted until the previously enqueued handler block has returned. The dispatch *data* object passed to an I/O handler block will be released by the system when the block returns, if access to the memory buffer it represents is needed outside of the handler, the handler block must retain the data object or create a new (e.g. concatenated) data object from it (see [dispatch\_data\_create(3)](/dispatch_data_create/3.md) for details). Once an I/O handler block is invoked with the *done* flag set, the associated I/O operation is complete and that handler block will not be run again. If an unrecoverable error occurs while performing the I/O operation, the handler block will be submitted with the *done* flag set and the appropriate POSIX error code in the *error* parameter. An invocation of a handler block with the *done* flag set, zero *error* and *data* set to *dispatch\_data\_empty* indicates that the I/O operation has encountered EOF. ## SEE ALSO [dispatch(3)](/dispatch/3.md), [dispatch\_data\_create(3)](/dispatch_data_create/3.md), [dispatch\_io\_create(3)](/dispatch_io_create/3.md), [dispatch\_read(3)](/dispatch_read/3.md), [fread(3)](/fread/3.md)