Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
exec(n)			     Tcl Built-In Commands		       exec(n)

______________________________________________________________________________

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  mes- |
		    sages to the pipeline's standard error channel as an error |
		    case.

       -keepnewline Retains a trailing newline in the pipeline's output.  Nor-
		    mally 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 subpro-
       cess(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	 stan-
		      dard  output of the preceding command will be piped into
		      the standard input of the	next command.

       |&	      Separates	distinct commands in the pipeline.  Both stan-
		      dard  output and standard	error of the preceding command
		      will be piped into the standard input of the  next  com-
		      mand.   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 in-
		      put.

       > fileName     Standard	output	from the last command is redirected to
		      the file named fileName, overwriting its	previous  con-
		      tents.

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

       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  re-
       turns 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	 addi-
       tional 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	 back-
       ground.	 In  this  case	the exec command will return a list whose ele-
       ments 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	 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-sub-
       stitution  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"	 nota-
	      tion,  does  not work.  When reading from	a socket, a 16-bit DOS
	      application will hang and	a 32-bit application will return imme-
	      diately  with  end-of-file.   When  either  type	of application
	      writes to	a socket, the information is instead sent to the  con-
	      sole, if one is present, or is discarded.

	      The Tk console text widget does not provide real standard	IO ca-
	      pabilities.  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  dis-
	      carded.

	      Either  forward or backward slashes are accepted as path separa-
	      tors for arguments to Tcl	commands.  When	executing an  applica-
	      tion,  the path name specified for the application may also con-
	      tain 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  con-
	      verted  to use the backslash character.  If an argument contains
	      forward slashes as the path separator, it	may or may not be rec-
	      ognized as a path	name, depending	on the program.

	      Additionally,  when calling a 16-bit DOS or Windows 3.X applica-
	      tion, 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 -short-
	      name" 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  applica-
	      tions:

		     [1]    CLI	 --  CommandLine  Interface,  simple stdio ex-
			    change. 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, de-
			    tecting  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  de-
	      tached.	This is	a designed-in limitation as exec wants to com-
	      municate 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 spec-
	      ified as part of the application name, the following directories
	      are automatically	searched in order when	attempting  to	locate
	      the application:

	      o	     The directory from	which the Tcl executable was loaded.

	      o	     The current directory.

	      o	     The Windows NT 32-bit system directory.

	      o	     The Windows NT 16-bit system directory.

	      o	     The Windows NT home directory.

	      o	     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 spec-
	      ified as part of the application name, the following directories
	      are automatically	searched in order when	attempting  to	locate
	      the application:

	      o	     The directory from	which the Tcl executable was loaded.

	      o	     The current directory.

	      o	     The Windows 9x system directory.

	      o	     The Windows 9x home directory.

	      o	     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 exe-
	      cutables.

	      Once a 16-bit DOS	application has	read  standard	input  from  a
	      console  and then	quit, all subsequently run 16-bit DOS applica-
	      tions will see the standard input	as already closed.  32-bit ap-
	      plications 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 applica-
	      tions  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  be-
	      fore  the	16-bit DOS application begins executing.  All standard
	      output or	error from a 16-bit DOS	application to a pipe is  col-
	      lected  into temporary files; the	application must terminate be-
	      fore 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 exe-
	      cuted 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
	      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

       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 re-
       turn 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 kind	of unexpected failure
		 }
	      }

       When translating	a command from a Unix shell invocation,	care should be
       taken  over  the	fact that single quote characters have no special sig-
       nificance 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

       If you are converting invocations involving shell globbing, you	should
       remember	that Tcl does not handle globbing or expand things into	multi-
       ple arguments by	default.  Instead you should write things like this:
	      exec ls -l {*}[glob *.tcl]

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

       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

       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	 espe-
       cially  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

SEE ALSO
       error(n), open(n)

KEYWORDS
       execute,	pipeline, redirection, subprocess

Tcl				      8.5			       exec(n)

NAME | SYNOPSIS | DESCRIPTION | PORTABILITY ISSUES | UNIX EXAMPLES | WINDOWS EXAMPLES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=exec.tcl85&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help