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 ele
- ments in argv.
- char *argv[] (in) Array of
- strings con
taining com
mand-line argu
ments. - Tcl_AppInitProc *appInitProc (in) Address of an
- applicationspecific ini
tialization
procedure. The
value for this
argument is
usually
Tcl_AppInit. - Tcl_MainLoopProc *mainLoopProc (in) Address of an
- applicationspecific event
loop procedure.
DESCRIPTION
Tcl_Main can serve as the main program for Tcl-based shell
applications. A ``shell application'' is a program like
tclsh or wish that supports both interactive interpreta
tion of Tcl and evaluation of a script contained in a file
given as a command line argument. Tcl_Main is offered as
a convenience to developers of shell applications, so they
do not have to reproduce all of the code for proper ini
tialization of the Tcl library and interactive shell oper
ation. 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 prob
lems 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 tclshlike 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 library. Extensions (stubenabled or not) are not intended to call Tcl_Main.
Tcl_Main is not thread-safe. It should only be called by
a single master 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 stan
dard channels to their default values. See Tcl_Standard
Channels for more information.
Tcl_Main supports two modes of operation, depending on the
values of argc and argv. If argv[1] exists and does not
begin with the character -, it is taken to be the name of
a file containing a startup script, which Tcl_Main will
attempt to evaluate. Otherwise, Tcl_Main will enter an
interactive mode.
In either mode, Tcl_Main will define in its master inter preter the Tcl variables argc, argv, argv0, and tcl_inter_ active, 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 argument. This procedure provides a ``hook'' for the application to perform its own initial
ization of the interpreter created by Tcl_Main, such as defining application-specific commands. The procedure
must have an interface that matches the type Tcl_AppInit Proc: - 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 variable tcl_rcFile_ Name 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 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 documenta tion 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 proce
dure is called. When the loop procedure returns in inter
active mode, interactive operation 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 evalu
ated. 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) returns, Tcl_Main will also evalu ate the exit command.
SEE ALSO
tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3),
Tcl_AppInit(3), exit(n)
KEYWORDS
- application-specific initialization, command-line argu
ments, main program