| .\" 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 |