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_SetStartupScript, Tcl_GetStartupScript, Tcl_SetMainLoop -
       main program, startup script, and event loop definition	for  Tcl-based
       applications

SYNOPSIS
       #include	<tcl.h>

       Tcl_Main(argc, argv, appInitProc)

       Tcl_SetStartupScript(path, encoding)

       Tcl_Obj *
       Tcl_GetStartupScript(encodingPtr)

       Tcl_SetMainLoop(mainLoopProc)

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

       char *argv[] (in)			    Array of strings  contain-
						    ing	  command-line	 argu-
						    ments.  On	Windows,  when
						    using  -DUNICODE,  the pa-
						    rameter  type  changes  to
						    wchar_t *.

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

       Tcl_Obj *path (in)			    Name  of  file  to	use as
						    startup script, or NULL.

       const char *encoding (in)		    Encoding of	file to	use as
						    startup script, or NULL.

       const char **encodingPtr	(out)		    If	non-NULL,  location to
						    write a copy of the	(const
						    char  *)  pointing	to the
						    encoding name.

       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 whether the
       filename	and encoding of	a startup script has  been  established.   The
       routines	 Tcl_SetStartupScript  and  Tcl_GetStartupScript are the tools
       for controlling this configuration of Tcl_Main.

       Tcl_SetStartupScript registers the value	path as	the name of  the  file
       for  Tcl_Main to	evaluate as its	startup	script.	 The value encoding is
       Tcl's name for the encoding used	to store the text  in  that  file.   A
       value  of  NULL for encoding is a signal	to use the system encoding.  A
       value of	NULL  for  path	 erases	 any  existing	registration  so  that
       Tcl_Main	will not evaluate any startup script.

       Tcl_GetStartupScript  queries the registered file name and encoding set
       by the most recent Tcl_SetStartupScript call in the same	 thread.   The
       stored  file  name is returned, and the stored encoding name is written
       to space	pointed	to by encodingPtr, when	that is	not NULL.

       The file	name and encoding values managed by the	routines  Tcl_SetStar-
       tupScript and Tcl_GetStartupScript are stored per-thread.  Although the
       storage and retrieval functions of these	routines work in  any  thread,
       only those calls	in the same master thread as Tcl_Main can have any in-
       fluence on it.

       The caller of Tcl_Main may call Tcl_SetStartupScript first to establish
       its  desired  startup  script.	If Tcl_Main finds that no such startup
       script has been established, it consults	the  first  few	 arguments  in
       argv.  If they 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  contents  of  that	 file.	 Tcl_Main  then	 calls
       Tcl_SetStartupScript with these values.

       Tcl_Main	then defines 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 application	initialization
       routine might also call Tcl_SetStartupScript to (re-)set	the  file  and
       encoding	 to  be	 used as a startup script.  The	procedure must have an
       interface 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 calls Tcl_GetStartupScript
       to determine what startup script	has been  requested,  if  any.	 If  a
       startup	script	has  been  provided, Tcl_Main attempts to evaluate it.
       Otherwise, interactive mode begins with	examination  of	 the  variable
       tcl_rcFileName  in the master interpreter.  If that variable exists and
       holds the name of a readable file, the contents of that file are	evalu-
       ated  in	 the  master  interpreter.  Then interactive operations	begin,
       with prompts and	command	evaluation results  written  to	 the  standard
       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 channel 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), encoding(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_GetStartupScript.tcl86&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help