dispatch_write(3) [osx man page]
dispatch_read(3) BSD Library Functions Manual dispatch_read(3) 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 func- tions based on the dispatch_io_read(3) 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, emtpy 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. 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 han- dlers 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). SEE ALSO
dispatch(3), dispatch_data_create(3), dispatch_io_create(3), dispatch_io_read(3), fread(3) Darwin December 1, 2010 Darwin
Check Out this Related Man Page
dispatch_io_read(3) BSD Library Functions Manual dispatch_io_read(3) NAME
dispatch_io_read, dispatch_io_write -- submit read and write operations to dispatch I/O channels SYNOPSIS
#include <dispatch/dispatch.h> 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 dispatch, 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) 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) page. The dispatch I/O framework also provides the convenience functions dispatch_read(3) 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) and fwrite(3) 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 rep- resenting 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) 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) 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 appriate 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_data_create(3), dispatch_io_create(3), dispatch_read(3), fread(3) Darwin December 1, 2010 Darwin