Provided by: tcl8.4-doc_8.4.19-4ubuntu3_all bug

NAME

       exec - Invoke subprocesses

SYNOPSIS

       exec ?switches? arg ?arg ...?
_________________________________________________________________

DESCRIPTION

       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 arg  becomes
       one word of a command, and each distinct command becomes a subprocess.

       If  the  initial  arguments  to  exec  start  with - then they are treated as command-line
       switches and are not part of the  pipeline  specification.   The  following  switches  are
       currently supported:

       -keepnewline Retains  a  trailing  newline  in the pipeline's output.  Normally a trailing
                    newline will be deleted.

       --           Marks the end of switches.  The argument following this one will  be  treated
                    as the first arg even if it starts with a -.

       If  an  arg (or pair of args) has one of the forms described below then it is used by exec
       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 ``< fileName'' fileName may either be
       in a separate argument from ``<'' or in the same argument with no intervening space  (i.e.
       ``<fileName'').

       |              Separates  distinct  commands  in the pipeline.  The standard output of the
                      preceding command will be  piped  into  the  standard  input  of  the  next
                      command.

       |&             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 >&.

       < fileName     The file named by fileName is opened and used as the standard input for the
                      first command in the pipeline.

       <@ fileId      FileId  must  be  the identifier for an open file, such as the return value
                      from a previous call to open.  It is used as the  standard  input  for  the
                      first command in the pipeline.  FileId must have been opened for reading.

       << value       Value is passed to the first command as its standard input.

       > fileName     Standard  output  from  the  last  command  is redirected to the file named
                      fileName, overwriting its previous contents.

       2> fileName    Standard error from all commands in the pipeline is redirected to the  file
                      named fileName, overwriting its previous contents.

       >& fileName    Both  standard  output  from  the  last command and standard error from all
                      commands are  redirected  to  the  file  named  fileName,  overwriting  its
                      previous contents.

       >> fileName    Standard  output  from  the  last  command  is redirected to the file named
                      fileName, appending to it rather than overwriting it.

       2>> fileName   Standard error from all commands in the pipeline is redirected to the  file
                      named fileName, appending to it rather than overwriting it.

       >>& fileName   Both  standard  output  from  the  last command and standard error from all
                      commands are redirected to the file named fileName, appending to it  rather
                      than overwriting it.

       >@ fileId      FileId  must  be  the identifier for an open file, such as the return value
                      from a previous call to open.  Standard output from  the  last  command  is
                      redirected to fileId's file, which must have been opened for writing.

       2>@ fileId     FileId  must  be  the identifier for an open file, such as the return value
                      from a previous call to open.  Standard error  from  all  commands  in  the
                      pipeline  is  redirected  to fileId's file.  The file must have been opened
                      for writing.

       >&@ fileId     FileId must be the identifier for an open file, such as  the  return  value
                      from  a  previous call to open.  Both standard output from the last command
                      and standard error from all commands are redirected to fileId's file.   The
                      file must have been opened for writing.

       If  standard  output  has  not  been redirected then the exec 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  exec will return an error and the error
       message will include the pipeline's output  followed  by  error  messages  describing  the
       abnormal  terminations;  the  errorCode 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 exec 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.

       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 -keepnewline is
       specified then the trailing newline is retained.

       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.

       If the last arg is ``&'' then the pipeline will be executed in background.  In  this  case
       the  exec 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.

       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.

PORTABILITY ISSUESWindows (all versions)                                                                     │
              Reading from or writing to a socket, using  the  ``@ fileId''  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.                                                    │

              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.                                                                          │

              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.                                                           │

              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 file attributes $fileName-shortname command.                                                                 │

              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 c:/ with a subdirectory │
              /windows/system will yield c://windows/system (two slashes together), which  refers │
              to  the  mount  point  called  system on the machine called windows (and the c:/ is │
              ignored), and is not equivalent to c:/windows/system, which describes  a  directory │
              on  the current computer.  The file join command should be used to concatenate path │
              components.                                                                         │

              Note that there are two general types of Win32 console applications:                │
                     1) CLI -- CommandLine Interface,  simple  stdio  exchange.  netstat.exe  for │
                     example.                                                                     │
                     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 telnet.exe from │
                     Windows 2000.  These types of applications  are  not  common  in  a  windows │
                     environment, but do exist.                                                   │
              exec  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 exec wants │
              to communicate  over  pipes.   The  Expect  extension  addresses  this  issue  when │
              communicating with a TUI application.                                               │

       Windows NT                                                                                 │
              When  attempting  to execute an application, exec first searches for the name as it │
              was specified.  Then, in order, .com, .exe, and .bat 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:          │

                     The directory from which the Tcl executable was loaded.                      │
                     The current directory.                                                       │
                     The Windows NT 32-bit system directory.                                      │
                     The Windows NT 16-bit system directory.                                      │
                     The Windows NT home directory.                                               │
                     The directories listed in the path.                                          │

              In  order  to  execute  shell  built-in commands like dir and copy, the caller must │
              prepend the desired command with ``cmd.exe /c '' because built-in commands are  not │
              implemented using executables.                                                      │

       Windows 9x                                                                                 │
              When  attempting  to execute an application, exec first searches for the name as it │
              was specified.  Then, in order, .com, .exe, and .bat 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:          │

                     The directory from which the Tcl executable was loaded.                      │
                     The current directory.                                                       │
                     The Windows 9x system directory.                                             │
                     The Windows 9x home directory.                                               │
                     The directories listed in the path.                                          │

              In  order  to  execute  shell  built-in commands like dir and copy, the caller must │
              prepend the desired command with ``command.com /c '' because built-in commands  are │
              not implemented using executables.                                                  │

              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.                                         │

              Redirection  between the NUL: device and a 16-bit application does not always work. │
              When redirecting from NUL:, 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 NUL:, some applications will │
              hang.  The above problems do not happen with 32-bit applications.                   │

              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.                                                     │

              Certain  applications,  such  as command.com, 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.  │

       Macintosh                                                                                  │
              The exec command is not implemented and does not exist under Macintosh.             │

       Unix                                                                                       │
              The exec command is fully functional and works as described.                        │

UNIX EXAMPLES                                                                                     │
       Here are some examples of the use of the exec command on Unix.                             │

       To execute a simple program and get its result:                                            │
              exec uname -a                                                                       │

       To execute a program that can return a non-zero result, you should wrap the call  to  exec │
       in  catch  and  check what the contents of the global errorCode variable is if you have an │
       error:                                                                                     │
              set status 0                                                                        │
              if {[catch {exec grep foo bar.txt} results]} {                                      │
                 if {[lindex $::errorCode 0] eq "CHILDSTATUS"} {                                  │
                    set status [lindex $::errorCode 2]                                            │
                 } else {                                                                         │
                    # Some kind of unexpected failure                                             │
                 }                                                                                │
              }                                                                                   │

       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:              │
              awk '{sum += $1} END {print sum}' numbers.list                                      │
       would be translated into something like:                                                   │
              exec awk {{sum += $1} END {print sum}} numbers.list                                 │

       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:                                                             │
              eval [list exec ls -l] [glob *.tcl]                                                 │

WINDOWS EXAMPLES                                                                                  │
       Here are some examples of the use of the exec command on Windows.                          │

       To  start  an  instance  of  notepad editing a file without waiting for the user to finish │
       editing the file:                                                                          │
              exec notepad myfile.txt &                                                           │

       To print a text file using notepad:                                                        │
              exec notepad /p myfile.txt                                                          │

       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:                   │
              exec cmp.bat somefile.c -o somefile                                                 │
       With the file cmp.bat looking something like:                                              │
              @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9                                                     │

       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  a  differentprogram  than  the  same  command  run  via  exec.  This  is  because  of the (documented) │
       differences in behaviour between exec and DOS batch files.                                 │

       When in doubt, use the command auto_execok: it  will  return  the  complete  path  to  the │
       program  as  seen  by  the  exec  command.   This  applies especially when you want to run │
       "internal" commands like dir from a Tcl script (if you just want to  list  filenames,  use │
       the glob command.)  To do that, use this:                                                  │
              eval [list exec] [auto_execok dir] [list *.tcl]                                     │

SEE ALSOerror(3tcl), open(3tcl)                                                                    │

KEYWORDS                                                                                          │
       execute, pipeline, redirection, subprocess                                                 │