Function

dispatch_io_create

Creates a dispatch I/O channel and associates it with the specified file descriptor.

Declaration

dispatch_io_t dispatch_io_create(dispatch_io_type_t type, dispatch_fd_t fd, dispatch_queue_t queue, void (^cleanup_handler)(int error));

Parameters

type

The type of channel to create. For a list of possible options, see dispatch_io_type_t.

fd

The file descriptor to associate with the channel.

queue

The dispatch queue to associate with the channel. This queue is used to execute the channel’s clean up handler. The channel retains this queue.

cleanup_handler

The block to enqueue when the system relinquishes control of the channel’s file descriptor. This channel takes a single parameter that indicates the reason why control was relinquished. If the error parameter contains a non zero value, control was relinquished because there was an error creating the channel; otherwise, this value should be 0.

Return Value

The dispatch I/O channel or NULL if an error occurred. The returned object is retained before it is returned; it is your responsibility to close the channel and then release this object when you are done using it.

Discussion

You use this function to create a dispatch I/O channel for an already open file descriptor. After calling this function, the system takes control of the specified file descriptor until one of the following occurs:

  • You close the channel by calling the dispatch_io_close function.

  • An unrecoverable error occurs on the file descriptor.

  • All references to the channel are released.

While it controls the file descriptor, the system may modify that file descriptor on behalf of the application. For example, the system typically adds the O_NONBLOCK flag to ensure that any operations on the file descriptor are non-blocking. During that time, it is an error for your application to modify the file descriptor directly. However, you may create additional channels using the same file descriptor.

See Also

Creating a Dispatch I/O Object

dispatch_io_create_with_io

Creates a new dispatch I/O channel from an existing channel.

dispatch_io_create_with_path

Creates a dispatch I/O channel with the associated path name.

dispatch_io_t

A dispatch I/O channel.

dispatch_fd_t

A file descriptor used for I/O operations.

dispatch_io_type_t

The type of a dispatch I/O channel.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software