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.

       <@ fileId      FileId must be the identifier for  an  open
                      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.

       >>& 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 pre-
                      vious 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, 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.


PORTABILITY ISSUES
       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  directory  /system on the machine windows (and
              the c:/ is  ignored),  and  is  not  equivalent  to
              c:/windows/system,  which  describes a directory on
              the current computer.

       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 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
              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 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 Windows 95 command line interpreter 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.

       Windows 3.X
              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 3.X system directory.
                     The Windows 3.X 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.

              16-bit and 32-bit DOS and Windows applications  may
              be  executed.   However,  redirection and piping of
              standard IO only works  with  16-bit  DOS  applica-
              tions.   32-bit  applications  always  see standard
              input as already closed, and any standard output or
              error is discarded, no matter where in the pipeline
              the application occurs or what redirection  symbols
              are  used  by the caller.  Additionally, for 16-bit
              applications, standard error is always sent to  the
              same  place  as standard output; it cannot be redi-
              rected to a separate location.  In order to achieve
              pseudo-redirection  for  32-bit  applications,  the
              32-bit application must instead be written to  take
              command  line arguments that specify the files that
              it should read from and write  to  and  open  those
              files itself.

              All  applications, both 16-bit and 32-bit, run syn-
              chronously; each  application  runs  to  completion
              before the next one in the pipeline starts.  Tempo-
              rary files are  used  to  simulate  piping  between
              applications.   The  exec command cannot be used to
              start an application in the background.

              When standard input is redirected from an open file
              using  the  ``@ fileId'' notation, the open file is
              completely read up to its end.   This  is  slightly
              different  than  under  Windows 95 or NT, where the
              child application consumes from the open file  only
              as  much  as it wants.  Redirecting to an open file
              is supported as normal.

       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
       open(n)


KEYWORDS
       execute, pipeline, redirection, subprocess
