.\" Copyright (c) 2010 Apple Inc. All rights reserved.
.Dd December 1, 2010
.Dt dispatch_read 3
.Os Darwin
.Sh NAME
.Nm dispatch_read ,
.Nm dispatch_write
.Nd asynchronously read from and write to file descriptors
.Sh SYNOPSIS
.Fd #include <dispatch/dispatch.h>
.Ft void
.Fo dispatch_read
.Fa "int fd"
.Fa "size_t length"
.Fa "dispatch_queue_t queue"
.Fa "void (^handler)(dispatch_data_t data, int error)"
.Fc
.Ft void
.Fo dispatch_write
.Fa "int fd"
.Fa "dispatch_data_t data"
.Fa "dispatch_queue_t queue"
.Fa "void (^handler)(dispatch_data_t data, int error))"
.Fc
.Sh DESCRIPTION
The
.Fn dispatch_read
and
.Fn dispatch_write
functions asynchronously read from and write to POSIX file descriptors. They
can be thought of as asynchronous, callback-based versions of the
.Fn fread
and
.Fn fwrite
functions provided by the standard C library. They are convenience functions
based on the
.Xr dispatch_io_read 3
and
.Xr 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.
.Sh BEHAVIOR
The
.Fn dispatch_read
function schedules an asynchronous read operation on the file descriptor
.Va fd .
Once the file descriptor is readable, the system will read as much data as is
currently available, up to the specified
.Va length ,
starting at the current file pointer position. The given
.Va handler
block will be submitted to
.Va queue
when the operation completes or an error occurs. The block will be passed a
dispatch
.Va data
object with the result of the read operation. If an error occurred while
reading from the file descriptor, the
.Va error
parameter to the block will be set to the appropriate POSIX error code and
.Va data
will contain any data that could be read successfully. If the file pointer
position is at end-of-file, emtpy
.Va data
and zero
.Va error
will be passed to the handler block.
.Pp
The
.Fn dispatch_write
function schedules an asynchronous write operation on the file descriptor
.Va fd .
The system will attempt to write the entire contents of the provided
.Va data
object to
.Va fd
at the current file pointer position. The given
.Va handler
block will be submitted to
.Va queue
when the operation completes or an error occurs. If the write operation
completed successfully, the
.Va error
parameter to the block will be set to zero, otherwise it will be set to the
appropriate POSIX error code and the
.Va data
parameter will contain any data that could not be written.
.Sh CAVEATS
The
.Va data
object passed to a
.Va handler
block is released by the system when the block returns. If
.Va data
is needed outside of the handler block, it must concatenate, copy, or retain
it.
.Pp
Once an asynchronous read or write operation has been submitted on a file
descriptor
.Va fd ,
the system takes control of that file descriptor until the
.Va handler
block is executed. During this time the application must not manipulate
.Va fd
directly, in particular it is only safe to close
.Va fd
from the handler block (or after it has returned).
.Pp
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
.Sx FILEDESCRIPTOR OWNERSHIP
in
.Xr dispatch_io_create 3 .
.Sh SEE ALSO
.Xr dispatch 3 ,
.Xr dispatch_data_create 3 ,
.Xr dispatch_io_create 3 ,
.Xr dispatch_io_read 3 ,
.Xr fread 3