Manpages - dispatch_read.3

The

and

functions asynchronously read from and write to POSIX file descriptors. They can be thought of as asynchronous, callback-based versions of the

and

functions provided by the standard C library. They are convenience functions based on the

and

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.

The

function schedules an asynchronous read operation on the file descriptor

Once the file descriptor is readable, the system will read as much data as is currently available, up to the specified

starting at the current file pointer position. The given

block will be submitted to

when the operation completes or an error occurs. The block will be passed a dispatch

object with the result of the read operation. If an error occurred while reading from the file descriptor, the

parameter to the block will be set to the appropriate POSIX error code and

will contain any data that could be read successfully. If the file pointer position is at end-of-file, emtpy

and zero

will be passed to the handler block.

The

function schedules an asynchronous write operation on the file descriptor

The system will attempt to write the entire contents of the provided

object to

at the current file pointer position. The given

block will be submitted to

when the operation completes or an error occurs. If the write operation completed successfully, the

parameter to the block will be set to zero, otherwise it will be set to the appropriate POSIX error code and the

parameter will contain any data that could not be written.

The

object passed to a

block is released by the system when the block returns. If

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

the system takes control of that file descriptor until the

block is executed. During this time the application must not manipulate

directly, in particular it is only safe to close

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

in