diff options
Diffstat (limited to 'usr/man/mann/exec.n')
| -rwxr-xr-x | usr/man/mann/exec.n | 706 |
1 files changed, 706 insertions, 0 deletions
diff --git a/usr/man/mann/exec.n b/usr/man/mann/exec.n new file mode 100755 index 000000000..a4d62954a --- /dev/null +++ b/usr/man/mann/exec.n @@ -0,0 +1,706 @@ +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 2006 Donal K. Fellows. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.\" The -*- nroff -*- 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 ?manpage? +.\" Start of list of standard options for a Tk widget. The manpage +.\" argument defines where to look up the standard options; if +.\" omitted, defaults to "options". The options follow on successive +.\" lines, in three 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. +.\" +.\" .QW arg1 ?arg2? +.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). +.\" +.\" .PQ arg1 ?arg2? +.\" Print an open parenthesis, arg1 in quotes, then arg2 normally +.\" (for trailing punctuation) and then a closing parenthesis. +.\" +.\" # 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 +'ie '\\$1'' .ds So \\fBoptions\\fR +'el .ds So \\fB\\$1\\fR +.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 \\*(So 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 +.. +.\" # UL - underline word +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.\" # QW - apply quotation marks to word +.de QW +.ie '\\*(lq'"' ``\\$1''\\$2 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\$2 +.. +.\" # PQ - apply parens and quotation marks to word +.de PQ +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 +.\"" fix emacs highlighting +.el (\\*(lq\\$1\\*(rq\\$2)\\$3 +.. +.\" # QR - quoted range +.de QR +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 +.. +.\" # MT - "empty" string +.de MT +.QW "" +.. +.TH exec n 8.5 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +exec \- Invoke subprocesses +.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\-ignorestderr\fR +.VS 8.5 +Stops the \fBexec\fR command from treating the output of messages to the +pipeline's standard error channel as an error case. +.VE 8.5 +.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\fRs) 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 +.QW "\fB<\fR \fIfileName\fR" , +\fIfileName\fR may either be in a separate argument from +.QW \fB<\fR +or in the same argument with no intervening space (i.e. +.QW \fB<\fIfileName\fR ). +.TP 15 +\fB|\fR +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 +\fB|&\fR +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 +\fB<\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 +\fB<@\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 +\fB<<\0\fIvalue\fR +\fIValue\fR is passed to the first command as its standard input. +.TP 15 +\fB>\0\fIfileName\fR +Standard output from the last command is redirected to the file named +\fIfileName\fR, overwriting its previous contents. +.TP 15 +\fB2>\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 +\fB>&\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 +\fB>>\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 +\fB2>>\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 +\fB>>&\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 +\fB>@\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 +\fB2>@\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 +\fB2>@1\0\fR +Standard error from all commands in the pipeline is redirected to the +command result. This operator is only valid at the end of the command +pipeline. +.TP 15 +\fB>&@\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, +.VS 8.5 +unless +.QW 2>@1 +was specified, in which case standard error is included as well. +.VE 8.5 +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 +\fB\-errorcode\fR return option 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 is not redirected +.VS 8.5 +and \fB\-ignorestderr\fR is not specified, +.VE 8.5 +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 do not +normally end with newlines. +However, if \fB\-keepnewline\fR is specified then the trailing +newline is retained. +.PP +If standard input is not redirected with +.QW < , +.QW << +or +.QW <@ +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 +.QW & +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 has not 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 +.QW glob +expansion or other shell-like substitutions +are performed on the arguments to commands. +.SH "PORTABILITY ISSUES" +.TP +\fBWindows\fR (all versions) +. +Reading from or writing to a socket, using the +.QW \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. +.RS +.PP +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. +.PP +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. +.PP +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 +.QW applba~1.def +instead of +.QW applbakery.default ), +which can be obtained with the +.QW "\fBfile attributes \fIfileName \fB\-shortname\fR" +command. +.PP +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. +.PP +Note that there are two general types of Win32 console applications: +.RS +.IP [1] +CLI \(em CommandLine Interface, simple stdio exchange. \fBnetstat.exe\fR for +example. +.IP [2] +TUI \(em 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 +.PP +\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 communicating with a TUI application. +.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: +.RS +.IP \(bu +The directory from which the Tcl executable was loaded. +.IP \(bu +The current directory. +.IP \(bu +The Windows NT 32-bit system directory. +.IP \(bu +The Windows NT 16-bit system directory. +.IP \(bu +The Windows NT home directory. +.IP \(bu +The directories listed in the path. +.PP +In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR, +the caller must prepend the desired command with +.QW "\fBcmd.exe /c\0\fR" +because built-in commands are not implemented using executables. +.RE +.TP +\fBWindows 9x\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: +.RS +.IP \(bu +The directory from which the Tcl executable was loaded. +.IP \(bu +The current directory. +.IP \(bu +The Windows 9x system directory. +.IP \(bu +The Windows 9x home directory. +.IP \(bu +The directories listed in the path. +.RE +.RS +.PP +In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR, +the caller must prepend the desired command with +.QW "\fBcommand.com /c\0\fR" +because built-in commands are not implemented using executables. +.PP +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. +.PP +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 +.QW 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. +.PP +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. +.PP +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 +\fBUnix\fR\0\0\0\0\0\0\0 +The \fBexec\fR command is fully functional and works as described. +.SH "UNIX EXAMPLES" +Here are some examples of the use of the \fBexec\fR command on Unix. +.PP +To execute a simple program and get its result: +.CS +\fBexec\fR uname -a +.CE +.PP +To execute a program that can return a non-zero result, you should +wrap the call to \fBexec\fR in \fBcatch\fR and check the contents +of the \fB\-errorcode\fR return option if you have an error: +.CS +set status 0 +if {[catch {\fBexec\fR grep foo bar.txt} results options]} { + set details [dict get $options -errorcode] + if {[lindex $details 0] eq "CHILDSTATUS"} { + set status [lindex $details 2] + } else { + # Some kind of unexpected failure + } +} +.CE +.PP +When translating a command from a Unix shell invocation, care should +be taken over the fact that single quote characters have no special +significance to Tcl. Thus: +.CS +awk '{sum += $1} END {print sum}' numbers.list +.CE +would be translated into something like: +.CS +\fBexec\fR awk {{sum += $1} END {print sum}} numbers.list +.CE +.PP +If you are converting invocations involving shell globbing, you should +remember that Tcl does not handle globbing or expand things into +multiple arguments by default. Instead you should write things like +this: +.CS +\fBexec\fR ls -l {*}[glob *.tcl] +.CE +.SH "WINDOWS EXAMPLES" +Here are some examples of the use of the \fBexec\fR command on Windows. +.PP +To start an instance of \fInotepad\fR editing a file without waiting +for the user to finish editing the file: +.CS +\fBexec\fR notepad myfile.txt & +.CE +.PP +To print a text file using \fInotepad\fR: +.CS +\fBexec\fR notepad /p myfile.txt +.CE +.PP +If a program calls other programs, such as is common with compilers, +then you may need to resort to batch files to hide the console windows +that sometimes pop up: +.CS +\fBexec\fR cmp.bat somefile.c -o somefile +.CE +With the file \fIcmp.bat\fR looking something like: +.CS +@gcc %1 %2 %3 %4 %5 %6 %7 %8 %9 +.CE +.PP +Sometimes you need to be careful, as different programs may have the +same name and be in the path. It can then happen that typing a command +at the DOS prompt finds \fIa different program\fR than the same +command run via \fBexec\fR. This is because of the (documented) +differences in behaviour between \fBexec\fR and DOS batch files. +.PP +When in doubt, use the command \fBauto_execok\fR: it will return the +complete path to the program as seen by the \fBexec\fR command. This +applies especially when you want to run +.QW internal +commands like +\fIdir\fR from a Tcl script (if you just want to list filenames, use +the \fBglob\fR command.) To do that, use this: +.CS +\fBexec\fR {*}[auto_execok dir] *.tcl +.CE +.SH "SEE ALSO" +error(n), open(n) +.SH KEYWORDS +execute, pipeline, redirection, subprocess |