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

FreeBSD Manual Pages

  
 
  

home | help
Tcl_Main(3)		    Tcl	Library	Procedures		   Tcl_Main(3)

______________________________________________________________________________

NAME
       Tcl_Main,  Tcl_SetMainLoop - main program and event loop	definition for
       Tcl-based applications

SYNOPSIS
       #include	<tcl.h>

       Tcl_Main(argc, argv, appInitProc)

       Tcl_SetMainLoop(mainLoopProc)

ARGUMENTS
       int argc	(in)				    Number  of	 elements   in
						    argv.

       char *argv[] (in)			    Array  of strings contain-
						    ing	  command-line	 argu-
						    ments.

       Tcl_AppInitProc *appInitProc (in)	    Address of an application-
						    specific	initialization
						    procedure.	 The value for
						    this argument  is  usually
						    Tcl_AppInit.

       Tcl_MainLoopProc	*mainLoopProc (in)	    Address of an application-
						    specific event loop	proce-
						    dure.
______________________________________________________________________________

DESCRIPTION
       Tcl_Main	 can  serve  as	 the main program for Tcl-based	shell applica-
       tions.  A "shell	application" is	a program like tclsh or	wish that sup-
       ports both interactive interpretation of	Tcl and	evaluation of a	script
       contained in a file given as a command line argument.  Tcl_Main is  of-
       fered  as a convenience to developers of	shell applications, so they do
       not have	to reproduce all of the	code for proper	initialization of  the
       Tcl library and interactive shell operation.  Other styles of embedding
       Tcl in an application are not supported by  Tcl_Main.   Those  must  be
       achieved	by calling lower level functions in the	Tcl library directly.

       The Tcl_Main function has been offered by the Tcl library since release
       Tcl 7.4.	 In older releases of Tcl, the Tcl library  itself  defined  a
       function	main, but that lacks flexibility of embedding style and	having
       a function main in a library (particularly  a  shared  library)	causes
       problems	 on  many  systems.  Having main in the	Tcl library would also
       make it hard to use Tcl in C++ programs,	since C++ programs  must  have
       special C++ main	functions.

       Normally	 each  shell  application  contains a small main function that
       does nothing but	invoke Tcl_Main.  Tcl_Main then	does all the  work  of
       creating	and running a tclsh-like application.

       Tcl_Main	is not provided	by the public interface	of Tcl's stub library.
       Programs	that call Tcl_Main must	be linked against the standard Tcl li-
       brary.	Extensions  (stub-enabled  or  not)  are  not intended to call
       Tcl_Main.

       Tcl_Main	is not thread-safe.  It	should only be called by a single mas-
       ter  thread of a	multi-threaded application.  This restriction is not a
       problem with normal use described above.

       Tcl_Main	and therefore all applications based upon it, like tclsh,  use
       Tcl_GetStdChannel  to initialize	the standard channels to their default
       values. See Tcl_StandardChannels	for more information.

       Tcl_Main	supports two modes of operation, depending on  the  values  of
       argc  and  argv.	  If  the first	few arguments in argv match ?-encoding
       name? fileName, where fileName does not begin  with  the	 character  -,
       then  fileName  is  taken to be the name	of a file containing a startup
       script, and name	is taken to be the name	of the encoding	 of  the  con-
       tents  of  that	file, which Tcl_Main will attempt to evaluate.	Other-
       wise, Tcl_Main will enter an interactive	mode.

       In either mode, Tcl_Main	will define in its master interpreter the  Tcl
       variables  argc,	 argv, argv0, and tcl_interactive, as described	in the
       documentation for tclsh.

       When it has finished its	own initialization, but	 before	 it  processes
       commands,  Tcl_Main  calls the procedure	given by the appInitProc argu-
       ment.  This procedure provides a	"hook" for the application to  perform
       its  own	initialization of the interpreter created by Tcl_Main, such as
       defining	application-specific commands.	The procedure must have	an in-
       terface that matches the	type Tcl_AppInitProc:
	      typedef int Tcl_AppInitProc(Tcl_Interp *interp);

       AppInitProc is almost always a pointer to Tcl_AppInit; for more details
       on this procedure, see the documentation	for Tcl_AppInit.

       When the	appInitProc is finished, Tcl_Main enters one of	its two	modes.
       If  a  startup  script has been provided, Tcl_Main attempts to evaluate
       it.  Otherwise, interactive mode	begins with examination	of  the	 vari-
       able tcl_rcFileName in the master interpreter.  If that variable	exists
       and holds the name of a readable	file, the contents of  that  file  are
       evaluated  in  the master interpreter.  Then interactive	operations be-
       gin, with prompts and command evaluation	results	written	to  the	 stan-
       dard  output channel, and commands read from the	standard input channel
       and then	evaluated.  The	prompts	written	to the standard	output channel
       may  be	customized  by	defining  the  Tcl  variables  tcl_prompt1 and
       tcl_prompt2 as described	in the documentation for tclsh.	  The  prompts
       and command evaluation results are written to the standard output chan-
       nel only	if the Tcl variable tcl_interactive in the master  interpreter
       holds a non-zero	integer	value.

       Tcl_SetMainLoop allows setting an event loop procedure to be run.  This
       allows, for example, Tk to be dynamically  loaded  and  set  its	 event
       loop.   The  event  loop	will run following the startup script.	If you
       are in interactive mode,	setting	the main loop procedure	will cause the
       prompt to become	fileevent based	and then the loop procedure is called.
       When the	loop procedure returns in interactive mode, interactive	opera-
       tion  will  continue.   The  main loop procedure	must have an interface
       that matches the	type Tcl_MainLoopProc:
	      typedef void Tcl_MainLoopProc(void);

       Tcl_Main	does not return.  Normally a program based  on	Tcl_Main  will
       terminate  when the exit	command	is evaluated.  In interactive mode, if
       an EOF or channel error is encountered on the standard  input  channel,
       then Tcl_Main itself will evaluate the exit command after the main loop
       procedure (if any) returns.  In non-interactive	mode,  after  Tcl_Main
       evaluates  the startup script, and the main loop	procedure (if any) re-
       turns, Tcl_Main will also evaluate the exit command.

SEE ALSO
       tclsh(1),   Tcl_GetStdChannel(3),   Tcl_StandardChannels(3),    Tcl_Ap-
       pInit(3), exit(n)

KEYWORDS
       application-specific  initialization, command-line arguments, main pro-
       gram

Tcl				      8.4			   Tcl_Main(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS

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

home | help