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