util/X86LINUX64/man/man3/Tcl_SetMainLoop.3

   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 .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures"
  10 .\" The -*- nroff -*- definitions below are for supplemental macros used
  11 .\" in Tcl/Tk manual entries.
  12 .\"
  13 .\" .AP type name in/out ?indent?
  14 .\"     Start paragraph describing an argument to a library procedure.
  15 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  16 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  17 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  18 .\"     needed;  use .AS below instead)
  19 .\"
  20 .\" .AS ?type? ?name?
  21 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  22 .\"     name are examples of largest possible arguments that will be passed
  23 .\"     to .AP later.  If args are omitted, default tab stops are used.
  24 .\"
  25 .\" .BS
  26 .\"     Start box enclosure.  From here until next .BE, everything will be
  27 .\"     enclosed in one large box.
  28 .\"
  29 .\" .BE
  30 .\"     End of box enclosure.
  31 .\"
  32 .\" .CS
  33 .\"     Begin code excerpt.
  34 .\"
  35 .\" .CE
  36 .\"     End code excerpt.
  37 .\"
  38 .\" .VS ?version? ?br?
  39 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  40 .\"     of man pages.  The first argument is ignored and used for recording
  41 .\"     the version when the .VS was added, so that the sidebars can be
  42 .\"     found and removed when they reach a certain age.  If another argument
  43 .\"     is present, then a line break is forced before starting the sidebar.
  44 .\"
  45 .\" .VE
  46 .\"     End of vertical sidebar.
  47 .\"
  48 .\" .DS
  49 .\"     Begin an indented unfilled display.
  50 .\"
  51 .\" .DE
  52 .\"     End of indented unfilled display.
  53 .\"
  54 .\" .SO ?manpage?
  55 .\"     Start of list of standard options for a Tk widget. The manpage
  56 .\"     argument defines where to look up the standard options; if
  57 .\"     omitted, defaults to "options". The options follow on successive
  58 .\"     lines, in three columns separated by tabs.
  59 .\"
  60 .\" .SE
  61 .\"     End of list of standard options for a Tk widget.
  62 .\"
  63 .\" .OP cmdName dbName dbClass
  64 .\"     Start of description of a specific option.  cmdName gives the
  65 .\"     option's name as specified in the class command, dbName gives
  66 .\"     the option's name in the option database, and dbClass gives
  67 .\"     the option's class in the option database.
  68 .\"
  69 .\" .UL arg1 arg2
  70 .\"     Print arg1 underlined, then print arg2 normally.
  71 .\"
  72 .\" .QW arg1 ?arg2?
  73 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  74 .\"
  75 .\" .PQ arg1 ?arg2?
  76 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  77 .\"     (for trailing punctuation) and then a closing parenthesis.
  78 .\"
  79 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  80 .if t .wh -1.3i ^B
  81 .nr ^l \n(.l
  82 .ad b
  83 .\"     # Start an argument description
  84 .de AP
  85 .ie !"\\$4"" .TP \\$4
  86 .el \{\
  87 .   ie !"\\$2"" .TP \\n()Cu
  88 .   el          .TP 15
  89 .\}
  90 .ta \\n()Au \\n()Bu
  91 .ie !"\\$3"" \{\
  92 \&\\$1 \\fI\\$2\\fP (\\$3)
  93 .\".b
  94 .\}
  95 .el \{\
  96 .br
  97 .ie !"\\$2"" \{\
  98 \&\\$1  \\fI\\$2\\fP
  99 .\}
 100 .el \{\
 101 \&\\fI\\$1\\fP
 102 .\}
 103 .\}
 104 ..
 105 .\"     # define tabbing values for .AP
 106 .de AS
 107 .nr )A 10n
 108 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 109 .nr )B \\n()Au+15n
 110 .\"
 111 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 112 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 113 ..
 114 .AS Tcl_Interp Tcl_CreateInterp in/out
 115 .\"     # BS - start boxed text
 116 .\"     # ^y = starting y location
 117 .\"     # ^b = 1
 118 .de BS
 119 .br
 120 .mk ^y
 121 .nr ^b 1u
 122 .if n .nf
 123 .if n .ti 0
 124 .if n \l'\\n(.lu\(ul'
 125 .if n .fi
 126 ..
 127 .\"     # BE - end boxed text (draw box now)
 128 .de BE
 129 .nf
 130 .ti 0
 131 .mk ^t
 132 .ie n \l'\\n(^lu\(ul'
 133 .el \{\
 134 .\"     Draw four-sided box normally, but don't draw top of
 135 .\"     box if the box started on an earlier page.
 136 .ie !\\n(^b-1 \{\
 137 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 138 .\}
 139 .el \}\
 140 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 141 .\}
 142 .\}
 143 .fi
 144 .br
 145 .nr ^b 0
 146 ..
 147 .\"     # VS - start vertical sidebar
 148 .\"     # ^Y = starting y location
 149 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 150 .de VS
 151 .if !"\\$2"" .br
 152 .mk ^Y
 153 .ie n 'mc \s12\(br\s0
 154 .el .nr ^v 1u
 155 ..
 156 .\"     # VE - end of vertical sidebar
 157 .de VE
 158 .ie n 'mc
 159 .el \{\
 160 .ev 2
 161 .nf
 162 .ti 0
 163 .mk ^t
 164 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 165 .sp -1
 166 .fi
 167 .ev
 168 .\}
 169 .nr ^v 0
 170 ..
 171 .\"     # Special macro to handle page bottom:  finish off current
 172 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 173 .\"     # page bottom macro.
 174 .de ^B
 175 .ev 2
 176 'ti 0
 177 'nf
 178 .mk ^t
 179 .if \\n(^b \{\
 180 .\"     Draw three-sided box if this is the box's first page,
 181 .\"     draw two sides but no top otherwise.
 182 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 183 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 184 .\}
 185 .if \\n(^v \{\
 186 .nr ^x \\n(^tu+1v-\\n(^Yu
 187 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 188 .\}
 189 .bp
 190 'fi
 191 .ev
 192 .if \\n(^b \{\
 193 .mk ^y
 194 .nr ^b 2
 195 .\}
 196 .if \\n(^v \{\
 197 .mk ^Y
 198 .\}
 199 ..
 200 .\"     # DS - begin display
 201 .de DS
 202 .RS
 203 .nf
 204 .sp
 205 ..
 206 .\"     # DE - end display
 207 .de DE
 208 .fi
 209 .RE
 210 .sp
 211 ..
 212 .\"     # SO - start of list of standard options
 213 .de SO
 214 'ie '\\$1'' .ds So \\fBoptions\\fR
 215 'el .ds So \\fB\\$1\\fR
 216 .SH "STANDARD OPTIONS"
 217 .LP
 218 .nf
 219 .ta 5.5c 11c
 220 .ft B
 221 ..
 222 .\"     # SE - end of list of standard options
 223 .de SE
 224 .fi
 225 .ft R
 226 .LP
 227 See the \\*(So manual entry for details on the standard options.
 228 ..
 229 .\"     # OP - start of full description for a single option
 230 .de OP
 231 .LP
 232 .nf
 233 .ta 4c
 234 Command-Line Name:      \\fB\\$1\\fR
 235 Database Name:  \\fB\\$2\\fR
 236 Database Class: \\fB\\$3\\fR
 237 .fi
 238 .IP
 239 ..
 240 .\"     # CS - begin code excerpt
 241 .de CS
 242 .RS
 243 .nf
 244 .ta .25i .5i .75i 1i
 245 ..
 246 .\"     # CE - end code excerpt
 247 .de CE
 248 .fi
 249 .RE
 250 ..
 251 .\"     # UL - underline word
 252 .de UL
 253 \\$1\l'|0\(ul'\\$2
 254 ..
 255 .\"     # QW - apply quotation marks to word
 256 .de QW
 257 .ie '\\*(lq'"' ``\\$1''\\$2
 258 .\"" fix emacs highlighting
 259 .el \\*(lq\\$1\\*(rq\\$2
 260 ..
 261 .\"     # PQ - apply parens and quotation marks to word
 262 .de PQ
 263 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 264 .\"" fix emacs highlighting
 265 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 266 ..
 267 .\"     # QR - quoted range
 268 .de QR
 269 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 270 .\"" fix emacs highlighting
 271 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 272 ..
 273 .\"     # MT - "empty" string
 274 .de MT
 275 .QW ""
 276 ..
 277 .BS
 278 .SH NAME
 279 Tcl_Main, Tcl_SetStartupScript, Tcl_GetStartupScript, Tcl_SetMainLoop \- main program, startup script, and event loop definition for Tcl-based applications
 280 .SH SYNOPSIS
 281 .nf
 282 \fB#include <tcl.h>\fR
 283 .sp
 284 \fBTcl_Main\fR(\fIargc, argv, appInitProc\fR)
 285 .sp
 286 \fBTcl_SetStartupScript\fR(\fIpath, encoding\fR)
 287 .sp
 288 Tcl_Obj *
 289 \fBTcl_GetStartupScript\fR(\fIencodingPtr\fR)
 290 .sp
 291 \fBTcl_SetMainLoop\fR(\fImainLoopProc\fR)
 292 .SH ARGUMENTS
 293 .AS Tcl_MainLoopProc *mainLoopProc
 294 .AP int argc in
 295 Number of elements in \fIargv\fR.
 296 .AP char *argv[] in
 297 Array of strings containing command-line arguments. On Windows, when
 298 using -DUNICODE, the parameter type changes to wchar_t *.
 299 .AP Tcl_AppInitProc *appInitProc in
 300 Address of an application-specific initialization procedure.
 301 The value for this argument is usually \fBTcl_AppInit\fR.
 302 .AP Tcl_Obj *path in
 303 Name of file to use as startup script, or NULL.
 304 .AP "const char" *encoding in
 305 Encoding of file to use as startup script, or NULL.
 306 .AP "const char" **encodingPtr out
 307 If non-NULL, location to write a copy of the (const char *)
 308 pointing to the encoding name.
 309 .AP Tcl_MainLoopProc *mainLoopProc in
 310 Address of an application-specific event loop procedure.
 311 .BE
 312 .SH DESCRIPTION
 313 .PP
 314 \fBTcl_Main\fR can serve as the main program for Tcl-based shell
 315 applications.  A
 316 .QW "shell application"
 317 is a program
 318 like tclsh or wish that supports both interactive interpretation
 319 of Tcl and evaluation of a script contained in a file given as
 320 a command line argument.  \fBTcl_Main\fR is offered as a convenience
 321 to developers of shell applications, so they do not have to
 322 reproduce all of the code for proper initialization of the Tcl
 323 library and interactive shell operation.  Other styles of embedding
 324 Tcl in an application are not supported by \fBTcl_Main\fR.  Those
 325 must be achieved by calling lower level functions in the Tcl library
 326 directly.
 327 .PP
 328 The \fBTcl_Main\fR function has been offered by the Tcl library
 329 since release Tcl 7.4.  In older releases of Tcl, the Tcl library
 330 itself defined a function \fBmain\fR, but that lacks flexibility
 331 of embedding style and having a function \fBmain\fR in a library
 332 (particularly a shared library) causes problems on many systems.
 333 Having \fBmain\fR in the Tcl library would also make it hard to use
 334 Tcl in C++ programs, since C++ programs must have special C++
 335 \fBmain\fR functions.
 336 .PP
 337 Normally each shell application contains a small \fBmain\fR function
 338 that does nothing but invoke \fBTcl_Main\fR.
 339 \fBTcl_Main\fR then does all the work of creating and running a
 340 \fBtclsh\fR-like application.
 341 .PP
 342 \fBTcl_Main\fR is not provided by the public interface of Tcl's
 343 stub library.  Programs that call \fBTcl_Main\fR must be linked
 344 against the standard Tcl library.  Extensions (stub-enabled or
 345 not) are not intended to call \fBTcl_Main\fR.
 346 .PP
 347 \fBTcl_Main\fR is not thread-safe.  It should only be called by
 348 a single master thread of a multi-threaded application.  This
 349 restriction is not a problem with normal use described above.
 350 .PP
 351 \fBTcl_Main\fR and therefore all applications based upon it, like
 352 \fBtclsh\fR, use \fBTcl_GetStdChannel\fR to initialize the standard
 353 channels to their default values. See \fBTcl_StandardChannels\fR for
 354 more information.
 355 .PP
 356 \fBTcl_Main\fR supports two modes of operation, depending on
 357 whether the filename and encoding of a startup script has been
 358 established.  The routines \fBTcl_SetStartupScript\fR and
 359 \fBTcl_GetStartupScript\fR are the tools for controlling this
 360 configuration of \fBTcl_Main\fR.
 361 .PP
 362 \fBTcl_SetStartupScript\fR registers the value \fIpath\fR
 363 as the name of the file for \fBTcl_Main\fR to evaluate as
 364 its startup script.  The value \fIencoding\fR is Tcl's name
 365 for the encoding used to store the text in that file.  A
 366 value of \fBNULL\fR for \fIencoding\fR is a signal to use
 367 the system encoding.  A value of \fBNULL\fR for \fIpath\fR
 368 erases any existing registration so that \fBTcl_Main\fR
 369 will not evaluate any startup script.
 370 .PP
 371 \fBTcl_GetStartupScript\fR queries the registered file name
 372 and encoding set by the most recent \fBTcl_SetStartupScript\fR
 373 call in the same thread.  The stored file name is returned,
 374 and the stored encoding name is written to space pointed to
 375 by \fIencodingPtr\fR, when that is not NULL.
 376 .PP
 377 The file name and encoding values managed by the routines
 378 \fBTcl_SetStartupScript\fR and \fBTcl_GetStartupScript\fR
 379 are stored per-thread.  Although the storage and retrieval
 380 functions of these routines work in any thread, only those
 381 calls in the same master thread as \fBTcl_Main\fR can have
 382 any influence on it.
 383 .PP
 384 The caller of \fBTcl_Main\fR may call \fBTcl_SetStartupScript\fR
 385 first to establish its desired startup script.  If \fBTcl_Main\fR
 386 finds that no such startup script has been established, it consults
 387 the first few arguments in \fIargv\fR.  If they match
 388 ?\fB\-encoding \fIname\fR? \fIfileName\fR,
 389 where \fIfileName\fR does not begin with the character \fI\-\fR,
 390 then \fIfileName\fR is taken to be the name of a file containing
 391 a \fIstartup script\fR, and \fIname\fR is taken to be the name
 392 of the encoding of the contents of that file.  \fBTcl_Main\fR
 393 then calls \fBTcl_SetStartupScript\fR with these values.
 394 .PP
 395 \fBTcl_Main\fR then defines in its master interpreter
 396 the Tcl variables \fIargc\fR, \fIargv\fR, \fIargv0\fR, and
 397 \fItcl_interactive\fR, as described in the documentation for \fBtclsh\fR.
 398 .PP
 399 When it has finished its own initialization, but before it processes
 400 commands, \fBTcl_Main\fR calls the procedure given by the
 401 \fIappInitProc\fR argument.  This procedure provides a
 402 .QW hook
 403 for the application to perform its own initialization of the interpreter
 404 created by \fBTcl_Main\fR, such as defining application-specific
 405 commands.  The application initialization routine might also
 406 call \fBTcl_SetStartupScript\fR to (re-)set the file and encoding
 407 to be used as a startup script.  The procedure must have an interface
 408 that matches the type \fBTcl_AppInitProc\fR:
 409 .PP
 410 .CS
 411 typedef int \fBTcl_AppInitProc\fR(
 412         Tcl_Interp *\fIinterp\fR);
 413 .CE
 414 .PP
 415 \fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR; for more
 416 details on this procedure, see the documentation for \fBTcl_AppInit\fR.
 417 .PP
 418 When the \fIappInitProc\fR is finished, \fBTcl_Main\fR calls
 419 \fBTcl_GetStartupScript\fR to determine what startup script has
 420 been requested, if any.  If a startup script has been provided,
 421 \fBTcl_Main\fR attempts to evaluate it.  Otherwise, interactive
 422 mode begins with examination of the variable \fItcl_rcFileName\fR
 423 in the master interpreter.  If that variable exists and holds the
 424 name of a readable file, the contents of that file are evaluated
 425 in the master interpreter.  Then interactive operations begin,
 426 with prompts and command evaluation results written to the standard
 427 output channel, and commands read from the standard input channel
 428 and then evaluated.  The prompts written to the standard output
 429 channel may be customized by defining the Tcl variables \fItcl_prompt1\fR
 430 and \fItcl_prompt2\fR as described in the documentation for \fBtclsh\fR.
 431 The prompts and command evaluation results are written to the standard
 432 output channel only if the Tcl variable \fItcl_interactive\fR in the
 433 master interpreter holds a non-zero integer value.
 434 .PP
 435 \fBTcl_SetMainLoop\fR allows setting an event loop procedure to be run.
 436 This allows, for example, Tk to be dynamically loaded and set its event
 437 loop.  The event loop will run following the startup script.  If you
 438 are in interactive mode, setting the main loop procedure will cause the
 439 prompt to become fileevent based and then the loop procedure is called.
 440 When the loop procedure returns in interactive mode, interactive operation
 441 will continue.
 442 The main loop procedure must have an interface that matches the type
 443 \fBTcl_MainLoopProc\fR:
 444 .PP
 445 .CS
 446 typedef void \fBTcl_MainLoopProc\fR(void);
 447 .CE
 448 .PP
 449 \fBTcl_Main\fR does not return.  Normally a program based on
 450 \fBTcl_Main\fR will terminate when the \fBexit\fR command is
 451 evaluated.  In interactive mode, if an EOF or channel error
 452 is encountered on the standard input channel, then \fBTcl_Main\fR
 453 itself will evaluate the \fBexit\fR command after the main loop
 454 procedure (if any) returns.  In non-interactive mode, after
 455 \fBTcl_Main\fR evaluates the startup script, and the main loop
 456 procedure (if any) returns, \fBTcl_Main\fR will also evaluate
 457 the \fBexit\fR command.
 458 .SH "SEE ALSO"
 459 tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3),
 460 exit(n), encoding(n)
 461 .SH KEYWORDS
 462 application-specific initialization, command-line arguments, main program