man/dispatch_read.3

   1 .\" Copyright (c) 2010 Apple Inc. All rights reserved.
   2 .Dd December 1, 2010
   3 .Dt dispatch_read 3
   4 .Os Darwin
   5 .Sh NAME
   6 .Nm dispatch_read ,
   7 .Nm dispatch_write
   8 .Nd asynchronously read from and write to file descriptors
   9 .Sh SYNOPSIS
  10 .Fd #include <dispatch/dispatch.h>
  11 .Ft void
  12 .Fo dispatch_read
  13 .Fa "int fd"
  14 .Fa "size_t length"
  15 .Fa "dispatch_queue_t queue"
  16 .Fa "void (^handler)(dispatch_data_t data, int error)"
  17 .Fc
  18 .Ft void
  19 .Fo dispatch_write
  20 .Fa "int fd"
  21 .Fa "dispatch_data_t data"
  22 .Fa "dispatch_queue_t queue"
  23 .Fa "void (^handler)(dispatch_data_t data, int error))"
  24 .Fc
  25 .Sh DESCRIPTION
  26 The
  27 .Fn dispatch_read
  28 and
  29 .Fn dispatch_write
  30 functions asynchronously read from and write to POSIX file descriptors. They
  31 can be thought of as asynchronous, callback-based versions of the
  32 .Fn fread
  33 and
  34 .Fn fwrite
  35 functions provided by the standard C library. They are convenience functions
  36 based on the
  37 .Xr dispatch_io_read 3
  38 and
  39 .Xr dispatch_io_write 3
  40 functions, intended for simple one-shot read or write requests. Multiple
  41 request on the same file desciptor are better handled with the full underlying
  42 dispatch I/O channel functions.
  43 .Sh BEHAVIOR
  44 The
  45 .Fn dispatch_read
  46 function schedules an asynchronous read operation on the file descriptor
  47 .Va fd .
  48 Once the file descriptor is readable, the system will read as much data as is
  49 currently available, up to the specified
  50 .Va length ,
  51 starting at the current file pointer position. The given
  52 .Va handler
  53 block will be submitted to
  54 .Va queue
  55 when the operation completes or an error occurs. The block will be passed a
  56 dispatch
  57 .Va data
  58 object with the result of the read operation. If an error occurred while
  59 reading from the file descriptor, the
  60 .Va error
  61 parameter to the block will be set to the appropriate POSIX error code and
  62 .Va data
  63 will contain any data that could be read successfully. If the file pointer
  64 position is at end-of-file, emtpy
  65 .Va data
  66 and zero
  67 .Va error
  68 will be passed to the handler block.
  69 .Pp
  70 The
  71 .Fn dispatch_write
  72 function schedules an asynchronous write operation on the file descriptor
  73 .Va fd .
  74 The system will attempt to write the entire contents of the provided
  75 .Va data
  76 object to
  77 .Va fd
  78 at the current file pointer position. The given
  79 .Va handler
  80 block will be submitted to
  81 .Va queue
  82 when the operation completes or an error occurs. If the write operation
  83 completed successfully, the
  84 .Va error
  85 parameter to the block will be set to zero, otherwise it will be set to the
  86 appropriate POSIX error code and the
  87 .Va data
  88 parameter will contain any data that could not be written.
  89 .Sh CAVEATS
  90 The
  91 .Va data
  92 object passed to a
  93 .Va handler
  94 block is released by the system when the block returns. If
  95 .Va data
  96 is needed outside of the handler block, it must concatenate, copy, or retain
  97 it.
  98 .Pp
  99 Once an asynchronous read or write operation has been submitted on a file
 100 descriptor
 101 .Va fd ,
 102 the system takes control of that file descriptor until the
 103 .Va handler
 104 block is executed. During this time the application must not manipulate
 105 .Va fd
 106 directly, in particular it is only safe to close
 107 .Va fd
 108 from the handler block (or after it has returned).
 109 .Pp
 110 If multiple asynchronous read or write operations are submitted to the same
 111 file descriptor, they will be performed in order, but their handlers will only
 112 be submitted once all operations have completed and control over the file
 113 descriptor has been relinquished. For details on this and on the interaction
 114 with dispatch I/O channels created from the same file descriptor, see
 115 .Sx FILEDESCRIPTOR OWNERSHIP
 116 in
 117 .Xr dispatch_io_create 3 .
 118 .Sh SEE ALSO
 119 .Xr dispatch 3 ,
 120 .Xr dispatch_data_create 3 ,
 121 .Xr dispatch_io_create 3 ,
 122 .Xr dispatch_io_read 3 ,
 123 .Xr fread 3