133 lines
3.7 KiB
Plaintext
133 lines
3.7 KiB
Plaintext
'\"!tbl|mmdoc
|
|
'\"macro stdmacro
|
|
.TH datapipe 3X
|
|
.SH NAME
|
|
datapipe:
|
|
dpipeCreate,
|
|
dpipeDestroy,
|
|
dpipeTransfer,
|
|
dpipeReset,
|
|
dpipeFlush\- data pipe operations.
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\f4#include <dpipe.h>\f1
|
|
.PP
|
|
\f4int dpipeCreate (int src_fd, int sink_fd);\f1
|
|
.PP
|
|
\f4int dpipeDestroy (int pipefd);\f1
|
|
.PP
|
|
\f4__int64_t dpipeTransfer (int pipefd, dpipe_lib_hdl_t src_context,
|
|
dpipe_lib_hdl_t sink_context);\f1
|
|
.PP
|
|
\f4int dpipeStop (int pipefd, __int64_t transfer_id);\f1
|
|
.PP
|
|
\f4int dpipeReset (int pipefd);\f1
|
|
.PP
|
|
\f4int dpipeFlush (int pipefd);\f1
|
|
.PP
|
|
\f4int dpipeStatus (int pipefd, __int64_t transfer_id);\f1
|
|
.SH 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.
|
|
.PP
|
|
.B dpipeCreate
|
|
creates a data pipe between two file descriptors:
|
|
.I src_fd
|
|
is the source file descriptor, and
|
|
.I 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
|
|
.B 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.
|
|
.PP
|
|
.B 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).
|
|
.PP
|
|
.B dpipeDestroy
|
|
halts all data flow between source and sink and destroys the data pipe.
|
|
.PP
|
|
.B dpipeTransfer
|
|
starts the data flow in the data pipe specified by
|
|
.I pipefd.
|
|
.I src_context
|
|
and
|
|
.I sink_context
|
|
are handles to the transfer context that has been setup by the two
|
|
pipe ends before
|
|
.B dpipeTransfer
|
|
is called (see below). This is an asynchronous IO operation. In order
|
|
to reference this transfer later,
|
|
.B dpipeTransfer
|
|
returns a transfer id (non negative) for the application to identify
|
|
a particular transfer. It is unique within a data pipe.
|
|
.PP
|
|
Each pipe end has its own way to set up the transfer context. In the
|
|
regular file case, see
|
|
.B dpipe_fspe_get_hdl(3x)
|
|
and
|
|
.B dpipe_fspe_set_ctx(3x).
|
|
For early access, only xfs file system supports data pipe.
|
|
.PP
|
|
.B dpipeStop
|
|
stops the transfer specified by
|
|
.I pipefd
|
|
and
|
|
.I transfer_id.
|
|
.PP
|
|
.B 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.
|
|
.PP
|
|
.B dpipeStatus
|
|
returns the status of the transfer specified by
|
|
.I pipefd
|
|
and
|
|
.I transfer_id.
|
|
The potential values are:
|
|
.TP 25
|
|
DPIPE_TRANS_COMPLETE
|
|
The transfer is completed successfully.
|
|
.TP 25
|
|
DPIPE_TRANS_PENDING
|
|
The transfer is still pending.
|
|
.TP 25
|
|
DPIPE_TRANS_CANCELLED
|
|
The transfer is cancelled. It's the result of
|
|
.B dpipeStop().
|
|
.TP 25
|
|
DPIPE_TRANS_ERROR
|
|
The transfer failed.
|
|
.SH DIAGNOSTICS
|
|
On success,
|
|
.B dpipeStatus
|
|
returns the status value (which is always non-negative);
|
|
.B 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:
|
|
.TP 10
|
|
[EBADFD]
|
|
The file descriptors is invalid.
|
|
.TP 10
|
|
[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.
|
|
.SH FILES
|
|
/usr/share/src/irix/examples/dpipe/src/dpcp.c is an example which
|
|
copies one regular file to another.
|
|
|