init

Telegram/ThirdParty/dispatch/man/dispatch_read.3

@@ -0,0 +1,123 @@
+.\" 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