datapipe(3X)datapipe(3X)NAME
datapipe: dpipeCreate, dpipeDestroy, dpipeTransfer, dpipeReset,
dpipeFlush- data pipe operations.
SYNOPSIS
#include <dpipe.h>
int dpipeCreate (int src_fd, int sink_fd);
int dpipeDestroy (int pipefd);
__int64_t dpipeTransfer (int pipefd, dpipe_lib_hdl_t src_context,
dpipe_lib_hdl_t sink_context);
int dpipeStop (int pipefd, __int64_t transfer_id);
int dpipeReset (int pipefd);
int dpipeFlush (int pipefd);
int dpipeStatus (int pipefd, __int64_t transfer_id);
DESCRIPTION
Data pipes are dynamic connections between two hardware devices that
support peer-to-peer data transfers. These connections are created by an
application to process a data stream from a source device to a sink
device. The purpose is to have minimum system impact during I/O
operations.
dpipeCreate creates a data pipe between two file descriptors: src_fd is
the source file descriptor, and sink_fd is the sink file descriptor.
Either file descriptor can refer to a regular file, a special device
file, or potentially a socket (not available for now). Both should be
open when passed to dpipeCreate and should keep open during the course of
the data pipe operation. If any one is closed, the data pipe will not
function correctly.
dpipeCreate returns a file descriptor as a handler to the data pipe.
This handler is used in other data pipe routines to reference the data
pipe that is created. This is also used when bandwidth allocation is
requested on the data pipe (Note: priority bandwidth allocation is not
supported for early access).
dpipeDestroy halts all data flow between source and sink and destroys the
data pipe.
dpipeTransfer starts the data flow in the data pipe specified by pipefd.
src_context and sink_context are handles to the transfer context that has
been setup by the two pipe ends before dpipeTransfer is called (see
below). This is an asynchronous IO operation. In order to reference this
transfer later, dpipeTransfer returns a transfer id (non negative) for
the application to identify a particular transfer. It is unique within a
Page 1
datapipe(3X)datapipe(3X)
data pipe.
Each pipe end has its own way to set up the transfer context. In the
regular file case, see dpipe_fspe_get_hdl(3x) and dpipe_fspe_set_ctx(3x).
For early access, only xfs file system supports data pipe.
dpipeStop stops the transfer specified by pipefd and transfer_id.
dpipeFlush returns only after all the pending transfers in a data pipe
are completed or when an error occurred during the transfer. It is
useful, for example, when the application wishes to close one pipe end
but is not sure whether the transfer is over.
dpipeStatus returns the status of the transfer specified by pipefd and
transfer_id. The potential values are:
DPIPE_TRANS_COMPLETE The transfer is completed successfully.
DPIPE_TRANS_PENDING The transfer is still pending.
DPIPE_TRANS_CANCELLED The transfer is cancelled. It's the result of
dpipeStop().
DPIPE_TRANS_ERROR The transfer failed.
DIAGNOSTICS
On success, dpipeStatus returns the status value (which is always non-
negative); dpipeTransfer returns transfer id (always non negative); all
other routines return 0. On failure, all the routines return -1 and errno
is set to one of the following:
[EBADFD] The file descriptors is invalid.
[EINVAL] One or more of the parameters are invalid. [EOPNOTSUPP] The
operation is not supported on the system. [ENOMEM] Not enough
space for memory allocation.
FILES
/usr/share/src/irix/examples/dpipe/src/dpcp.c is an example which copies
one regular file to another.
Page 2