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
                    following  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
                      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 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
              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'').

              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.

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


SEE ALSO
       open(n)


KEYWORDS
