2 '\" Copyright (c) 1993 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
4 '\" Copyright (c) 2006 Donal K. Fellows.
6 '\" See the file "license.terms" for information on usage and redistribution
7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
9 .TH exec n 8.5 Tcl "Tcl Built-In Commands"
10 .\" The -*- nroff -*- definitions below are for supplemental macros used
11 .\" in Tcl/Tk manual entries.
13 .\" .AP type name in/out ?indent?
14 .\" Start paragraph describing an argument to a library procedure.
15 .\" type is type of argument (int, etc.), in/out is either "in", "out",
16 .\" or "in/out" to describe whether procedure reads or modifies arg,
17 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
18 .\" needed; use .AS below instead)
21 .\" Give maximum sizes of arguments for setting tab stops. Type and
22 .\" name are examples of largest possible arguments that will be passed
23 .\" to .AP later. If args are omitted, default tab stops are used.
26 .\" Start box enclosure. From here until next .BE, everything will be
27 .\" enclosed in one large box.
30 .\" End of box enclosure.
33 .\" Begin code excerpt.
38 .\" .VS ?version? ?br?
39 .\" Begin vertical sidebar, for use in marking newly-changed parts
40 .\" of man pages. The first argument is ignored and used for recording
41 .\" the version when the .VS was added, so that the sidebars can be
42 .\" found and removed when they reach a certain age. If another argument
43 .\" is present, then a line break is forced before starting the sidebar.
46 .\" End of vertical sidebar.
49 .\" Begin an indented unfilled display.
52 .\" End of indented unfilled display.
55 .\" Start of list of standard options for a Tk widget. The manpage
56 .\" argument defines where to look up the standard options; if
57 .\" omitted, defaults to "options". The options follow on successive
58 .\" lines, in three columns separated by tabs.
61 .\" End of list of standard options for a Tk widget.
63 .\" .OP cmdName dbName dbClass
64 .\" Start of description of a specific option. cmdName gives the
65 .\" option's name as specified in the class command, dbName gives
66 .\" the option's name in the option database, and dbClass gives
67 .\" the option's class in the option database.
70 .\" Print arg1 underlined, then print arg2 normally.
73 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
76 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
77 .\" (for trailing punctuation) and then a closing parenthesis.
79 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
83 .\" # Start an argument description
87 . ie !"\\$2"" .TP \\n()Cu
92 \&\\$1 \\fI\\$2\\fP (\\$3)
105 .\" # define tabbing values for .AP
108 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
111 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
112 .nr )C \\n()Bu+\\w'(in/out)'u+2n
114 .AS Tcl_Interp Tcl_CreateInterp in/out
115 .\" # BS - start boxed text
116 .\" # ^y = starting y location
124 .if n \l'\\n(.lu\(ul'
127 .\" # BE - end boxed text (draw box now)
132 .ie n \l'\\n(^lu\(ul'
134 .\" Draw four-sided box normally, but don't draw top of
135 .\" box if the box started on an earlier page.
137 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
140 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
147 .\" # VS - start vertical sidebar
148 .\" # ^Y = starting y location
149 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
153 .ie n 'mc \s12\(br\s0
156 .\" # VE - end of vertical sidebar
164 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
171 .\" # Special macro to handle page bottom: finish off current
172 .\" # box/sidebar if in box/sidebar mode, then invoked standard
173 .\" # page bottom macro.
180 .\" Draw three-sided box if this is the box's first page,
181 .\" draw two sides but no top otherwise.
182 .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
183 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
186 .nr ^x \\n(^tu+1v-\\n(^Yu
187 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
200 .\" # DS - begin display
206 .\" # DE - end display
212 .\" # SO - start of list of standard options
214 'ie '\\$1'' .ds So \\fBoptions\\fR
215 'el .ds So \\fB\\$1\\fR
216 .SH "STANDARD OPTIONS"
222 .\" # SE - end of list of standard options
227 See the \\*(So manual entry for details on the standard options.
229 .\" # OP - start of full description for a single option
234 Command-Line Name: \\fB\\$1\\fR
235 Database Name: \\fB\\$2\\fR
236 Database Class: \\fB\\$3\\fR
240 .\" # CS - begin code excerpt
246 .\" # CE - end code excerpt
251 .\" # UL - underline word
255 .\" # QW - apply quotation marks to word
257 .ie '\\*(lq'"' ``\\$1''\\$2
258 .\"" fix emacs highlighting
259 .el \\*(lq\\$1\\*(rq\\$2
261 .\" # PQ - apply parens and quotation marks to word
263 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
264 .\"" fix emacs highlighting
265 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
267 .\" # QR - quoted range
269 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
270 .\"" fix emacs highlighting
271 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
273 .\" # MT - "empty" string
278 '\" Note: do not modify the .SH NAME line immediately below!
280 exec \- Invoke subprocesses
282 \fBexec \fR?\fIswitches\fR? \fIarg \fR?\fIarg ...\fR? ?\fB&\fR?
286 This command treats its arguments as the specification
287 of one or more subprocesses to execute.
288 The arguments take the form of a standard shell pipeline
289 where each \fIarg\fR becomes one word of a command, and
290 each distinct command becomes a subprocess.
292 If the initial arguments to \fBexec\fR start with \fB\-\fR then
293 they are treated as command-line switches and are not part
294 of the pipeline specification. The following switches are
299 Stops the \fBexec\fR command from treating the output of messages to the
300 pipeline's standard error channel as an error case.
304 Retains a trailing newline in the pipeline's output.
305 Normally a trailing newline will be deleted.
309 Marks the end of switches. The argument following this one will
310 be treated as the first \fIarg\fR even if it starts with a \fB\-\fR.
312 If an \fIarg\fR (or pair of \fIarg\fRs) has one of the forms
313 described below then it is used by \fBexec\fR to control the
314 flow of input and output among the subprocess(es).
315 Such arguments will not be passed to the subprocess(es). In forms
317 .QW "\fB<\fR \fIfileName\fR" ,
318 \fIfileName\fR may either be in a separate argument from
320 or in the same argument with no intervening space (i.e.
321 .QW \fB<\fIfileName\fR ).
325 Separates distinct commands in the pipeline. The standard output
326 of the preceding command will be piped into the standard input
331 Separates distinct commands in the pipeline. Both standard output
332 and standard error of the preceding command will be piped into
333 the standard input of the next command.
334 This form of redirection overrides forms such as 2> and >&.
338 The file named by \fIfileName\fR is opened and used as the standard
339 input for the first command in the pipeline.
343 \fIFileId\fR must be the identifier for an open file, such as the return
344 value from a previous call to \fBopen\fR.
345 It is used as the standard input for the first command in the pipeline.
346 \fIFileId\fR must have been opened for reading.
350 \fIValue\fR is passed to the first command as its standard input.
354 Standard output from the last command is redirected to the file named
355 \fIfileName\fR, overwriting its previous contents.
357 \fB2>\0\fIfileName\fR
359 Standard error from all commands in the pipeline is redirected to the
360 file named \fIfileName\fR, overwriting its previous contents.
362 \fB>&\0\fIfileName\fR
364 Both standard output from the last command and standard error from all
365 commands are redirected to the file named \fIfileName\fR, overwriting
366 its previous contents.
368 \fB>>\0\fIfileName\fR
370 Standard output from the last command is
371 redirected to the file named \fIfileName\fR, appending to it rather
374 \fB2>>\0\fIfileName\fR
376 Standard error from all commands in the pipeline is
377 redirected to the file named \fIfileName\fR, appending to it rather
380 \fB>>&\0\fIfileName\fR
382 Both standard output from the last command and standard error from
383 all commands are redirected to the file named \fIfileName\fR,
384 appending to it rather than overwriting it.
388 \fIFileId\fR must be the identifier for an open file, such as the return
389 value from a previous call to \fBopen\fR.
390 Standard output from the last command is redirected to \fIfileId\fR's
391 file, which must have been opened for writing.
395 \fIFileId\fR must be the identifier for an open file, such as the return
396 value from a previous call to \fBopen\fR.
397 Standard error from all commands in the pipeline is
398 redirected to \fIfileId\fR's file.
399 The file must have been opened for writing.
403 Standard error from all commands in the pipeline is redirected to the
404 command result. This operator is only valid at the end of the command
409 \fIFileId\fR must be the identifier for an open file, such as the return
410 value from a previous call to \fBopen\fR.
411 Both standard output from the last command and standard error from
412 all commands are redirected to \fIfileId\fR's file.
413 The file must have been opened for writing.
415 If standard output has not been redirected then the \fBexec\fR
416 command returns the standard output from the last command
417 in the pipeline, unless
419 was specified, in which case standard error is included as well.
420 If any of the commands in the pipeline exit abnormally or
421 are killed or suspended, then \fBexec\fR will return an error
422 and the error message will include the pipeline's output followed by
423 error messages describing the abnormal terminations; the
424 \fB\-errorcode\fR return option will contain additional information
425 about the last abnormal termination encountered.
426 If any of the commands writes to its standard error file and that
427 standard error is not redirected
428 and \fB\-ignorestderr\fR is not specified,
429 then \fBexec\fR will return an error; the error message
430 will include the pipeline's standard output, followed by messages
431 about abnormal terminations (if any), followed by the standard error
434 If the last character of the result or error message
435 is a newline then that character is normally deleted
436 from the result or error message.
437 This is consistent with other Tcl return values, which do not
438 normally end with newlines.
439 However, if \fB\-keepnewline\fR is specified then the trailing
442 If standard input is not redirected with
447 then the standard input for the first command in the
448 pipeline is taken from the application's current standard input.
450 If the last \fIarg\fR is
452 then the pipeline will be executed in background.
453 In this case the \fBexec\fR command will return a list whose
454 elements are the process identifiers for all of the subprocesses
456 The standard output from the last command in the pipeline will
457 go to the application's standard output if it has not been
458 redirected, and error output from all of
459 the commands in the pipeline will go to the application's
460 standard error file unless redirected.
462 The first word in each command is taken as the command name;
463 tilde-substitution is performed on it, and if the result contains
464 no slashes then the directories
465 in the PATH environment variable are searched for
466 an executable by the given name.
467 If the name contains a slash then it must refer to an executable
468 reachable from the current directory.
471 expansion or other shell-like substitutions
472 are performed on the arguments to commands.
473 .SH "PORTABILITY ISSUES"
475 \fBWindows\fR (all versions)
477 Reading from or writing to a socket, using the
478 .QW \fB@\0\fIfileId\fR
479 notation, does not work. When reading from a socket, a 16-bit DOS
480 application will hang and a 32-bit application will return immediately with
481 end-of-file. When either type of application writes to a socket, the
482 information is instead sent to the console, if one is present, or is
486 The Tk console text widget does not provide real standard IO capabilities.
487 Under Tk, when redirecting from standard input, all applications will see an
488 immediate end-of-file; information redirected to standard output or standard
489 error will be discarded.
491 Either forward or backward slashes are accepted as path separators for
492 arguments to Tcl commands. When executing an application, the path name
493 specified for the application may also contain forward or backward slashes
494 as path separators. Bear in mind, however, that most Windows applications
495 accept arguments with forward slashes only as option delimiters and
496 backslashes only in paths. Any arguments to an application that specify a
497 path name with forward slashes will not automatically be converted to use
498 the backslash character. If an argument contains forward slashes as the
499 path separator, it may or may not be recognized as a path name, depending on
502 Additionally, when calling a 16-bit DOS or Windows 3.X application, all path
503 names must use the short, cryptic, path format (e.g., using
506 .QW applbakery.default ),
507 which can be obtained with the
508 .QW "\fBfile attributes\fI fileName \fB\-shortname\fR"
511 Two or more forward or backward slashes in a row in a path refer to a
512 network path. For example, a simple concatenation of the root directory
513 \fBc:/\fR with a subdirectory \fB/windows/system\fR will yield
514 \fBc://windows/system\fR (two slashes together), which refers to the mount
515 point called \fBsystem\fR on the machine called \fBwindows\fR (and the
516 \fBc:/\fR is ignored), and is not equivalent to \fBc:/windows/system\fR,
517 which describes a directory on the current computer. The \fBfile join\fR
518 command should be used to concatenate path components.
520 Note that there are two general types of Win32 console applications:
523 CLI \(em CommandLine Interface, simple stdio exchange. \fBnetstat.exe\fR for
526 TUI \(em Textmode User Interface, any application that accesses the console
527 API for doing such things as cursor movement, setting text color, detecting
528 key presses and mouse movement, etc. An example would be \fBtelnet.exe\fR
529 from Windows 2000. These types of applications are not common in a windows
530 environment, but do exist.
533 \fBexec\fR will not work well with TUI applications when a console is not
534 present, as is done when launching applications under wish. It is desirable
535 to have console applications hidden and detached. This is a designed-in
536 limitation as \fBexec\fR wants to communicate over pipes. The Expect
537 extension addresses this issue when communicating with a TUI application.
539 When attempting to execute an application, \fBexec\fR first searches for
540 the name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and
541 \fB.bat\fR are appended to the end of the specified name and it searches
542 for the longer name. If a directory name was not specified as part of the
543 application name, the following directories are automatically searched in
544 order when attempting to locate the application:
546 The directory from which the Tcl executable was loaded.
548 The current directory.
550 The Windows NT 32-bit system directory.
552 The Windows NT 16-bit system directory.
554 The Windows NT home directory.
556 The directories listed in the path.
558 In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
559 the caller must prepend the desired command with
560 .QW "\fBcmd.exe /c\0\fR"
561 because built-in commands are not implemented using executables.
564 \fBUnix\fR (including Mac OS X)
566 The \fBexec\fR command is fully functional and works as described.
569 Here are some examples of the use of the \fBexec\fR command on Unix.
570 To execute a simple program and get its result:
575 .SS "WORKING WITH NON-ZERO RESULTS"
577 To execute a program that can return a non-zero result, you should
578 wrap the call to \fBexec\fR in \fBcatch\fR and check the contents
579 of the \fB\-errorcode\fR return option if you have an error:
583 if {[catch {\fBexec\fR grep foo bar.txt} results options]} {
584 set details [dict get $options -errorcode]
585 if {[lindex $details 0] eq "CHILDSTATUS"} {
586 set status [lindex $details 2]
588 # Some other error; regenerate it to let caller handle
589 return -options $options -level 0 $results
595 This is more easily written using the \fBtry\fR command, as that makes
596 it simpler to trap specific types of errors. This is
597 done using code like this:
601 set results [\fBexec\fR grep foo bar.txt]
603 } trap CHILDSTATUS {results options} {
604 set status [lindex [dict get $options -errorcode] 2]
608 .SS "WORKING WITH QUOTED ARGUMENTS"
610 When translating a command from a Unix shell invocation, care should
611 be taken over the fact that single quote characters have no special
612 significance to Tcl. Thus:
615 awk '{sum += $1} END {print sum}' numbers.list
618 would be translated into something like:
621 \fBexec\fR awk {{sum += $1} END {print sum}} numbers.list
623 .SS "WORKING WITH GLOBBING"
625 If you are converting invocations involving shell globbing, you should
626 remember that Tcl does not handle globbing or expand things into
627 multiple arguments by default. Instead you should write things like
631 \fBexec\fR ls -l {*}[glob *.tcl]
633 .SS "WORKING WITH USER-SUPPLIED SHELL SCRIPT FRAGMENTS"
635 One useful technique can be to expose to users of a script the ability
636 to specify a fragment of shell script to execute that will have some
637 data passed in on standard input that was produced by the Tcl program.
638 This is a common technique for using the \fIlpr\fR program for
639 printing. By far the simplest way of doing this is to pass the user's
640 script to the user's shell for processing, as this avoids a lot of
641 complexity with parsing other languages.
644 set lprScript [\fIget from user...\fR]
645 set postscriptData [\fIgenerate somehow...\fR]
647 \fBexec\fR $env(SHELL) -c $lprScript << $postscriptData
649 .SH "WINDOWS EXAMPLES"
651 Here are some examples of the use of the \fBexec\fR command on Windows.
652 To start an instance of \fInotepad\fR editing a file without waiting
653 for the user to finish editing the file:
656 \fBexec\fR notepad myfile.txt &
659 To print a text file using \fInotepad\fR:
662 \fBexec\fR notepad /p myfile.txt
664 .SS "WORKING WITH CONSOLE PROGRAMS"
666 If a program calls other programs, such as is common with compilers,
667 then you may need to resort to batch files to hide the console windows
668 that sometimes pop up:
671 \fBexec\fR cmp.bat somefile.c -o somefile
674 With the file \fIcmp.bat\fR looking something like:
677 @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9
679 .SS "WORKING WITH COMMAND BUILT-INS"
681 Sometimes you need to be careful, as different programs may have the
682 same name and be in the path. It can then happen that typing a command
683 at the DOS prompt finds \fIa different program\fR than the same
684 command run via \fBexec\fR. This is because of the (documented)
685 differences in behaviour between \fBexec\fR and DOS batch files.
687 When in doubt, use the command \fBauto_execok\fR: it will return the
688 complete path to the program as seen by the \fBexec\fR command. This
689 applies especially when you want to run
692 \fIdir\fR from a Tcl script (if you just want to list filenames, use
693 the \fBglob\fR command.) To do that, use this:
696 \fBexec\fR {*}[auto_execok dir] *.tcl
698 .SS "WORKING WITH NATIVE FILENAMES"
700 Many programs on Windows require filename arguments to be passed in with
701 backslashes as pathname separators. This is done with the help of the
702 \fBfile nativename\fR command. For example, to make a directory (on NTFS)
703 encrypted so that only the current user can access it requires use of
704 the \fICIPHER\fR command, like this:
707 set secureDir "~/Desktop/Secure Directory"
708 file mkdir $secureDir
709 \fBexec\fR CIPHER /e /s:[file nativename $secureDir]
712 error(n), file(n), open(n)
714 execute, pipeline, redirection, subprocess
OSDN Git Service
