Function

dispatch_io_read

Schedules an asynchronous read operation on the specified channel.

Declaration

void dispatch_io_read(dispatch_io_t channel, off_t offset, size_t length, dispatch_queue_t queue, dispatch_io_handler_t io_handler);

Parameters

channel

The channel to use when reading the data.

offset

For random-access channels, this parameter specifies the offset into the channel from which to read. The offset is specified relative to the initial file pointer of the channel’s file descriptor at the time the channel was created.

For stream-based channels, this parameter is ignored and data is read from the current position.

length

The number of bytes to read from the channel. Specify SIZE_MAX to continue reading data until an EOF is reached.

queue

The dispatch queue on which to submit the io_handler block.

io_handler

The block to use to process the data read from the channel. This block may be queued multiple times to process a given data request. Each time the block is queued, the data parameter passed to the handler contains the most recently read chunk of data. The handler has no return value and takes the following parameters:

done

A Boolean value indicating whether the operation is complete.

data

A dispatch_data_t object containing the data read from the file descriptor.

error

An errno condition if there was an error; otherwise, the value is 0.

Your block need not be reentrant. The system guarantees that only one instance of this block will be executed at any given time.

Discussion

This function reads the specified data and submits the handler block to queue to process the data. If the done parameter of the handler is set to false, it means that only part of the data was read. If the done parameter is YES, it means the read operation is complete and the handler will not be submitted again. If an unrecoverable error occurs on the channel’s file descriptor, the done parameter is set to true and an appropriate error value is reported in the handler’s error parameter.

If the handler is submitted with the done parameter set to true, an empty data object, and an error code of 0, it means that the channel reached the end of the file.

See Also

Reading from the File

dispatch_read

Schedules an asynchronous read operation using the specified file descriptor.

dispatch_io_handler_t

A handler block used to process operations on a dispatch I/O channel.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software