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