tcl7.6 User Commands - exec






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

     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 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 previ-
                    ous 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 pipe-
                    line   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 pipe-
                    line   is   redirected   to  the  file  named
                    fileName,  appending  to   it   rather   than
                    overwriting 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 previ-
                    ous 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 previ-
                    ous 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 previ-
                    ous 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 termi-
     nations (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.  How-
     ever, 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  stan-  |
          dard  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 execut-  |
          ing 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 appli-  |
          cation 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, cryp-  |
          tic, 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  sub-  |
          directory /windows/system will yield c://windows/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   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.                                     |


     Win-  |
          dows 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 appli-  |
          cation  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 applica-  |
          tion 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 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 out-  |
          put 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   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 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  applications.   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 redirected 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  synchro-  |
          nously;  each application runs to completion before the  |
          next one in the pipeline starts.  Temporary  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 com-  |
          pletely read up to its end.  This is slightly different  |
          than  under  Windows 95 or NT, where the child applica-  |
          tion consumes from the open file only  as  much  as  it  |
          wants.   Redirecting  to  an  open file is supported as  |
          normal.                                                  |

     Macin-  |
          tosh                                                  |
          |                                                        |
          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