home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tcl2-73c.zip / tcl7.3 / doc / CrtPipelin.3 < prev    next >
Text File  |  1993-04-09  |  5KB  |  115 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/CrtPipelin.3,v 1.7 93/04/09 11:53:47 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tcl_CreatePipeline tclc
  25. .BS
  26. .SH NAME
  27. Tcl_CreatePipeline \- create one or more child processes, with I/O redirection
  28. .SH SYNOPSIS
  29. .nf
  30. \fB#include <tcl.h>\fR
  31. .sp
  32. int
  33. \fBTcl_CreatePipeline\fR(\fIinterp, argc, argv, pidArrayPtr, inPipePtr, outPipePtr, errFilePtr\fR)
  34. .SH ARGUMENTS
  35. .AS Tcl_Interp **pidArrayPtr
  36. .AP Tcl_Interp *interp in
  37. Interpreter to use for error reporting.
  38. .AP int argc in
  39. Number of strings in \fIargv\fR array.
  40. .AP char **argv in
  41. Array of strings describing command(s) and I/O redirection.
  42. .AP int **pidArrayPtr out
  43. The value at \fI*pidArrayPtr\fR is modified to hold a pointer to
  44. an array of process identifiers.  The array is dynamically
  45. allocated and must be freed by the caller.
  46. .AP int *inPipePtr out
  47. If this argument is NULL then standard input for the first command
  48. in the pipeline comes from the current standard input.
  49. If \fIinPipePtr\fR is not NULL then \fBTcl_CreatePipeline\fR will
  50. create a pipe, arrange for it to be used for standard input
  51. to the first command,
  52. and store a file id for writing to that pipe at \fI*inPipePtr\fR.
  53. If the command specified its own input using redirection, then
  54. no pipe is created and -1 is stored at \fI*inPipePtr\fR.
  55. .AP int *outPipePtr out
  56. If this argument is NULL then standard output for the last command
  57. in the pipeline goes to the current standard output.
  58. If \fIoutPipePtr\fR is not NULL then \fBTcl_CreatePipeline\fR will
  59. create a pipe, arrange for it to be used for standard output from
  60. the last command, and store a file id for reading from that
  61. pipe at \fI*outPipePtr\fR.
  62. If the command specified its own output using redirection then
  63. no pipe is created and -1 is stored at \fI*outPipePtr\fR.
  64. .AP int *errFilePtr out
  65. If this argument is NULL then error output for all the commands
  66. in the pipeline will go to the current standard error file.
  67. If \fIerrFilePtr\fR is not NULL, error output from all the commands
  68. in the pipeline will go to a temporary file created by
  69. \fBTcl_CreatePipeline\fR.
  70. A file id to read from that file will be stored at \fI*errFilePtr\fR.
  71. The file will already have been removed, so closing the file
  72. descriptor at \fI*errFilePtr\fR will cause the file to be flushed
  73. completely.
  74. .BE
  75.  
  76. .SH DESCRIPTION
  77. .PP
  78. \fBTcl_CreatePipeline\fR processes the \fIargv\fR array and sets
  79. up one or more child processes in a pipeline configuration.
  80. \fBTcl_CreatePipeline\fR handles pipes specified with ``|'',
  81. input redirection specified with ``<'' or ``<<'', and output
  82. redirection specified with ``>'';  see the documentation for
  83. the \fBexec\fR command for details on these specifications.
  84. The return value from \fBTcl_CreatePipeline\fR is a count of
  85. the number of child processes created;  the process identifiers
  86. for those processes are stored in a \fImalloc\fR-ed array and
  87. a pointer to that array is stored at \fI*pidArrayPtr\fR.
  88. It is the caller's responsibility to free the array when finished
  89. with it.
  90. .PP
  91. If the \fIinPipePtr\fR, \fIoutPipePtr\fR, and \fIerrFilePtr\fR
  92. arguments are NULL then the pipeline's standard input, standard
  93. output, and standard error are taken from the corresponding
  94. streams of the process.  Non-NULL values may be specified for
  95. these arguments to use pipes for standard input and standard
  96. output and a file for standard error.  \fBTcl_CreatePipeline\fR
  97. will create the requested pipes or file and return file identifiers
  98. that may be used to read or write them.  It is the caller's
  99. responsibility to close all of these files when they are no
  100. longer needed.  If \fIargv\fR specifies redirection for standard
  101. input or standard output, then pipes will not be created even
  102. if requested by the \fIinPipePtr\fR and \fIoutPipePtr\fR
  103. arguments.
  104. .PP
  105. If an error occurs in \fBTcl_CreatePipeline\fR (e.g. ``|'' or
  106. ``<'' was the last argument in \fIargv\fR, or it wasn't possible
  107. to fork off a child), then -1 is returned
  108. and \fIinterp->result\fR is set to an error message.
  109.  
  110. .SH "SEE ALSO"
  111. \fBTcl_DetachPids\fR, \fBTcl_ReapDetachedProcs\fR
  112.  
  113. .SH KEYWORDS
  114. background, child, detach, fork, process, status, wait
  115.