| '\" |
| '\" 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.6 2002/04/23 19:06:10 hobbs Exp $ |
| '\" |
| '\" The definitions below are for supplemental macros used in Tcl/Tk |
| '\" manual entries. |
| '\" |
| '\" .AP type name in/out ?indent? |
| '\" Start paragraph describing an argument to a library procedure. |
| '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| '\" or "in/out" to describe whether procedure reads or modifies arg, |
| '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| '\" needed; use .AS below instead) |
| '\" |
| '\" .AS ?type? ?name? |
| '\" Give maximum sizes of arguments for setting tab stops. Type and |
| '\" name are examples of largest possible arguments that will be passed |
| '\" to .AP later. If args are omitted, default tab stops are used. |
| '\" |
| '\" .BS |
| '\" Start box enclosure. From here until next .BE, everything will be |
| '\" enclosed in one large box. |
| '\" |
| '\" .BE |
| '\" End of box enclosure. |
| '\" |
| '\" .CS |
| '\" Begin code excerpt. |
| '\" |
| '\" .CE |
| '\" End code excerpt. |
| '\" |
| '\" .VS ?version? ?br? |
| '\" Begin vertical sidebar, for use in marking newly-changed parts |
| '\" of man pages. The first argument is ignored and used for recording |
| '\" the version when the .VS was added, so that the sidebars can be |
| '\" found and removed when they reach a certain age. If another argument |
| '\" is present, then a line break is forced before starting the sidebar. |
| '\" |
| '\" .VE |
| '\" End of vertical sidebar. |
| '\" |
| '\" .DS |
| '\" Begin an indented unfilled display. |
| '\" |
| '\" .DE |
| '\" End of indented unfilled display. |
| '\" |
| '\" .SO |
| '\" Start of list of standard options for a Tk widget. The |
| '\" options follow on successive lines, in four columns separated |
| '\" by tabs. |
| '\" |
| '\" .SE |
| '\" End of list of standard options for a Tk widget. |
| '\" |
| '\" .OP cmdName dbName dbClass |
| '\" Start of description of a specific option. cmdName gives the |
| '\" option's name as specified in the class command, dbName gives |
| '\" the option's name in the option database, and dbClass gives |
| '\" the option's class in the option database. |
| '\" |
| '\" .UL arg1 arg2 |
| '\" Print arg1 underlined, then print arg2 normally. |
| '\" |
| '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| '\" |
| '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| .if t .wh -1.3i ^B |
| .nr ^l \n(.l |
| .ad b |
| '\" # Start an argument description |
| .de AP |
| .ie !"\\$4"" .TP \\$4 |
| .el \{\ |
| . ie !"\\$2"" .TP \\n()Cu |
| . el .TP 15 |
| .\} |
| .ta \\n()Au \\n()Bu |
| .ie !"\\$3"" \{\ |
| \&\\$1 \\fI\\$2\\fP (\\$3) |
| .\".b |
| .\} |
| .el \{\ |
| .br |
| .ie !"\\$2"" \{\ |
| \&\\$1 \\fI\\$2\\fP |
| .\} |
| .el \{\ |
| \&\\fI\\$1\\fP |
| .\} |
| .\} |
| .. |
| '\" # define tabbing values for .AP |
| .de AS |
| .nr )A 10n |
| .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| .nr )B \\n()Au+15n |
| .\" |
| .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| .. |
| .AS Tcl_Interp Tcl_CreateInterp in/out |
| '\" # BS - start boxed text |
| '\" # ^y = starting y location |
| '\" # ^b = 1 |
| .de BS |
| .br |
| .mk ^y |
| .nr ^b 1u |
| .if n .nf |
| .if n .ti 0 |
| .if n \l'\\n(.lu\(ul' |
| .if n .fi |
| .. |
| '\" # BE - end boxed text (draw box now) |
| .de BE |
| .nf |
| .ti 0 |
| .mk ^t |
| .ie n \l'\\n(^lu\(ul' |
| .el \{\ |
| .\" Draw four-sided box normally, but don't draw top of |
| .\" box if the box started on an earlier page. |
| .ie !\\n(^b-1 \{\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .el \}\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .\} |
| .fi |
| .br |
| .nr ^b 0 |
| .. |
| '\" # VS - start vertical sidebar |
| '\" # ^Y = starting y location |
| '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| .de VS |
| .if !"\\$2"" .br |
| .mk ^Y |
| .ie n 'mc \s12\(br\s0 |
| .el .nr ^v 1u |
| .. |
| '\" # VE - end of vertical sidebar |
| .de VE |
| .ie n 'mc |
| .el \{\ |
| .ev 2 |
| .nf |
| .ti 0 |
| .mk ^t |
| \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| .sp -1 |
| .fi |
| .ev |
| .\} |
| .nr ^v 0 |
| .. |
| '\" # Special macro to handle page bottom: finish off current |
| '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| '\" # page bottom macro. |
| .de ^B |
| .ev 2 |
| 'ti 0 |
| 'nf |
| .mk ^t |
| .if \\n(^b \{\ |
| .\" Draw three-sided box if this is the box's first page, |
| .\" draw two sides but no top otherwise. |
| .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .\} |
| .if \\n(^v \{\ |
| .nr ^x \\n(^tu+1v-\\n(^Yu |
| \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| .\} |
| .bp |
| 'fi |
| .ev |
| .if \\n(^b \{\ |
| .mk ^y |
| .nr ^b 2 |
| .\} |
| .if \\n(^v \{\ |
| .mk ^Y |
| .\} |
| .. |
| '\" # DS - begin display |
| .de DS |
| .RS |
| .nf |
| .sp |
| .. |
| '\" # DE - end display |
| .de DE |
| .fi |
| .RE |
| .sp |
| .. |
| '\" # SO - start of list of standard options |
| .de SO |
| .SH "STANDARD OPTIONS" |
| .LP |
| .nf |
| .ta 5.5c 11c |
| .ft B |
| .. |
| '\" # SE - end of list of standard options |
| .de SE |
| .fi |
| .ft R |
| .LP |
| See the \\fBoptions\\fR manual entry for details on the standard options. |
| .. |
| '\" # OP - start of full description for a single option |
| .de OP |
| .LP |
| .nf |
| .ta 4c |
| Command-Line Name: \\fB\\$1\\fR |
| Database Name: \\fB\\$2\\fR |
| Database Class: \\fB\\$3\\fR |
| .fi |
| .IP |
| .. |
| '\" # CS - begin code excerpt |
| .de CS |
| .RS |
| .nf |
| .ta .25i .5i .75i 1i |
| .. |
| '\" # CE - end code excerpt |
| .de CE |
| .fi |
| .RE |
| .. |
| .de UL |
| \\$1\l'|0\(ul'\\$2 |
| .. |
| .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''), which can be obtained with the |
| \fBfile attributes $fileName -shortname\fR command. |
| .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. |
| .sp |
| .RS |
| Note that there are two general types of Win32 console applications: |
| .RS |
| 1) CLI -- CommandLine Interface, simple stdio exchange. \fBnetstat.exe\fR for |
| example. |
| .br |
| 2) TUI -- Textmode User Interface, any application that accesses the console |
| API for doing such things as cursor movement, setting text color, detecting |
| key presses and mouse movement, etc... An example would be \fBtelnet.exe\fR |
| from Windows 2000. These types of applications are not common in a windows |
| environment, but do exist. |
| .RE |
| \fBexec\fR will not work well with TUI applications when a console is not |
| present, as is done when launching applications under wish. It is desirable |
| to have console applications hidden and detached. This is a designed-in |
| limitation as \fBexec\fR wants to communicate over pipes. The Expect |
| extension addresses this issue when communication between a TUI application |
| is desired. |
| .sp |
| .RE |
| .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 |
| \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" |
| error(n), open(n) |
| |
| .SH KEYWORDS |
| execute, pipeline, redirection, subprocess |