1Tcl_Main(3)                 Tcl Library Procedures                 Tcl_Main(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

13       #include <tcl.h>
14
15       Tcl_Main(argc, argv, appInitProc)
16
17       Tcl_MainEx(argc, charargv, appInitProc, interp)
18
19       Tcl_MainExW(argc, wideargv, appInitProc, interp)
20
21       Tcl_SetStartupScript(path, encoding)
22
23       Tcl_Obj *
24       Tcl_GetStartupScript(encodingPtr)
25
26       Tcl_SetMainLoop(mainLoopProc)
27

ARGUMENTS

29       int argc (in)                                Number   of   elements  in
30                                                    argv.
31
32       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
39       char *charargv[] (in)                        As   argv,  but  does  not
40                                                    change type to wchar_t.
41
42       char *wideargv[] (in)                        As argv, but type  is  al‐
43                                                    ways wchar_t.
44
45       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
51       Tcl_Obj *path (in)                           Name  of  file  to  use as
52                                                    startup script, or NULL.
53
54       const char *encoding (in)                    Encoding of file to use as
55                                                    startup script, or NULL.
56
57       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
62       Tcl_MainLoopProc *mainLoopProc (in)          Address of an application-
63                                                    specific event loop proce‐
64                                                    dure.
65
66       Tcl_Interp *interp (in)                      Already created Tcl Inter‐
67                                                    preter.
68______________________________________________________________________________
69

DESCRIPTION

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
81       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
89       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
93       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
98       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
102       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
106       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
111       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
118       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
123       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
129       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
138       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
142       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
151              typedef int Tcl_AppInitProc(
152                      Tcl_Interp *interp);
153
154       AppInitProc is almost always a pointer to Tcl_AppInit; for more details
155       on this procedure, see the documentation for Tcl_AppInit.
156
157       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
173       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
182              typedef void Tcl_MainLoopProc(void);
183
184       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

SEE ALSO

193       tclsh(1),    Tcl_GetStdChannel(3),   Tcl_StandardChannels(3),   Tcl_Ap‐
194       pInit(3), exit(n), encoding(n)
195

KEYWORDS

197       application-specific initialization, command-line arguments, main  pro‐
198       gram
199
200
201
202Tcl                                   8.4                          Tcl_Main(3)
Impressum