1Tcl_Main(3) Tcl Library Procedures Tcl_Main(3)
2______________________________________________________________________________
6
8 Tcl_Main, Tcl_MainEx, Tcl_MainExW, Tcl_SetStartupScript, Tcl_GetStar‐
9 tupScript, Tcl_SetMainLoop - main program, startup script, and event
10 loop definition for Tcl-based applications
11
13 #include <tcl.h>
14 Tcl_Main(argc, argv, appInitProc)
16 Tcl_MainEx(argc, charargv, appInitProc, interp)
18 Tcl_MainExW(argc, wideargv, appInitProc, interp)
20 Tcl_SetStartupScript(path, encoding)
22 Tcl_Obj *
24 Tcl_GetStartupScript(encodingPtr)
25 Tcl_SetMainLoop(mainLoopProc)
27
29 int argc (in) Number of elements in
30 argv.
31 char *argv[] (in) Array of strings contain‐
33 ing command-line argu‐
34 ments. On Windows, when
35 using -DUNICODE, the pa‐
36 rameter type changes to
37 wchar_t *.
38 char *charargv[] (in) As argv, but does not
40 change type to wchar_t.
41 char *wideargv[] (in) As argv, but type is al‐
43 ways wchar_t.
44 Tcl_AppInitProc *appInitProc (in) Address of an application-
46 specific initialization
47 procedure. The value for
48 this argument is usually
49 Tcl_AppInit.
50 Tcl_Obj *path (in) Name of file to use as
52 startup script, or NULL.
53 const char *encoding (in) Encoding of file to use as
55 startup script, or NULL.
56 const char **encodingPtr (out) If non-NULL, location to
58 write a copy of the (const
59 char *) pointing to the
60 encoding name.
61 Tcl_MainLoopProc *mainLoopProc (in) Address of an application-
63 specific event loop proce‐
64 dure.
65 Tcl_Interp *interp (in) Already created Tcl Inter‐
67 preter.
68______________________________________________________________________________
69
71 Tcl_Main can serve as the main program for Tcl-based shell applica‐
72 tions. A “shell application” is a program like tclsh or wish that sup‐
73 ports both interactive interpretation of Tcl and evaluation of a script
74 contained in a file given as a command line argument. Tcl_Main is of‐
75 fered as a convenience to developers of shell applications, so they do
76 not have to reproduce all of the code for proper initialization of the
77 Tcl library and interactive shell operation. Other styles of embedding
78 Tcl in an application are not supported by Tcl_Main. Those must be
79 achieved by calling lower level functions in the Tcl library directly.
80 The Tcl_Main function has been offered by the Tcl library since release
82 Tcl 7.4. In older releases of Tcl, the Tcl library itself defined a
83 function main, but that lacks flexibility of embedding style and having
84 a function main in a library (particularly a shared library) causes
85 problems on many systems. Having main in the Tcl library would also
86 make it hard to use Tcl in C++ programs, since C++ programs must have
87 special C++ main functions.
88 Normally each shell application contains a small main function that
90 does nothing but invoke Tcl_Main. Tcl_Main then does all the work of
91 creating and running a tclsh-like application.
92 Tcl_Main is not provided by the public interface of Tcl's stub library.
94 Programs that call Tcl_Main must be linked against the standard Tcl li‐
95 brary. Extensions (stub-enabled or not) are not intended to call
96 Tcl_Main.
97 Tcl_Main is not thread-safe. It should only be called by a single main
99 thread of a multi-threaded application. This restriction is not a
100 problem with normal use described above.
101 Tcl_Main and therefore all applications based upon it, like tclsh, use
103 Tcl_GetStdChannel to initialize the standard channels to their default
104 values. See Tcl_StandardChannels for more information.
105 Tcl_Main supports two modes of operation, depending on whether the
107 filename and encoding of a startup script has been established. The
108 routines Tcl_SetStartupScript and Tcl_GetStartupScript are the tools
109 for controlling this configuration of Tcl_Main.
110 Tcl_SetStartupScript registers the value path as the name of the file
112 for Tcl_Main to evaluate as its startup script. The value encoding is
113 Tcl's name for the encoding used to store the text in that file. A
114 value of NULL for encoding is a signal to use the system encoding. A
115 value of NULL for path erases any existing registration so that
116 Tcl_Main will not evaluate any startup script.
117 Tcl_GetStartupScript queries the registered file name and encoding set
119 by the most recent Tcl_SetStartupScript call in the same thread. The
120 stored file name is returned, and the stored encoding name is written
121 to space pointed to by encodingPtr, when that is not NULL.
122 The file name and encoding values managed by the routines Tcl_SetStar‐
124 tupScript and Tcl_GetStartupScript are stored per-thread. Although the
125 storage and retrieval functions of these routines work in any thread,
126 only those calls in the same main thread as Tcl_Main can have any in‐
127 fluence on it.
128 The caller of Tcl_Main may call Tcl_SetStartupScript first to establish
130 its desired startup script. If Tcl_Main finds that no such startup
131 script has been established, it consults the first few arguments in
132 argv. If they match ?-encoding name? fileName, where fileName does not
133 begin with the character -, then fileName is taken to be the name of a
134 file containing a startup script, and name is taken to be the name of
135 the encoding of the contents of that file. Tcl_Main then calls
136 Tcl_SetStartupScript with these values.
137 Tcl_Main then defines in its main interpreter the Tcl variables argc,
139 argv, argv0, and tcl_interactive, as described in the documentation for
140 tclsh.
141 When it has finished its own initialization, but before it processes
143 commands, Tcl_Main calls the procedure given by the appInitProc argu‐
144 ment. This procedure provides a “hook” for the application to perform
145 its own initialization of the interpreter created by Tcl_Main, such as
146 defining application-specific commands. The application initialization
147 routine might also call Tcl_SetStartupScript to (re-)set the file and
148 encoding to be used as a startup script. The procedure must have an
149 interface that matches the type Tcl_AppInitProc:
150 typedef int Tcl_AppInitProc(
152 Tcl_Interp *interp);
153 AppInitProc is almost always a pointer to Tcl_AppInit; for more details
155 on this procedure, see the documentation for Tcl_AppInit.
156 When the appInitProc is finished, Tcl_Main calls Tcl_GetStartupScript
158 to determine what startup script has been requested, if any. If a
159 startup script has been provided, Tcl_Main attempts to evaluate it.
160 Otherwise, interactive mode begins with examination of the variable
161 tcl_rcFileName in the main interpreter. If that variable exists and
162 holds the name of a readable file, the contents of that file are evalu‐
163 ated in the main interpreter. Then interactive operations begin, with
164 prompts and command evaluation results written to the standard output
165 channel, and commands read from the standard input channel and then
166 evaluated. The prompts written to the standard output channel may be
167 customized by defining the Tcl variables tcl_prompt1 and tcl_prompt2 as
168 described in the documentation for tclsh. The prompts and command
169 evaluation results are written to the standard output channel only if
170 the Tcl variable tcl_interactive in the main interpreter holds a non-
171 zero integer value.
172 Tcl_SetMainLoop allows setting an event loop procedure to be run. This
174 allows, for example, Tk to be dynamically loaded and set its event
175 loop. The event loop will run following the startup script. If you
176 are in interactive mode, setting the main loop procedure will cause the
177 prompt to become fileevent based and then the loop procedure is called.
178 When the loop procedure returns in interactive mode, interactive opera‐
179 tion will continue. The main loop procedure must have an interface
180 that matches the type Tcl_MainLoopProc:
181 typedef void Tcl_MainLoopProc(void);
183 Tcl_Main does not return. Normally a program based on Tcl_Main will
185 terminate when the exit command is evaluated. In interactive mode, if
186 an EOF or channel error is encountered on the standard input channel,
187 then Tcl_Main itself will evaluate the exit command after the main loop
188 procedure (if any) returns. In non-interactive mode, after Tcl_Main
189 evaluates the startup script, and the main loop procedure (if any) re‐
190 turns, Tcl_Main will also evaluate the exit command.
191
193 tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_Ap‐
194 pInit(3), exit(n), encoding(n)
195
197 application-specific initialization, command-line arguments, main pro‐
198 gram
199Tcl 8.4 Tcl_Main(3)