---
name: "dispatch_read"
section: "3"
platform: "macos"
package: "libdispatch"
version: "1542.100.32"
release: "macOS 26.5"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/dispatch_read"
---

# dispatch\_read(3)

asynchronously read from and write to file descriptors

## NAME

**dispatch\_read**, **dispatch\_write** – asynchronously read from and write to file descriptors

## SYNOPSIS

**#include \<dispatch/dispatch.h\>**

*void*\

**dispatch\_read**(*int fd*, *size\_t length*, *dispatch\_queue\_t queue*, *void (^handler)(dispatch\_data\_t data, int error)*);

*void*\

**dispatch\_write**(*int fd*, *dispatch\_data\_t data*, *dispatch\_queue\_t queue*, *void (^handler)(dispatch\_data\_t data, int error))*);

## DESCRIPTION

The **dispatch\_read**() and **dispatch\_write**() functions asynchronously read from and write to POSIX file descriptors. They can be thought of as asynchronous, callback-based versions of the **fread**() and **fwrite**() functions provided by the standard C library. They are convenience functions based on the [dispatch\_io\_read(3)](/dispatch_io_read/3.md) and dispatch\_io\_write(3) functions, intended for simple one-shot read or write requests. Multiple request on the same file desciptor are better handled with the full underlying dispatch I/O channel functions.

## BEHAVIOR

The **dispatch\_read**() function schedules an asynchronous read operation on the file descriptor *fd*. Once the file descriptor is readable, the system will read as much data as is currently available, up to the specified *length*, starting at the current file pointer position. The given *handler* block will be submitted to *queue* when the operation completes or an error occurs. The block will be passed a dispatch *data* object with the result of the read operation. If an error occurred while reading from the file descriptor, the *error* parameter to the block will be set to the appropriate POSIX error code and *data* will contain any data that could be read successfully. If the file pointer position is at end-of-file, empty *data* and zero *error* will be passed to the handler block.

The **dispatch\_write**() function schedules an asynchronous write operation on the file descriptor *fd*. The system will attempt to write the entire contents of the provided *data* object to *fd* at the current file pointer position. The given *handler* block will be submitted to *queue* when the operation completes or an error occurs. If the write operation completed successfully, the *error* parameter to the block will be set to zero, otherwise it will be set to the appropriate POSIX error code and the *data* parameter will contain any data that could not be written.

## 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\_io\_read(3)](/dispatch_io_read/3.md), [fread(3)](/fread/3.md)

## CAVEATS

The *data* object passed to a *handler* block is released by the system when the block returns. If *data* is needed outside of the handler block, it must concatenate, copy, or retain it.

Once an asynchronous read or write operation has been submitted on a file descriptor *fd*, the system takes control of that file descriptor until the *handler* block is executed. During this time the application must not manipulate *fd* directly, in particular it is only safe to close *fd* from the handler block (or after it has returned).

If multiple asynchronous read or write operations are submitted to the same file descriptor, they will be performed in order, but their handlers will only be submitted once all operations have completed and control over the file descriptor has been relinquished. For details on this and on the interaction with dispatch I/O channels created from the same file descriptor, see FILEDESCRIPTOR OWNERSHIP in [dispatch\_io\_create(3)](/dispatch_io_create/3.md).