diff options
Diffstat (limited to 'doc/exec.n')
-rw-r--r-- | doc/exec.n | 358 |
1 files changed, 0 insertions, 358 deletions
diff --git a/doc/exec.n b/doc/exec.n deleted file mode 100644 index f30f6b0..0000000 --- a/doc/exec.n +++ /dev/null @@ -1,358 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: exec.n,v 1.3 1999/04/16 00:46:34 stanton Exp $ -'\" -.so man.macros -.TH exec n 7.6 Tcl "Tcl Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -exec \- Invoke subprocess(es) -.SH SYNOPSIS -\fBexec \fR?\fIswitches\fR? \fIarg \fR?\fIarg ...\fR? -.BE - -.SH DESCRIPTION -.PP -This command treats its arguments as the specification -of one or more subprocesses to execute. -The arguments take the form of a standard shell pipeline -where each \fIarg\fR becomes one word of a command, and -each distinct command becomes a subprocess. -.PP -If the initial arguments to \fBexec\fR start with \fB\-\fR then -they are treated as command-line switches and are not part -of the pipeline specification. The following switches are -currently supported: -.TP 13 -\fB\-keepnewline\fR -Retains a trailing newline in the pipeline's output. -Normally a trailing newline will be deleted. -.TP 13 -\fB\-\|\-\fR -Marks the end of switches. The argument following this one will -be treated as the first \fIarg\fR even if it starts with a \fB\-\fR. -.PP -If an \fIarg\fR (or pair of \fIarg\fR's) has one of the forms -described below then it is used by \fBexec\fR to control the -flow of input and output among the subprocess(es). -Such arguments will not be passed to the subprocess(es). In forms -such as ``< \fIfileName\fR'' \fIfileName\fR may either be in a -separate argument from ``<'' or in the same argument with no -intervening space (i.e. ``<\fIfileName\fR''). -.TP 15 -| -Separates distinct commands in the pipeline. The standard output -of the preceding command will be piped into the standard input -of the next command. -.TP 15 -|& -Separates distinct commands in the pipeline. Both standard output -and standard error of the preceding command will be piped into -the standard input of the next command. -This form of redirection overrides forms such as 2> and >&. -.TP 15 -<\0\fIfileName\fR -The file named by \fIfileName\fR is opened and used as the standard -input for the first command in the pipeline. -.TP 15 -<@\0\fIfileId\fR -\fIFileId\fR must be the identifier for an open file, such as the return -value from a previous call to \fBopen\fR. -It is used as the standard input for the first command in the pipeline. -\fIFileId\fR must have been opened for reading. -.TP 15 -<<\0\fIvalue\fR -\fIValue\fR is passed to the first command as its standard input. -.TP 15 ->\0\fIfileName\fR -Standard output from the last command is redirected to the file named -\fIfileName\fR, overwriting its previous contents. -.TP 15 -2>\0\fIfileName\fR -Standard error from all commands in the pipeline is redirected to the -file named \fIfileName\fR, overwriting its previous contents. -.TP 15 ->&\0\fIfileName\fR -Both standard output from the last command and standard error from all -commands are redirected to the file named \fIfileName\fR, overwriting -its previous contents. -.TP 15 ->>\0\fIfileName\fR -Standard output from the last command is -redirected to the file named \fIfileName\fR, appending to it rather -than overwriting it. -.TP 15 -2>>\0\fIfileName\fR -Standard error from all commands in the pipeline is -redirected to the file named \fIfileName\fR, appending to it rather -than overwriting it. -.TP 15 ->>&\0\fIfileName\fR -Both standard output from the last command and standard error from -all commands are redirected to the file named \fIfileName\fR, -appending to it rather than overwriting it. -.TP 15 ->@\0\fIfileId\fR -\fIFileId\fR must be the identifier for an open file, such as the return -value from a previous call to \fBopen\fR. -Standard output from the last command is redirected to \fIfileId\fR's -file, which must have been opened for writing. -.TP 15 -2>@\0\fIfileId\fR -\fIFileId\fR must be the identifier for an open file, such as the return -value from a previous call to \fBopen\fR. -Standard error from all commands in the pipeline is -redirected to \fIfileId\fR's file. -The file must have been opened for writing. -.TP 15 ->&@\0\fIfileId\fR -\fIFileId\fR must be the identifier for an open file, such as the return -value from a previous call to \fBopen\fR. -Both standard output from the last command and standard error from -all commands are redirected to \fIfileId\fR's file. -The file must have been opened for writing. -.PP -If standard output has not been redirected then the \fBexec\fR -command returns the standard output from the last command -in the pipeline. -If any of the commands in the pipeline exit abnormally or -are killed or suspended, then \fBexec\fR will return an error -and the error message will include the pipeline's output followed by -error messages describing the abnormal terminations; the -\fBerrorCode\fR variable will contain additional information -about the last abnormal termination encountered. -If any of the commands writes to its standard error file and that -standard error isn't redirected, -then \fBexec\fR will return an error; the error message -will include the pipeline's standard output, followed by messages -about abnormal terminations (if any), followed by the standard error -output. -.PP -If the last character of the result or error message -is a newline then that character is normally deleted -from the result or error message. -This is consistent with other Tcl return values, which don't -normally end with newlines. -However, if \fB\-keepnewline\fR is specified then the trailing -newline is retained. -.PP -If standard input isn't redirected with ``<'' or ``<<'' -or ``<@'' then the standard input for the first command in the -pipeline is taken from the application's current standard input. -.PP -If the last \fIarg\fR is ``&'' then the pipeline will be -executed in background. -In this case the \fBexec\fR command will return a list whose -elements are the process identifiers for all of the subprocesses -in the pipeline. -The standard output from the last command in the pipeline will -go to the application's standard output if it hasn't been -redirected, and error output from all of -the commands in the pipeline will go to the application's -standard error file unless redirected. -.PP -The first word in each command is taken as the command name; -tilde-substitution is performed on it, and if the result contains -no slashes then the directories -in the PATH environment variable are searched for -an executable by the given name. -If the name contains a slash then it must refer to an executable -reachable from the current directory. -No ``glob'' expansion or other shell-like substitutions -are performed on the arguments to commands. - -.VS -.SH "PORTABILITY ISSUES" -.TP -\fBWindows\fR (all versions) -. -Reading from or writing to a socket, using the ``\fB@\0\fIfileId\fR'' -notation, does not work. When reading from a socket, a 16-bit DOS -application will hang and a 32-bit application will return immediately with -end-of-file. When either type of application writes to a socket, the -information is instead sent to the console, if one is present, or is -discarded. -.sp -The Tk console text widget does not provide real standard IO capabilities. -Under Tk, when redirecting from standard input, all applications will see an -immediate end-of-file; information redirected to standard output or standard -error will be discarded. -.sp -Either forward or backward slashes are accepted as path separators for -arguments to Tcl commands. When executing an application, the path name -specified for the application may also contain forward or backward slashes -as path separators. Bear in mind, however, that most Windows applications -accept arguments with forward slashes only as option delimiters and -backslashes only in paths. Any arguments to an application that specify a -path name with forward slashes will not automatically be converted to use -the backslash character. If an argument contains forward slashes as the -path separator, it may or may not be recognized as a path name, depending on -the program. -.sp -Additionally, when calling a 16-bit DOS or Windows 3.X application, all path -names must use the short, cryptic, path format (e.g., using ``applba~1.def'' -instead of ``applbakery.default''). -.sp -Two or more forward or backward slashes in a row in a path refer to a -network path. For example, a simple concatenation of the root directory -\fBc:/\fR with a subdirectory \fB/windows/system\fR will yield -\fBc://windows/system\fR (two slashes together), which refers to the mount -point called \fBsystem\fR on the machine called \fBwindows\fR (and the -\fBc:/\fR is ignored), and is not equivalent to \fBc:/windows/system\fR, -which describes a directory on the current computer. The \fBfile join\fR -command should be used to concatenate path components. -.TP -\fBWindows NT\fR -. -When attempting to execute an application, \fBexec\fR first searches for the -name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR -are appended to the end of the specified name and it searches for -the longer name. If a directory name was not specified as part of the -application name, the following directories are automatically searched in -order when attempting to locate the application: -.sp -.RS -.RS -The directory from which the Tcl executable was loaded. -.br -The current directory. -.br -The Windows NT 32-bit system directory. -.br -The Windows NT 16-bit system directory. -.br -The Windows NT home directory. -.br -The directories listed in the path. -.RE -.sp -In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR, -the caller must prepend ``\fBcmd.exe /c\0\fR'' to the desired command. -.sp -.RE -.TP -\fBWindows 95\fR -. -When attempting to execute an application, \fBexec\fR first searches for the -name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR -are appended to the end of the specified name and it searches for -the longer name. If a directory name was not specified as part of the -application name, the following directories are automatically searched in -order when attempting to locate the application: -.sp -.RS -.RS -The directory from which the Tcl executable was loaded. -.br -The current directory. -.br -The Windows 95 system directory. -.br -The Windows 95 home directory. -.br -The directories listed in the path. -.RE -.sp -In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR, -the caller must prepend ``\fBcommand.com /c\0\fR'' to the desired command. -.sp -Once a 16-bit DOS application has read standard input from a console and -then quit, all subsequently run 16-bit DOS applications will see the -standard input as already closed. 32-bit applications do not have this -problem and will run correctly, even after a 16-bit DOS application thinks -that standard input is closed. There is no known workaround for this bug -at this time. -.sp -Redirection between the \fBNUL:\fR device and a 16-bit application does not -always work. When redirecting from \fBNUL:\fR, some applications may hang, -others will get an infinite stream of ``0x01'' bytes, and some will actually -correctly get an immediate end-of-file; the behavior seems to depend upon -something compiled into the application itself. When redirecting greater than -4K or so to \fBNUL:\fR, some applications will hang. The above problems do not -happen with 32-bit applications. -.sp -All DOS 16-bit applications are run synchronously. All standard input from -a pipe to a 16-bit DOS application is collected into a temporary file; the -other end of the pipe must be closed before the 16-bit DOS application -begins executing. All standard output or error from a 16-bit DOS -application to a pipe is collected into temporary files; the application -must terminate before the temporary files are redirected to the next stage -of the pipeline. This is due to a workaround for a Windows 95 bug in the -implementation of pipes, and is how the standard Windows 95 DOS shell -handles pipes itself. -.sp -Certain applications, such as \fBcommand.com\fR, should not be executed -interactively. Applications which directly access the console window, -rather than reading from their standard input and writing to their standard -output may fail, hang Tcl, or even hang the system if their own private -console window is not available to them. -.RE -.TP -\fBWindows 3.X\fR -. -When attempting to execute an application, \fBexec\fR first searches for the -name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR -are appended to the end of the specified name and it searches for -the longer name. If a directory name was not specified as part of the -application name, the following directories are automatically searched in -order when attempting to locate the application: -.sp -.RS -.RS -The directory from which the Tcl executable was loaded. -.br -The current directory. -.br -The Windows 3.X system directory. -.br -The Windows 3.X home directory. -.br -The directories listed in the path. -.RE -.sp -In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR, -the caller must prepend ``\fBcommand.com /c\0\fR'' to the desired command. -.sp -16-bit and 32-bit DOS and Windows applications may be executed. However, -redirection and piping of standard IO only works with 16-bit DOS -applications. 32-bit applications always see standard input as already -closed, and any standard output or error is discarded, no matter where in the -pipeline the application occurs or what redirection symbols are used by the -caller. Additionally, for 16-bit applications, standard error is always -sent to the same place as standard output; it cannot be redirected to a -separate location. In order to achieve pseudo-redirection for 32-bit -applications, the 32-bit application must instead be written to take command -line arguments that specify the files that it should read from and write to -and open those files itself. -.sp -All applications, both 16-bit and 32-bit, run synchronously; each application -runs to completion before the next one in the pipeline starts. Temporary files -are used to simulate piping between applications. The \fBexec\fR -command cannot be used to start an application in the background. -.sp -When standard input is redirected from an open file using the -``\fB@\0\fIfileId\fR'' notation, the open file is completely read up to its -end. This is slightly different than under Windows 95 or NT, where the child -application consumes from the open file only as much as it wants. -Redirecting to an open file is supported as normal. -.RE -.TP -\fBMacintosh\fR -The \fBexec\fR command is not implemented and does not exist under Macintosh. -.TP -\fBUnix\fR\0\0\0\0\0\0\0 -The \fBexec\fR command is fully functional and works as described. - -.SH "SEE ALSO" -open(n) -.VE - -.SH KEYWORDS -execute, pipeline, redirection, subprocess - |