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
     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 occured 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.