Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

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 applica-tion application
     tion 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 config-uration configuration
     uration 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 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 speci-fied specified
     fied 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