afb81b8278
Some checks failed
Docker. / Ubuntu (push) Has been cancelled
User-agent updater. / User-agent (push) Failing after 15s
Lock Threads / lock (push) Failing after 10s
Waiting for answer. / waiting-for-answer (push) Failing after 22s
Close stale issues and PRs / stale (push) Successful in 13s
Needs user action. / needs-user-action (push) Failing after 8s
Can't reproduce. / cant-reproduce (push) Failing after 8s
124 lines
3.6 KiB
Groff
124 lines
3.6 KiB
Groff
.\" 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
|