2 '\" Copyright (c) 1993 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 '\" RCS: @(#) $Id: exec.n,v 1.4 1999/12/09 14:43:47 hobbs Exp $
10 '\" The definitions below are for supplemental macros used in Tcl/Tk
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
56 '\" options follow on successive lines, in four columns separated
60 '\" End of list of standard options for a Tk widget.
62 '\" .OP cmdName dbName dbClass
63 '\" Start of description of a specific option. cmdName gives the
64 '\" option's name as specified in the class command, dbName gives
65 '\" the option's name in the option database, and dbClass gives
66 '\" the option's class in the option database.
69 '\" Print arg1 underlined, then print arg2 normally.
71 '\" RCS: @(#) $Id: man.macros,v 1.3 1999/04/16 00:46:35 stanton Exp $
73 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
77 '\" # Start an argument description
81 . ie !"\\$2"" .TP \\n()Cu
86 \&\\$1 \\fI\\$2\\fP (\\$3)
99 '\" # define tabbing values for .AP
102 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
105 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
106 .nr )C \\n()Bu+\\w'(in/out)'u+2n
108 .AS Tcl_Interp Tcl_CreateInterp in/out
109 '\" # BS - start boxed text
110 '\" # ^y = starting y location
118 .if n \l'\\n(.lu\(ul'
121 '\" # BE - end boxed text (draw box now)
126 .ie n \l'\\n(^lu\(ul'
128 .\" Draw four-sided box normally, but don't draw top of
129 .\" box if the box started on an earlier page.
131 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
134 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
141 '\" # VS - start vertical sidebar
142 '\" # ^Y = starting y location
143 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
147 .ie n 'mc \s12\(br\s0
150 '\" # VE - end of vertical sidebar
158 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
165 '\" # Special macro to handle page bottom: finish off current
166 '\" # box/sidebar if in box/sidebar mode, then invoked standard
167 '\" # page bottom macro.
174 .\" Draw three-sided box if this is the box's first page,
175 .\" draw two sides but no top otherwise.
176 .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
177 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
180 .nr ^x \\n(^tu+1v-\\n(^Yu
181 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
194 '\" # DS - begin display
200 '\" # DE - end display
206 '\" # SO - start of list of standard options
208 .SH "STANDARD OPTIONS"
214 '\" # SE - end of list of standard options
219 See the \\fBoptions\\fR manual entry for details on the standard options.
221 '\" # OP - start of full description for a single option
226 Command-Line Name: \\fB\\$1\\fR
227 Database Name: \\fB\\$2\\fR
228 Database Class: \\fB\\$3\\fR
232 '\" # CS - begin code excerpt
238 '\" # CE - end code excerpt
246 .TH exec n 7.6 Tcl "Tcl Built-In Commands"
248 '\" Note: do not modify the .SH NAME line immediately below!
250 exec \- Invoke subprocess(es)
252 \fBexec \fR?\fIswitches\fR? \fIarg \fR?\fIarg ...\fR?
257 This command treats its arguments as the specification
258 of one or more subprocesses to execute.
259 The arguments take the form of a standard shell pipeline
260 where each \fIarg\fR becomes one word of a command, and
261 each distinct command becomes a subprocess.
263 If the initial arguments to \fBexec\fR start with \fB\-\fR then
264 they are treated as command-line switches and are not part
265 of the pipeline specification. The following switches are
269 Retains a trailing newline in the pipeline's output.
270 Normally a trailing newline will be deleted.
273 Marks the end of switches. The argument following this one will
274 be treated as the first \fIarg\fR even if it starts with a \fB\-\fR.
276 If an \fIarg\fR (or pair of \fIarg\fR's) has one of the forms
277 described below then it is used by \fBexec\fR to control the
278 flow of input and output among the subprocess(es).
279 Such arguments will not be passed to the subprocess(es). In forms
280 such as ``< \fIfileName\fR'' \fIfileName\fR may either be in a
281 separate argument from ``<'' or in the same argument with no
282 intervening space (i.e. ``<\fIfileName\fR'').
285 Separates distinct commands in the pipeline. The standard output
286 of the preceding command will be piped into the standard input
290 Separates distinct commands in the pipeline. Both standard output
291 and standard error of the preceding command will be piped into
292 the standard input of the next command.
293 This form of redirection overrides forms such as 2> and >&.
296 The file named by \fIfileName\fR is opened and used as the standard
297 input for the first command in the pipeline.
300 \fIFileId\fR must be the identifier for an open file, such as the return
301 value from a previous call to \fBopen\fR.
302 It is used as the standard input for the first command in the pipeline.
303 \fIFileId\fR must have been opened for reading.
306 \fIValue\fR is passed to the first command as its standard input.
309 Standard output from the last command is redirected to the file named
310 \fIfileName\fR, overwriting its previous contents.
313 Standard error from all commands in the pipeline is redirected to the
314 file named \fIfileName\fR, overwriting its previous contents.
317 Both standard output from the last command and standard error from all
318 commands are redirected to the file named \fIfileName\fR, overwriting
319 its previous contents.
322 Standard output from the last command is
323 redirected to the file named \fIfileName\fR, appending to it rather
327 Standard error from all commands in the pipeline is
328 redirected to the file named \fIfileName\fR, appending to it rather
332 Both standard output from the last command and standard error from
333 all commands are redirected to the file named \fIfileName\fR,
334 appending to it rather than overwriting it.
337 \fIFileId\fR must be the identifier for an open file, such as the return
338 value from a previous call to \fBopen\fR.
339 Standard output from the last command is redirected to \fIfileId\fR's
340 file, which must have been opened for writing.
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 Standard error from all commands in the pipeline is
346 redirected to \fIfileId\fR's file.
347 The file must have been opened for writing.
350 \fIFileId\fR must be the identifier for an open file, such as the return
351 value from a previous call to \fBopen\fR.
352 Both standard output from the last command and standard error from
353 all commands are redirected to \fIfileId\fR's file.
354 The file must have been opened for writing.
356 If standard output has not been redirected then the \fBexec\fR
357 command returns the standard output from the last command
359 If any of the commands in the pipeline exit abnormally or
360 are killed or suspended, then \fBexec\fR will return an error
361 and the error message will include the pipeline's output followed by
362 error messages describing the abnormal terminations; the
363 \fBerrorCode\fR variable will contain additional information
364 about the last abnormal termination encountered.
365 If any of the commands writes to its standard error file and that
366 standard error isn't redirected,
367 then \fBexec\fR will return an error; the error message
368 will include the pipeline's standard output, followed by messages
369 about abnormal terminations (if any), followed by the standard error
372 If the last character of the result or error message
373 is a newline then that character is normally deleted
374 from the result or error message.
375 This is consistent with other Tcl return values, which don't
376 normally end with newlines.
377 However, if \fB\-keepnewline\fR is specified then the trailing
380 If standard input isn't redirected with ``<'' or ``<<''
381 or ``<@'' then the standard input for the first command in the
382 pipeline is taken from the application's current standard input.
384 If the last \fIarg\fR is ``&'' then the pipeline will be
385 executed in background.
386 In this case the \fBexec\fR command will return a list whose
387 elements are the process identifiers for all of the subprocesses
389 The standard output from the last command in the pipeline will
390 go to the application's standard output if it hasn't been
391 redirected, and error output from all of
392 the commands in the pipeline will go to the application's
393 standard error file unless redirected.
395 The first word in each command is taken as the command name;
396 tilde-substitution is performed on it, and if the result contains
397 no slashes then the directories
398 in the PATH environment variable are searched for
399 an executable by the given name.
400 If the name contains a slash then it must refer to an executable
401 reachable from the current directory.
402 No ``glob'' expansion or other shell-like substitutions
403 are performed on the arguments to commands.
406 .SH "PORTABILITY ISSUES"
408 \fBWindows\fR (all versions)
410 Reading from or writing to a socket, using the ``\fB@\0\fIfileId\fR''
411 notation, does not work. When reading from a socket, a 16-bit DOS
412 application will hang and a 32-bit application will return immediately with
413 end-of-file. When either type of application writes to a socket, the
414 information is instead sent to the console, if one is present, or is
417 The Tk console text widget does not provide real standard IO capabilities.
418 Under Tk, when redirecting from standard input, all applications will see an
419 immediate end-of-file; information redirected to standard output or standard
420 error will be discarded.
422 Either forward or backward slashes are accepted as path separators for
423 arguments to Tcl commands. When executing an application, the path name
424 specified for the application may also contain forward or backward slashes
425 as path separators. Bear in mind, however, that most Windows applications
426 accept arguments with forward slashes only as option delimiters and
427 backslashes only in paths. Any arguments to an application that specify a
428 path name with forward slashes will not automatically be converted to use
429 the backslash character. If an argument contains forward slashes as the
430 path separator, it may or may not be recognized as a path name, depending on
433 Additionally, when calling a 16-bit DOS or Windows 3.X application, all path
434 names must use the short, cryptic, path format (e.g., using ``applba~1.def''
435 instead of ``applbakery.default'').
437 Two or more forward or backward slashes in a row in a path refer to a
438 network path. For example, a simple concatenation of the root directory
439 \fBc:/\fR with a subdirectory \fB/windows/system\fR will yield
440 \fBc://windows/system\fR (two slashes together), which refers to the mount
441 point called \fBsystem\fR on the machine called \fBwindows\fR (and the
442 \fBc:/\fR is ignored), and is not equivalent to \fBc:/windows/system\fR,
443 which describes a directory on the current computer. The \fBfile join\fR
444 command should be used to concatenate path components.
448 When attempting to execute an application, \fBexec\fR first searches for the
449 name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR
450 are appended to the end of the specified name and it searches for
451 the longer name. If a directory name was not specified as part of the
452 application name, the following directories are automatically searched in
453 order when attempting to locate the application:
457 The directory from which the Tcl executable was loaded.
459 The current directory.
461 The Windows NT 32-bit system directory.
463 The Windows NT 16-bit system directory.
465 The Windows NT home directory.
467 The directories listed in the path.
470 In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR,
471 the caller must prepend ``\fBcmd.exe /c\0\fR'' to the desired command.
477 When attempting to execute an application, \fBexec\fR first searches for the
478 name as it was specified. Then, in order, \fB.com\fR, \fB.exe\fR, and \fB.bat\fR
479 are appended to the end of the specified name and it searches for
480 the longer name. If a directory name was not specified as part of the
481 application name, the following directories are automatically searched in
482 order when attempting to locate the application:
486 The directory from which the Tcl executable was loaded.
488 The current directory.
490 The Windows 95 system directory.
492 The Windows 95 home directory.
494 The directories listed in the path.
497 In order to execute the shell builtin commands like \fBdir\fR and \fBcopy\fR,
498 the caller must prepend ``\fBcommand.com /c\0\fR'' to the desired command.
500 Once a 16-bit DOS application has read standard input from a console and
501 then quit, all subsequently run 16-bit DOS applications will see the
502 standard input as already closed. 32-bit applications do not have this
503 problem and will run correctly, even after a 16-bit DOS application thinks
504 that standard input is closed. There is no known workaround for this bug
507 Redirection between the \fBNUL:\fR device and a 16-bit application does not
508 always work. When redirecting from \fBNUL:\fR, some applications may hang,
509 others will get an infinite stream of ``0x01'' bytes, and some will actually
510 correctly get an immediate end-of-file; the behavior seems to depend upon
511 something compiled into the application itself. When redirecting greater than
512 4K or so to \fBNUL:\fR, some applications will hang. The above problems do not
513 happen with 32-bit applications.
515 All DOS 16-bit applications are run synchronously. All standard input from
516 a pipe to a 16-bit DOS application is collected into a temporary file; the
517 other end of the pipe must be closed before the 16-bit DOS application
518 begins executing. All standard output or error from a 16-bit DOS
519 application to a pipe is collected into temporary files; the application
520 must terminate before the temporary files are redirected to the next stage
521 of the pipeline. This is due to a workaround for a Windows 95 bug in the
522 implementation of pipes, and is how the standard Windows 95 DOS shell
523 handles pipes itself.
525 Certain applications, such as \fBcommand.com\fR, should not be executed
526 interactively. Applications which directly access the console window,
527 rather than reading from their standard input and writing to their standard
528 output may fail, hang Tcl, or even hang the system if their own private
529 console window is not available to them.
533 The \fBexec\fR command is not implemented and does not exist under Macintosh.
535 \fBUnix\fR\0\0\0\0\0\0\0
536 The \fBexec\fR command is fully functional and works as described.
543 execute, pipeline, redirection, subprocess
OSDN Git Service
