1 | '\" |
---|
2 | '\" Copyright (c) 1994 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" Copyright (c) 2000 Ajuba Solutions. |
---|
5 | '\" |
---|
6 | '\" See the file "license.terms" for information on usage and redistribution |
---|
7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
8 | '\" |
---|
9 | '\" RCS: @(#) $Id: Tcl_Main.3,v 1.16 2007/12/13 15:22:32 dgp Exp $ |
---|
10 | '\" |
---|
11 | .so man.macros |
---|
12 | .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures" |
---|
13 | .BS |
---|
14 | .SH NAME |
---|
15 | Tcl_Main, Tcl_SetMainLoop \- main program and event loop definition for Tcl-based applications |
---|
16 | .SH SYNOPSIS |
---|
17 | .nf |
---|
18 | \fB#include <tcl.h>\fR |
---|
19 | .sp |
---|
20 | \fBTcl_Main\fR(\fIargc, argv, appInitProc\fR) |
---|
21 | .sp |
---|
22 | \fBTcl_SetMainLoop\fR(\fImainLoopProc\fR) |
---|
23 | .SH ARGUMENTS |
---|
24 | .AS Tcl_MainLoopProc *mainLoopProc |
---|
25 | .AP int argc in |
---|
26 | Number of elements in \fIargv\fR. |
---|
27 | .AP char *argv[] in |
---|
28 | Array of strings containing command-line arguments. |
---|
29 | .AP Tcl_AppInitProc *appInitProc in |
---|
30 | Address of an application-specific initialization procedure. |
---|
31 | The value for this argument is usually \fBTcl_AppInit\fR. |
---|
32 | .AP Tcl_MainLoopProc *mainLoopProc in |
---|
33 | Address of an application-specific event loop procedure. |
---|
34 | .BE |
---|
35 | |
---|
36 | .SH DESCRIPTION |
---|
37 | .PP |
---|
38 | \fBTcl_Main\fR can serve as the main program for Tcl-based shell |
---|
39 | applications. A |
---|
40 | .QW "shell application" |
---|
41 | is a program |
---|
42 | like tclsh or wish that supports both interactive interpretation |
---|
43 | of Tcl and evaluation of a script contained in a file given as |
---|
44 | a command line argument. \fBTcl_Main\fR is offered as a convenience |
---|
45 | to developers of shell applications, so they do not have to |
---|
46 | reproduce all of the code for proper initialization of the Tcl |
---|
47 | library and interactive shell operation. Other styles of embedding |
---|
48 | Tcl in an application are not supported by \fBTcl_Main\fR. Those |
---|
49 | must be achieved by calling lower level functions in the Tcl library |
---|
50 | directly. |
---|
51 | |
---|
52 | The \fBTcl_Main\fR function has been offered by the Tcl library |
---|
53 | since release Tcl 7.4. In older releases of Tcl, the Tcl library |
---|
54 | itself defined a function \fBmain\fR, but that lacks flexibility |
---|
55 | of embedding style and having a function \fBmain\fR in a library |
---|
56 | (particularly a shared library) causes problems on many systems. |
---|
57 | Having \fBmain\fR in the Tcl library would also make it hard to use |
---|
58 | Tcl in C++ programs, since C++ programs must have special C++ |
---|
59 | \fBmain\fR functions. |
---|
60 | .PP |
---|
61 | Normally each shell application contains a small \fBmain\fR function |
---|
62 | that does nothing but invoke \fBTcl_Main\fR. |
---|
63 | \fBTcl_Main\fR then does all the work of creating and running a |
---|
64 | \fBtclsh\fR-like application. |
---|
65 | .PP |
---|
66 | \fBTcl_Main\fR is not provided by the public interface of Tcl's |
---|
67 | stub library. Programs that call \fBTcl_Main\fR must be linked |
---|
68 | against the standard Tcl library. Extensions (stub-enabled or |
---|
69 | not) are not intended to call \fBTcl_Main\fR. |
---|
70 | .PP |
---|
71 | \fBTcl_Main\fR is not thread-safe. It should only be called by |
---|
72 | a single master thread of a multi-threaded application. This |
---|
73 | restriction is not a problem with normal use described above. |
---|
74 | .PP |
---|
75 | \fBTcl_Main\fR and therefore all applications based upon it, like |
---|
76 | \fBtclsh\fR, use \fBTcl_GetStdChannel\fR to initialize the standard |
---|
77 | channels to their default values. See \fBTcl_StandardChannels\fR for |
---|
78 | more information. |
---|
79 | .PP |
---|
80 | \fBTcl_Main\fR supports two modes of operation, depending on the |
---|
81 | values of \fIargc\fR and \fIargv\fR. If the first few arguments |
---|
82 | in \fIargv\fR match ?\fB\-encoding \fIname\fR? ?\fIfileName\fR?, |
---|
83 | where \fIfileName\fR does not begin with the character \fI\-\fR, |
---|
84 | then \fIfileName\fR is taken to be the name of a file containing |
---|
85 | a \fIstartup script\fR, and \fIname\fR is taken to be the name |
---|
86 | of the encoding of the contents of that file, which \fBTcl_Main\fR |
---|
87 | will attempt to evaluate. Otherwise, \fBTcl_Main\fR will enter an |
---|
88 | interactive mode. |
---|
89 | .PP |
---|
90 | In either mode, \fBTcl_Main\fR will define in its master interpreter |
---|
91 | the Tcl variables \fIargc\fR, \fIargv\fR, \fIargv0\fR, and |
---|
92 | \fItcl_interactive\fR, as described in the documentation for \fBtclsh\fR. |
---|
93 | .PP |
---|
94 | When it has finished its own initialization, but before it processes |
---|
95 | commands, \fBTcl_Main\fR calls the procedure given by the |
---|
96 | \fIappInitProc\fR argument. This procedure provides a |
---|
97 | .QW hook |
---|
98 | for the application to perform its own initialization of the interpreter |
---|
99 | created by \fBTcl_Main\fR, such as defining application-specific |
---|
100 | commands. The procedure must have an interface that matches the |
---|
101 | type \fBTcl_AppInitProc\fR: |
---|
102 | .CS |
---|
103 | typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR); |
---|
104 | .CE |
---|
105 | |
---|
106 | \fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR; for more |
---|
107 | details on this procedure, see the documentation for \fBTcl_AppInit\fR. |
---|
108 | .PP |
---|
109 | When the \fIappInitProc\fR is finished, \fBTcl_Main\fR enters one |
---|
110 | of its two modes. If a startup script has been provided, \fBTcl_Main\fR |
---|
111 | attempts to evaluate it. Otherwise, interactive mode begins with |
---|
112 | examination of the variable \fItcl_rcFileName\fR in the master |
---|
113 | interpreter. If that variable exists and holds the name of a readable |
---|
114 | file, the contents of that file are evaluated in the master interpreter. |
---|
115 | Then interactive operations begin, |
---|
116 | with prompts and command evaluation results written to the standard |
---|
117 | output channel, and commands read from the standard input channel |
---|
118 | and then evaluated. The prompts written to the standard output |
---|
119 | channel may be customized by defining the Tcl variables \fItcl_prompt1\fR |
---|
120 | and \fItcl_prompt2\fR as described in the documentation for \fBtclsh\fR. |
---|
121 | The prompts and command evaluation results are written to the standard |
---|
122 | output channel only if the Tcl variable \fItcl_interactive\fR in the |
---|
123 | master interpreter holds a non-zero integer value. |
---|
124 | .PP |
---|
125 | \fBTcl_SetMainLoop\fR allows setting an event loop procedure to be run. |
---|
126 | This allows, for example, Tk to be dynamically loaded and set its event |
---|
127 | loop. The event loop will run following the startup script. If you |
---|
128 | are in interactive mode, setting the main loop procedure will cause the |
---|
129 | prompt to become fileevent based and then the loop procedure is called. |
---|
130 | When the loop procedure returns in interactive mode, interactive operation |
---|
131 | will continue. |
---|
132 | The main loop procedure must have an interface that matches the type |
---|
133 | \fBTcl_MainLoopProc\fR: |
---|
134 | .CS |
---|
135 | typedef void Tcl_MainLoopProc(void); |
---|
136 | .CE |
---|
137 | .PP |
---|
138 | \fBTcl_Main\fR does not return. Normally a program based on |
---|
139 | \fBTcl_Main\fR will terminate when the \fBexit\fR command is |
---|
140 | evaluated. In interactive mode, if an EOF or channel error |
---|
141 | is encountered on the standard input channel, then \fBTcl_Main\fR |
---|
142 | itself will evaluate the \fBexit\fR command after the main loop |
---|
143 | procedure (if any) returns. In non-interactive mode, after |
---|
144 | \fBTcl_Main\fR evaluates the startup script, and the main loop |
---|
145 | procedure (if any) returns, \fBTcl_Main\fR will also evaluate |
---|
146 | the \fBexit\fR command. |
---|
147 | |
---|
148 | .SH "SEE ALSO" |
---|
149 | tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3), |
---|
150 | exit(n) |
---|
151 | |
---|
152 | .SH KEYWORDS |
---|
153 | application-specific initialization, command-line arguments, main program |
---|