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

NAME

8       Tcl_Main, Tcl_SetStartupScript, Tcl_GetStartupScript, Tcl_SetMainLoop -
9       main program, startup script, and event loop definition  for  Tcl-based
10       applications
11

SYNOPSIS

13       #include <tcl.h>
14
15       Tcl_Main(argc, argv, appInitProc)
16
17       Tcl_SetStartupScript(path, encoding)
18
19       Tcl_Obj *
20       Tcl_GetStartupScript(encodingPtr)
21
22       Tcl_SetMainLoop(mainLoopProc)
23

ARGUMENTS

25       int argc (in)                                Number   of   elements  in
26                                                    argv.
27
28       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
35       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
41       Tcl_Obj *path (in)                           Name  of  file  to  use as
42                                                    startup script, or NULL.
43
44       const char *encoding (in)                    Encoding of file to use as
45                                                    startup script, or NULL.
46
47       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
52       Tcl_MainLoopProc *mainLoopProc (in)          Address of an application-
53                                                    specific event loop proce‐
54                                                    dure.
55______________________________________________________________________________
56

DESCRIPTION

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
69       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
77       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
81       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
86       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
90       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
94       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
99       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
106       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
111       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
117       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
126       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
130       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
139              typedef int Tcl_AppInitProc(
140                      Tcl_Interp *interp);
141
142       AppInitProc is almost always a pointer to Tcl_AppInit; for more details
143       on this procedure, see the documentation for Tcl_AppInit.
144
145       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
161       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
170              typedef void Tcl_MainLoopProc(void);
171
172       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

SEE ALSO

181       tclsh(1),         Tcl_GetStdChannel(3),        Tcl_StandardChannels(3),
182       Tcl_AppInit(3), exit(n), encoding(n)
183

KEYWORDS

185       application-specific initialization, command-line arguments, main  pro‐
186       gram
187
188
189
190Tcl                                   8.4                          Tcl_Main(3)
Impressum