NAME

       exec - Invoke subprocess(es)


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 fol­
                    lowing  this one will be treated as the first
                    arg even if it starts with a -.

       If an arg  (or  pair  of  arg's)  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 pre­
                      ceding command will be piped into the stan­
                      dard input of the next command.

       |&             Separates    distinct   commands   in   the
                      pipeline.  Both standard output  and  stan­
                      dard error of the preceding command will be
                      piped into the standard input of  the  next
                      command.   This  form  of redirection over­
                      rides 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.

                      file,  such as the return value from a pre­
                      vious 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  con­
                      tents.

       >& 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 over­
                      writing it.

       >&gt;& 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 pre­
                      vious call to open.  Standard  output  from
                      the  last command is redirected to fileId's
                      file, which must have been opened for writ­
                      ing.

       2>@ fileId     FileId  must  be the identifier for an open
                      file, such as the return value from a  pre­
                      vious  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

                      put  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, fol­
       lowed 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 stan­
       dard input.

       If  the  last  arg is ``&'' then the pipeline will be exe­
       cuted 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  redi­
       rected,  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 sub­
       stitutions are performed on the arguments to commands.

       Windows (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 redirect­ |
              ing  from standard input, all applications will see |
              an immediate end-of-file; information redirected to |
              standard  output  or  standard  error  will be dis­ |
              carded.                                             |

              Either forward or backward slashes are accepted  as |
              path  separators  for  arguments  to  Tcl commands. |
              When executing an application, the path name speci­ |
              fied  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 sepa­ |
              rator, 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'').                 |

              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://win­ |
              dows/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 equiv­ |
              alent   to  c:/windows/system,  which  describes  a |
              directory on the current computer.  The  file  join |
              command  should  be used to concatenate path compo­ |
              nents.                                              |

       Windows                                                    |
              NT                                                        ||
              When attempting to  execute  an  application,  exec |
              first  searches  for  the name as it was specified. |

              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 fol­ |
              lowing 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 the shell builtin commands like |
              dir  and  copy,  the  caller must prepend ``cmd.exe |
              /c '' to the desired command.                       |

       Windows                                                    |
              95                                                        ||
              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 fol­ |
              lowing 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 95 system directory.             |
                     The Windows 95 home directory.               |
                     The directories listed in the path.          |

              In order to execute the shell builtin commands like |
              dir and copy, the caller must prepend ``command.com |
              /c '' to the desired command.                       |

              Once a 16-bit DOS  application  has  read  standard |
              input  from  a  console  and  then quit, all subse­ |
              quently run 16-bit DOS applications  will  see  the |
              standard  input as already closed.  32-bit applica­ |
              tions do not have this problem and  will  run  cor­ |
              rectly,  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 |

              will  actually  correctly  get an immediate end-of- |
              file; the behavior seems to depend  upon  something |
              compiled  into  the application itself.  When redi­ |
              recting greater than 4K or so to NUL:, some  appli­ |
              cations  will hang.  The above problems do not hap­ |
              pen 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 stan­ |
              dard  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 Win­ |
              dows 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.                                          |


SEE ALSO |

       error(n), open(n)                                          |


KEYWORDS |

       execute, pipeline, redirection, subprocess                 |


Man(1) output converted with man2html