115 lines
5.1 KiB
Groff
115 lines
5.1 KiB
Groff
'\"
|
|
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
|
'\" All rights reserved.
|
|
'\"
|
|
'\" Permission is hereby granted, without written agreement and without
|
|
'\" license or royalty fees, to use, copy, modify, and distribute this
|
|
'\" documentation for any purpose, provided that the above copyright
|
|
'\" notice and the following two paragraphs appear in all copies.
|
|
'\"
|
|
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
|
|
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
|
|
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
|
|
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
'\"
|
|
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
|
|
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
'\" AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
|
|
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
|
|
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
|
|
'\"
|
|
'\" $Header: /user6/ouster/tcl/man/RCS/CrtPipelin.3,v 1.7 93/04/09 11:53:47 ouster Exp $ SPRITE (Berkeley)
|
|
'\"
|
|
.so man.macros
|
|
.HS Tcl_CreatePipeline tclc
|
|
.BS
|
|
.SH NAME
|
|
Tcl_CreatePipeline \- create one or more child processes, with I/O redirection
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
int
|
|
\fBTcl_CreatePipeline\fR(\fIinterp, argc, argv, pidArrayPtr, inPipePtr, outPipePtr, errFilePtr\fR)
|
|
.SH ARGUMENTS
|
|
.AS Tcl_Interp **pidArrayPtr
|
|
.AP Tcl_Interp *interp in
|
|
Interpreter to use for error reporting.
|
|
.AP int argc in
|
|
Number of strings in \fIargv\fR array.
|
|
.AP char **argv in
|
|
Array of strings describing command(s) and I/O redirection.
|
|
.AP int **pidArrayPtr out
|
|
The value at \fI*pidArrayPtr\fR is modified to hold a pointer to
|
|
an array of process identifiers. The array is dynamically
|
|
allocated and must be freed by the caller.
|
|
.AP int *inPipePtr out
|
|
If this argument is NULL then standard input for the first command
|
|
in the pipeline comes from the current standard input.
|
|
If \fIinPipePtr\fR is not NULL then \fBTcl_CreatePipeline\fR will
|
|
create a pipe, arrange for it to be used for standard input
|
|
to the first command,
|
|
and store a file id for writing to that pipe at \fI*inPipePtr\fR.
|
|
If the command specified its own input using redirection, then
|
|
no pipe is created and -1 is stored at \fI*inPipePtr\fR.
|
|
.AP int *outPipePtr out
|
|
If this argument is NULL then standard output for the last command
|
|
in the pipeline goes to the current standard output.
|
|
If \fIoutPipePtr\fR is not NULL then \fBTcl_CreatePipeline\fR will
|
|
create a pipe, arrange for it to be used for standard output from
|
|
the last command, and store a file id for reading from that
|
|
pipe at \fI*outPipePtr\fR.
|
|
If the command specified its own output using redirection then
|
|
no pipe is created and -1 is stored at \fI*outPipePtr\fR.
|
|
.AP int *errFilePtr out
|
|
If this argument is NULL then error output for all the commands
|
|
in the pipeline will go to the current standard error file.
|
|
If \fIerrFilePtr\fR is not NULL, error output from all the commands
|
|
in the pipeline will go to a temporary file created by
|
|
\fBTcl_CreatePipeline\fR.
|
|
A file id to read from that file will be stored at \fI*errFilePtr\fR.
|
|
The file will already have been removed, so closing the file
|
|
descriptor at \fI*errFilePtr\fR will cause the file to be flushed
|
|
completely.
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
\fBTcl_CreatePipeline\fR processes the \fIargv\fR array and sets
|
|
up one or more child processes in a pipeline configuration.
|
|
\fBTcl_CreatePipeline\fR handles pipes specified with ``|'',
|
|
input redirection specified with ``<'' or ``<<'', and output
|
|
redirection specified with ``>''; see the documentation for
|
|
the \fBexec\fR command for details on these specifications.
|
|
The return value from \fBTcl_CreatePipeline\fR is a count of
|
|
the number of child processes created; the process identifiers
|
|
for those processes are stored in a \fImalloc\fR-ed array and
|
|
a pointer to that array is stored at \fI*pidArrayPtr\fR.
|
|
It is the caller's responsibility to free the array when finished
|
|
with it.
|
|
.PP
|
|
If the \fIinPipePtr\fR, \fIoutPipePtr\fR, and \fIerrFilePtr\fR
|
|
arguments are NULL then the pipeline's standard input, standard
|
|
output, and standard error are taken from the corresponding
|
|
streams of the process. Non-NULL values may be specified for
|
|
these arguments to use pipes for standard input and standard
|
|
output and a file for standard error. \fBTcl_CreatePipeline\fR
|
|
will create the requested pipes or file and return file identifiers
|
|
that may be used to read or write them. It is the caller's
|
|
responsibility to close all of these files when they are no
|
|
longer needed. If \fIargv\fR specifies redirection for standard
|
|
input or standard output, then pipes will not be created even
|
|
if requested by the \fIinPipePtr\fR and \fIoutPipePtr\fR
|
|
arguments.
|
|
.PP
|
|
If an error occurs in \fBTcl_CreatePipeline\fR (e.g. ``|'' or
|
|
``<'' was the last argument in \fIargv\fR, or it wasn't possible
|
|
to fork off a child), then -1 is returned
|
|
and \fIinterp->result\fR is set to an error message.
|
|
|
|
.SH "SEE ALSO"
|
|
\fBTcl_DetachPids\fR, \fBTcl_ReapDetachedProcs\fR
|
|
|
|
.SH KEYWORDS
|
|
background, child, detach, fork, process, status, wait
|