1Tcl_Main(3) Tcl Library Procedures Tcl_Main(3)
2______________________________________________________________________________
6
8 Tcl_Main, Tcl_SetMainLoop - main program and event loop definition for
9 Tcl-based applications
10
12 #include <tcl.h>
13 Tcl_Main(argc, argv, appInitProc)
15 Tcl_SetMainLoop(mainLoopProc)
17
19 int argc (in) Number of elements in
20 argv.
21 char *argv[] (in) Array of strings contain‐
23 ing command-line argu‐
24 ments.
25 Tcl_AppInitProc *appInitProc (in) Address of an application-
27 specific initialization
28 procedure. The value for
29 this argument is usually
30 Tcl_AppInit.
31 Tcl_MainLoopProc *mainLoopProc (in) Address of an application-
33 specific event loop proce‐
34 dure.
35_________________________________________________________________
36
39 Tcl_Main can serve as the main program for Tcl-based shell applica‐
40 tions. A “shell application” is a program like tclsh or wish that sup‐
41 ports both interactive interpretation of Tcl and evaluation of a script
42 contained in a file given as a command line argument. Tcl_Main is
43 offered as a convenience to developers of shell applications, so they
44 do not have to reproduce all of the code for proper initialization of
45 the Tcl library and interactive shell operation. Other styles of
46 embedding Tcl in an application are not supported by Tcl_Main. Those
47 must be achieved by calling lower level functions in the Tcl library
48 directly.
49 The Tcl_Main function has been offered by the Tcl library since release
51 Tcl 7.4. In older releases of Tcl, the Tcl library itself defined a
52 function main, but that lacks flexibility of embedding style and having
53 a function main in a library (particularly a shared library) causes
54 problems on many systems. Having main in the Tcl library would also
55 make it hard to use Tcl in C++ programs, since C++ programs must have
56 special C++ main functions.
57 Normally each shell application contains a small main function that
59 does nothing but invoke Tcl_Main. Tcl_Main then does all the work of
60 creating and running a tclsh-like application.
61 Tcl_Main is not provided by the public interface of Tcl's stub library.
63 Programs that call Tcl_Main must be linked against the standard Tcl
64 library. Extensions (stub-enabled or not) are not intended to call
65 Tcl_Main.
66 Tcl_Main is not thread-safe. It should only be called by a single mas‐
68 ter thread of a multi-threaded application. This restriction is not a
69 problem with normal use described above.
70 Tcl_Main and therefore all applications based upon it, like tclsh, use
72 Tcl_GetStdChannel to initialize the standard channels to their default
73 values. See Tcl_StandardChannels for more information.
74 Tcl_Main supports two modes of operation, depending on the values of
76 argc and argv. If the first few arguments in argv match ?-encoding
77 name? fileName, where fileName does not begin with the character -,
78 then fileName is taken to be the name of a file containing a startup
79 script, and name is taken to be the name of the encoding of the con‐
80 tents of that file, which Tcl_Main will attempt to evaluate. Other‐
81 wise, Tcl_Main will enter an interactive mode.
82 In either mode, Tcl_Main will define in its master interpreter the Tcl
84 variables argc, argv, argv0, and tcl_interactive, as described in the
85 documentation for tclsh.
86 When it has finished its own initialization, but before it processes
88 commands, Tcl_Main calls the procedure given by the appInitProc argu‐
89 ment. This procedure provides a “hook” for the application to perform
90 its own initialization of the interpreter created by Tcl_Main, such as
91 defining application-specific commands. The procedure must have an
92 interface that matches the type Tcl_AppInitProc:
93 typedef int Tcl_AppInitProc(Tcl_Interp *interp);
94 AppInitProc is almost always a pointer to Tcl_AppInit; for more details
96 on this procedure, see the documentation for Tcl_AppInit.
97 When the appInitProc is finished, Tcl_Main enters one of its two modes.
99 If a startup script has been provided, Tcl_Main attempts to evaluate
100 it. Otherwise, interactive mode begins with examination of the vari‐
101 able tcl_rcFileName in the master interpreter. If that variable exists
102 and holds the name of a readable file, the contents of that file are
103 evaluated in the master interpreter. Then interactive operations
104 begin, with prompts and command evaluation results written to the stan‐
105 dard output channel, and commands read from the standard input channel
106 and then evaluated. The prompts written to the standard output channel
107 may be customized by defining the Tcl variables tcl_prompt1 and
108 tcl_prompt2 as described in the documentation for tclsh. The prompts
109 and command evaluation results are written to the standard output chan‐
110 nel only if the Tcl variable tcl_interactive in the master interpreter
111 holds a non-zero integer value.
112 Tcl_SetMainLoop allows setting an event loop procedure to be run. This
114 allows, for example, Tk to be dynamically loaded and set its event
115 loop. The event loop will run following the startup script. If you
116 are in interactive mode, setting the main loop procedure will cause the
117 prompt to become fileevent based and then the loop procedure is called.
118 When the loop procedure returns in interactive mode, interactive opera‐
119 tion will continue. The main loop procedure must have an interface
120 that matches the type Tcl_MainLoopProc:
121 typedef void Tcl_MainLoopProc(void);
122 Tcl_Main does not return. Normally a program based on Tcl_Main will
124 terminate when the exit command is evaluated. In interactive mode, if
125 an EOF or channel error is encountered on the standard input channel,
126 then Tcl_Main itself will evaluate the exit command after the main loop
127 procedure (if any) returns. In non-interactive mode, after Tcl_Main
128 evaluates the startup script, and the main loop procedure (if any)
129 returns, Tcl_Main will also evaluate the exit command.
130
133 tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3),
134 Tcl_AppInit(3), exit(n)
135
138 application-specific initialization, command-line arguments, main pro‐
139 gram
140Tcl 8.4 Tcl_Main(3)