Provided by: tcl8.6-doc_8.6.1-4ubuntu1_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:

       -ignorestderr
                    Stops the exec command from treating the output of messages to the pipeline's
                    standard error channel as an error case.

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

       2>@1           Standard  error  from  all  commands  in  the pipeline is redirected to the
                      command result.  This operator is only valid at  the  end  of  the  command
                      pipeline.

       >&@ 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, unless “2>@1” was specified, in which case
       standard error is included as  well.   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 return option 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 is not redirected and -ignorestderr is not
       specified, 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 do not normally end  with  newlines.   However,  if  -keepnewline  is
       specified then the trailing newline is retained.

       If standard input is not redirected with “<”, “<<” 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 has not 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”),  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.

       Unix (including Mac OS X)
              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

   WORKING WITH NON-ZERO RESULTS
       To  execute  a program that can return a non-zero result, you should wrap the call to exec
       in catch and check the contents of the -errorcode return option if you have an error:

              set status 0
              if {[catch {exec grep foo bar.txt} results options]} {
                  set details [dict get $options -errorcode]
                  if {[lindex $details 0] eq "CHILDSTATUS"} {
                      set status [lindex $details 2]
                  } else {
                      # Some other error; regenerate it to let caller handle
                      return -options $options -level 0 $results
                  }
              }

       This is more easily written using the try command,  as  that  makes  it  simpler  to  trap │
       specific types of errors. This is done using code like this:                               │

              try {                                                                               │
                  set results [exec grep foo bar.txt]                                             │
                  set status 0                                                                    │
              } trap CHILDSTATUS {results options} {                                              │
                  set status [lindex [dict get $options -errorcode] 2]                            │
              }                                                                                   │

   WORKING WITH QUOTED ARGUMENTS
       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

   WORKING WITH GLOBBING
       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:

              exec ls -l {*}[glob *.tcl]

   WORKING WITH USER-SUPPLIED SHELL SCRIPT FRAGMENTS
       One useful technique can be to expose to users of  a  script  the  ability  to  specify  a
       fragment  of  shell script to execute that will have some data passed in on standard input
       that was produced by the Tcl program.  This is  a  common  technique  for  using  the  lpr
       program  for  printing. By far the simplest way of doing this is to pass the user's script
       to the user's shell for processing, as this avoids a lot of complexity with parsing  other
       languages.

              set lprScript [get from user...]
              set postscriptData [generate somehow...]

              exec $env(SHELL) -c $lprScript << $postscriptData

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

   WORKING WITH CONSOLE PROGRAMS
       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

   WORKING WITH COMMAND BUILT-INS
       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  different
       program  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:

              exec {*}[auto_execok dir] *.tcl

   WORKING WITH NATIVE FILENAMES
       Many  programs  on  Windows require filename arguments to be passed in with backslashes as
       pathname separators. This is done with the  help  of  the  file  nativename  command.  For
       example,  to make a directory (on NTFS) encrypted so that only the current user can access
       it requires use of the CIPHER command, like this:

              set secureDir "~/Desktop/Secure Directory"
              file mkdir $secureDir
              exec CIPHER /e /s:[file nativename $secureDir]

SEE ALSO

       error(3tcl), file(3tcl), open(3tcl)

KEYWORDS

       execute, pipeline, redirection, subprocess