1dispatch_read(3)         BSD Library Functions Manual         dispatch_read(3)
2

NAME

4     dispatch_read, dispatch_write — asynchronously read from and write to
5     file descriptors
6

SYNOPSIS

8     #include <dispatch/dispatch.h>
9
10     void
11     dispatch_read(int fd, size_t length, dispatch_queue_t queue,
12         void (^handler)(dispatch_data_t data, int error));
13
14     void
15     dispatch_write(int fd, dispatch_data_t data, dispatch_queue_t queue,
16         void (^handler)(dispatch_data_t data, int error)));
17

DESCRIPTION

19     The dispatch_read() and dispatch_write() functions asynchronously read
20     from and write to POSIX file descriptors. They can be thought of as asyn‐
21     chronous, callback-based versions of the fread() and fwrite() functions
22     provided by the standard C library. They are convenience functions based
23     on the dispatch_io_read(3) and dispatch_io_write(3) functions, intended
24     for simple one-shot read or write requests. Multiple request on the same
25     file desciptor are better handled with the full underlying dispatch I/O
26     channel functions.
27

BEHAVIOR

29     The dispatch_read() function schedules an asynchronous read operation on
30     the file descriptor fd.  Once the file descriptor is readable, the system
31     will read as much data as is currently available, up to the specified
32     length, starting at the current file pointer position. The given handler
33     block will be submitted to queue when the operation completes or an error
34     occurs. The block will be passed a dispatch data object with the result
35     of the read operation. If an error occurred while reading from the file
36     descriptor, the error parameter to the block will be set to the appropri‐
37     ate POSIX error code and data will contain any data that could be read
38     successfully. If the file pointer position is at end-of-file, emtpy data
39     and zero error will be passed to the handler block.
40
41     The dispatch_write() function schedules an asynchronous write operation
42     on the file descriptor fd.  The system will attempt to write the entire
43     contents of the provided data object to fd at the current file pointer
44     position. The given handler block will be submitted to queue when the
45     operation completes or an error occurs. If the write operation completed
46     successfully, the error parameter to the block will be set to zero, oth‐
47     erwise it will be set to the appropriate POSIX error code and the data
48     parameter will contain any data that could not be written.
49

CAVEATS

51     The data object passed to a handler block is released by the system when
52     the block returns. If data is needed outside of the handler block, it
53     must concatenate, copy, or retain it.
54
55     Once an asynchronous read or write operation has been submitted on a file
56     descriptor fd, the system takes control of that file descriptor until the
57     handler block is executed. During this time the application must not
58     manipulate fd directly, in particular it is only safe to close fd from
59     the handler block (or after it has returned).
60
61     If multiple asynchronous read or write operations are submitted to the
62     same file descriptor, they will be performed in order, but their handlers
63     will only be submitted once all operations have completed and control
64     over the file descriptor has been relinquished. For details on this and
65     on the interaction with dispatch I/O channels created from the same file
66     descriptor, see FILEDESCRIPTOR OWNERSHIP in dispatch_io_create(3).
67

SEE ALSO

69     dispatch(3), dispatch_data_create(3), dispatch_io_create(3),
70     dispatch_io_read(3), fread(3)
71
72Darwin                         December 1, 2010                         Darwin
Impressum