man/man3/Tcl_Main.3 - toolchains/skids - Git at Google

 '\"
 '\" Copyright (c) 1994 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
 '\" Copyright (c) 2000 Ajuba Solutions.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
 '\" RCS: @(#) $Id: Tcl_Main.3,v 1.9 2002/07/01 18:24:39 jenglish Exp $
 '\"
 '\" The definitions below are for supplemental macros used in Tcl/Tk
 '\" manual entries.
 '\"
 '\" .AP type name in/out ?indent?
 '\"	Start paragraph describing an argument to a library procedure.
 '\"	type is type of argument (int, etc.), in/out is either "in", "out",
 '\"	or "in/out" to describe whether procedure reads or modifies arg,
 '\"	and indent is equivalent to second arg of .IP (shouldn't ever be
 '\"	needed;  use .AS below instead)
 '\"
 '\" .AS ?type? ?name?
 '\"	Give maximum sizes of arguments for setting tab stops.  Type and
 '\"	name are examples of largest possible arguments that will be passed
 '\"	to .AP later.  If args are omitted, default tab stops are used.
 '\"
 '\" .BS
 '\"	Start box enclosure.  From here until next .BE, everything will be
 '\"	enclosed in one large box.
 '\"
 '\" .BE
 '\"	End of box enclosure.
 '\"
 '\" .CS
 '\"	Begin code excerpt.
 '\"
 '\" .CE
 '\"	End code excerpt.
 '\"
 '\" .VS ?version? ?br?
 '\"	Begin vertical sidebar, for use in marking newly-changed parts
 '\"	of man pages.  The first argument is ignored and used for recording
 '\"	the version when the .VS was added, so that the sidebars can be
 '\"	found and removed when they reach a certain age.  If another argument
 '\"	is present, then a line break is forced before starting the sidebar.
 '\"
 '\" .VE
 '\"	End of vertical sidebar.
 '\"
 '\" .DS
 '\"	Begin an indented unfilled display.
 '\"
 '\" .DE
 '\"	End of indented unfilled display.
 '\"
 '\" .SO
 '\"	Start of list of standard options for a Tk widget.  The
 '\"	options follow on successive lines, in four columns separated
 '\"	by tabs.
 '\"
 '\" .SE
 '\"	End of list of standard options for a Tk widget.
 '\"
 '\" .OP cmdName dbName dbClass
 '\"	Start of description of a specific option.  cmdName gives the
 '\"	option's name as specified in the class command, dbName gives
 '\"	the option's name in the option database, and dbClass gives
 '\"	the option's class in the option database.
 '\"
 '\" .UL arg1 arg2
 '\"	Print arg1 underlined, then print arg2 normally.
 '\"
 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
 '\"
 '\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
 .if t .wh -1.3i ^B
 .nr ^l \n(.l
 .ad b
 '\"	# Start an argument description
 .de AP
 .ie !"\\$4"" .TP \\$4
 .el \{\
 .   ie !"\\$2"" .TP \\n()Cu
 .   el          .TP 15
 .\}
 .ta \\n()Au \\n()Bu
 .ie !"\\$3"" \{\
 \&\\$1	\\fI\\$2\\fP	(\\$3)
 .\".b
 .\}
 .el \{\
 .br
 .ie !"\\$2"" \{\
 \&\\$1	\\fI\\$2\\fP
 .\}
 .el \{\
 \&\\fI\\$1\\fP
 .\}
 .\}
 ..
 '\"	# define tabbing values for .AP
 .de AS
 .nr )A 10n
 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 .nr )B \\n()Au+15n
 .\"
 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 ..
 .AS Tcl_Interp Tcl_CreateInterp in/out
 '\"	# BS - start boxed text
 '\"	# ^y = starting y location
 '\"	# ^b = 1
 .de BS
 .br
 .mk ^y
 .nr ^b 1u
 .if n .nf
 .if n .ti 0
 .if n \l'\\n(.lu\(ul'
 .if n .fi
 ..
 '\"	# BE - end boxed text (draw box now)
 .de BE
 .nf
 .ti 0
 .mk ^t
 .ie n \l'\\n(^lu\(ul'
 .el \{\
 .\"	Draw four-sided box normally, but don't draw top of
 .\"	box if the box started on an earlier page.
 .ie !\\n(^b-1 \{\
 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 .\}
 .el \}\
 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 .\}
 .\}
 .fi
 .br
 .nr ^b 0
 ..
 '\"	# VS - start vertical sidebar
 '\"	# ^Y = starting y location
 '\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
 .de VS
 .if !"\\$2"" .br
 .mk ^Y
 .ie n 'mc \s12\(br\s0
 .el .nr ^v 1u
 ..
 '\"	# VE - end of vertical sidebar
 .de VE
 .ie n 'mc
 .el \{\
 .ev 2
 .nf
 .ti 0
 .mk ^t
 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 .sp -1
 .fi
 .ev
 .\}
 .nr ^v 0
 ..
 '\"	# Special macro to handle page bottom:  finish off current
 '\"	# box/sidebar if in box/sidebar mode, then invoked standard
 '\"	# page bottom macro.
 .de ^B
 .ev 2
 'ti 0
 'nf
 .mk ^t
 .if \\n(^b \{\
 .\"	Draw three-sided box if this is the box's first page,
 .\"	draw two sides but no top otherwise.
 .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
 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 .\}
 .if \\n(^v \{\
 .nr ^x \\n(^tu+1v-\\n(^Yu
 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 .\}
 .bp
 'fi
 .ev
 .if \\n(^b \{\
 .mk ^y
 .nr ^b 2
 .\}
 .if \\n(^v \{\
 .mk ^Y
 .\}
 ..
 '\"	# DS - begin display
 .de DS
 .RS
 .nf
 .sp
 ..
 '\"	# DE - end display
 .de DE
 .fi
 .RE
 .sp
 ..
 '\"	# SO - start of list of standard options
 .de SO
 .SH "STANDARD OPTIONS"
 .LP
 .nf
 .ta 5.5c 11c
 .ft B
 ..
 '\"	# SE - end of list of standard options
 .de SE
 .fi
 .ft R
 .LP
 See the \\fBoptions\\fR manual entry for details on the standard options.
 ..
 '\"	# OP - start of full description for a single option
 .de OP
 .LP
 .nf
 .ta 4c
 Command-Line Name:	\\fB\\$1\\fR
 Database Name:	\\fB\\$2\\fR
 Database Class:	\\fB\\$3\\fR
 .fi
 .IP
 ..
 '\"	# CS - begin code excerpt
 .de CS
 .RS
 .nf
 .ta .25i .5i .75i 1i
 ..
 '\"	# CE - end code excerpt
 .de CE
 .fi
 .RE
 ..
 .de UL
 \\$1\l'|0\(ul'\\$2
 ..
 .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
 Tcl_Main, Tcl_SetMainLoop \- main program and event loop definition for Tcl-based applications
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
 \fBTcl_Main\fR(\fIargc, argv, appInitProc\fR)
 .sp
 \fBTcl_SetMainLoop\fR(\fImainLoopProc\fR)
 .SH ARGUMENTS
 .AS Tcl_AppInitProc *appInitProc
 .AP int argc in
 Number of elements in \fIargv\fR.
 .AP char *argv[] in
 Array of strings containing command-line arguments.
 .AP Tcl_AppInitProc *appInitProc in
 Address of an application-specific initialization procedure.
 The value for this argument is usually \fBTcl_AppInit\fR.
 .AP Tcl_MainLoopProc *mainLoopProc in
 Address of an application-specific event loop procedure.
 .BE

 .SH DESCRIPTION
 .PP
 \fBTcl_Main\fR can serve as the main program for Tcl-based shell
 applications.  A ``shell application'' is a program
 like tclsh or wish that supports both interactive interpretation
 of Tcl and evaluation of a script contained in a file given as
 a command line argument.  \fBTcl_Main\fR is offered as a convenience
 to developers of shell applications, so they do not have to
 reproduce all of the code for proper initialization of the Tcl
 library and interactive shell operation.  Other styles of embedding
 Tcl in an application are not supported by \fBTcl_Main\fR.  Those
 must be achieved by calling lower level functions in the Tcl library
 directly.

 The \fBTcl_Main\fR function has been offered by the Tcl library
 since release Tcl 7.4.  In older releases of Tcl, the Tcl library
 itself defined a function \fBmain\fR, but that lacks flexibility
 of embedding style and having a function \fBmain\fR in a library
 (particularly a shared library) causes problems on many systems.
 Having \fBmain\fR in the Tcl library would also make it hard to use
 Tcl in C++ programs, since C++ programs must have special C++
 \fBmain\fR functions.
 .PP
 Normally each shell application contains a small \fBmain\fR function
 that does nothing but invoke \fBTcl_Main\fR.
 \fBTcl_Main\fR then does all the work of creating and running a
 \fBtclsh\fR-like application.
 .PP
 \fBTcl_Main\fR is not provided by the public interface of Tcl's
 stub library.  Programs that call \fBTcl_Main\fR must be linked
 against the standard Tcl library.  Extensions (stub-enabled or
 not) are not intended to call \fBTcl_Main\fR.
 .PP
 \fBTcl_Main\fR is not thread-safe.  It should only be called by
 a single master thread of a multi-threaded application.  This
 restriction is not a problem with normal use described above.
 .PP
 \fBTcl_Main\fR and therefore all applications based upon it, like
 \fBtclsh\fR, use \fBTcl_GetStdChannel\fR to initialize the standard
 channels to their default values. See \fBTcl_StandardChannels\fR for
 more information.
 .PP
 \fBTcl_Main\fR supports two modes of operation, depending on the
 values of \fIargc\fR and \fIargv\fR.  If \fIargv[1]\fR exists and
 does not begin with the character \fI-\fR, it is taken to be the
 name of a file containing a \fIstartup script\fR, which \fBTcl_Main\fR
 will attempt to evaluate.  Otherwise, \fBTcl_Main\fR will enter an
 interactive mode.
 .PP
 In either mode, \fBTcl_Main\fR will define in its master interpreter
 the Tcl variables \fIargc\fR, \fIargv\fR, \fIargv0\fR, and
 \fItcl_interactive\fR, as described in the documentation for \fBtclsh\fR.
 .PP
 When it has finished its own initialization, but before it processes
 commands, \fBTcl_Main\fR calls the procedure given by the
 \fIappInitProc\fR argument.  This procedure provides a ``hook'' for
 the application to perform its own initialization of the interpreter
 created by \fBTcl_Main\fR, such as defining application-specific
 commands.  The procedure must have an interface that matches the
 type \fBTcl_AppInitProc\fR:
 .CS
 typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR);
 .CE

 \fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR; for more
 details on this procedure, see the documentation for \fBTcl_AppInit\fR.
 .PP
 When the \fIappInitProc\fR is finished, \fBTcl_Main\fR enters one
 of its two modes.  If a startup script has been provided, \fBTcl_Main\fR
 attempts to evaluate it.  Otherwise, interactive mode begins with
 examination of the variable \fItcl_rcFileName\fR in the master
 interpreter.  If that variable exists and holds the name of a readable
 file, the contents of that file are evaluated in the master interpreter.
 Then interactive operations begin,
 with prompts and command evaluation results written to the standard
 output channel, and commands read from the standard input channel
 and then evaluated.  The prompts written to the standard output
 channel may be customized by defining the Tcl variables \fItcl_prompt1\fR
 and \fItcl_prompt2\fR as described in the documentation for \fBtclsh\fR.
 The prompts and command evaluation results are written to the standard
 output channel only if the Tcl variable \fItcl_interactive\fR in the
 master interpreter holds a non-zero integer value.
 .PP
 .VS 8.4
 \fBTcl_SetMainLoop\fR allows setting an event loop procedure to be run.
 This allows, for example, Tk to be dynamically loaded and set its event
 loop.  The event loop will run following the startup script.  If you
 are in interactive mode, setting the main loop procedure will cause the
 prompt to become fileevent based and then the loop procedure is called.
 When the loop procedure returns in interactive mode, interactive operation
 will continue.
 The main loop procedure must have an interface that matches the type
 \fBTcl_MainLoopProc\fR:
 .CS
 typedef void Tcl_MainLoopProc(void);
 .CE
 .VE 8.4
 .PP
 \fBTcl_Main\fR does not return.  Normally a program based on
 \fBTcl_Main\fR will terminate when the \fBexit\fR command is
 evaluated.  In interactive mode, if an EOF or channel error
 is encountered on the standard input channel, then \fBTcl_Main\fR
 itself will evaluate the \fBexit\fR command after the main loop
 procedure (if any) returns.  In non-interactive mode, after
 \fBTcl_Main\fR evaluates the startup script, and the main loop
 procedure (if any) returns, \fBTcl_Main\fR will also evaluate
 the \fBexit\fR command.

 .SH "SEE ALSO"
 tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3),
 exit(n)

 .SH KEYWORDS
 application-specific initialization, command-line arguments, main program
	'\"
	'\" Copyright (c) 1994 The Regents of the University of California.
	'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
	'\" Copyright (c) 2000 Ajuba Solutions.
	'\"
	'\" See the file "license.terms" for information on usage and redistribution
	'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
	'\"
	'\" RCS: @(#) $Id: Tcl_Main.3,v 1.9 2002/07/01 18:24:39 jenglish Exp $
	'\"
	'\" The definitions below are for supplemental macros used in Tcl/Tk
	'\" manual entries.
	'\"
	'\" .AP type name in/out ?indent?
	'\" Start paragraph describing an argument to a library procedure.
	'\" type is type of argument (int, etc.), in/out is either "in", "out",
	'\" or "in/out" to describe whether procedure reads or modifies arg,
	'\" and indent is equivalent to second arg of .IP (shouldn't ever be
	'\" needed; use .AS below instead)
	'\"
	'\" .AS ?type? ?name?
	'\" Give maximum sizes of arguments for setting tab stops. Type and
	'\" name are examples of largest possible arguments that will be passed
	'\" to .AP later. If args are omitted, default tab stops are used.
	'\"
	'\" .BS
	'\" Start box enclosure. From here until next .BE, everything will be
	'\" enclosed in one large box.
	'\"
	'\" .BE
	'\" End of box enclosure.
	'\"
	'\" .CS
	'\" Begin code excerpt.
	'\"
	'\" .CE
	'\" End code excerpt.
	'\"
	'\" .VS ?version? ?br?
	'\" Begin vertical sidebar, for use in marking newly-changed parts
	'\" of man pages. The first argument is ignored and used for recording
	'\" the version when the .VS was added, so that the sidebars can be
	'\" found and removed when they reach a certain age. If another argument
	'\" is present, then a line break is forced before starting the sidebar.
	'\"
	'\" .VE
	'\" End of vertical sidebar.
	'\"
	'\" .DS
	'\" Begin an indented unfilled display.
	'\"
	'\" .DE
	'\" End of indented unfilled display.
	'\"
	'\" .SO
	'\" Start of list of standard options for a Tk widget. The
	'\" options follow on successive lines, in four columns separated
	'\" by tabs.
	'\"
	'\" .SE
	'\" End of list of standard options for a Tk widget.
	'\"
	'\" .OP cmdName dbName dbClass
	'\" Start of description of a specific option. cmdName gives the
	'\" option's name as specified in the class command, dbName gives
	'\" the option's name in the option database, and dbClass gives
	'\" the option's class in the option database.
	'\"
	'\" .UL arg1 arg2
	'\" Print arg1 underlined, then print arg2 normally.
	'\"
	'\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
	'\"
	'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
	.if t .wh -1.3i ^B
	.nr ^l \n(.l
	.ad b
	'\" # Start an argument description
	.de AP
	.ie !"\\$4"" .TP \\$4
	.el \{\
	. ie !"\\$2"" .TP \\n()Cu
	. el .TP 15
	.\}
	.ta \\n()Au \\n()Bu
	.ie !"\\$3"" \{\
	\&\\$1 \\fI\\$2\\fP (\\$3)
	.\".b
	.\}
	.el \{\
	.br
	.ie !"\\$2"" \{\
	\&\\$1 \\fI\\$2\\fP
	.\}
	.el \{\
	\&\\fI\\$1\\fP
	.\}
	.\}
	..
	'\" # define tabbing values for .AP
	.de AS
	.nr )A 10n
	.if !"\\$1"" .nr )A \\w'\\$1'u+3n
	.nr )B \\n()Au+15n
	.\"
	.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
	.nr )C \\n()Bu+\\w'(in/out)'u+2n
	..
	.AS Tcl_Interp Tcl_CreateInterp in/out
	'\" # BS - start boxed text
	'\" # ^y = starting y location
	'\" # ^b = 1
	.de BS
	.br
	.mk ^y
	.nr ^b 1u
	.if n .nf
	.if n .ti 0
	.if n \l'\\n(.lu\(ul'
	.if n .fi
	..
	'\" # BE - end boxed text (draw box now)
	.de BE
	.nf
	.ti 0
	.mk ^t
	.ie n \l'\\n(^lu\(ul'
	.el \{\
	.\" Draw four-sided box normally, but don't draw top of
	.\" box if the box started on an earlier page.
	.ie !\\n(^b-1 \{\
	\h'-1.5n'\L'\|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'\|0u-1.5n\(ul'
	.\}
	.el \}\
	\h'-1.5n'\L'\|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'\|0u-1.5n\(ul'
	.\}
	.\}
	.fi
	.br
	.nr ^b 0
	..
	'\" # VS - start vertical sidebar
	'\" # ^Y = starting y location
	'\" # ^v = 1 (for troff; for nroff this doesn't matter)
	.de VS
	.if !"\\$2"" .br
	.mk ^Y
	.ie n 'mc \s12\(br\s0
	.el .nr ^v 1u
	..
	'\" # VE - end of vertical sidebar
	.de VE
	.ie n 'mc
	.el \{\
	.ev 2
	.nf
	.ti 0
	.mk ^t
	\h'\|\\n(^lu+3n'\L'\|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-\|\\n(^lu+3n'
	.sp -1
	.fi
	.ev
	.\}
	.nr ^v 0
	..
	'\" # Special macro to handle page bottom: finish off current
	'\" # box/sidebar if in box/sidebar mode, then invoked standard
	'\" # page bottom macro.
	.de ^B
	.ev 2
	'ti 0
	'nf
	.mk ^t
	.if \\n(^b \{\
	.\" Draw three-sided box if this is the box's first page,
	.\" draw two sides but no top otherwise.
	.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
	.el \h'-1.5n'\L'\|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'\|0u'\c
	.\}
	.if \\n(^v \{\
	.nr ^x \\n(^tu+1v-\\n(^Yu
	\kx\h'-\\nxu'\h'\|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'\|0u'\c
	.\}
	.bp
	'fi
	.ev
	.if \\n(^b \{\
	.mk ^y
	.nr ^b 2
	.\}
	.if \\n(^v \{\
	.mk ^Y
	.\}
	..
	'\" # DS - begin display
	.de DS
	.RS
	.nf
	.sp
	..
	'\" # DE - end display
	.de DE
	.fi
	.RE
	.sp
	..
	'\" # SO - start of list of standard options
	.de SO
	.SH "STANDARD OPTIONS"
	.LP
	.nf
	.ta 5.5c 11c
	.ft B
	..
	'\" # SE - end of list of standard options
	.de SE
	.fi
	.ft R
	.LP
	See the \\fBoptions\\fR manual entry for details on the standard options.
	..
	'\" # OP - start of full description for a single option
	.de OP
	.LP
	.nf
	.ta 4c
	Command-Line Name: \\fB\\$1\\fR
	Database Name: \\fB\\$2\\fR
	Database Class: \\fB\\$3\\fR
	.fi
	.IP
	..
	'\" # CS - begin code excerpt
	.de CS
	.RS
	.nf
	.ta .25i .5i .75i 1i
	..
	'\" # CE - end code excerpt
	.de CE
	.fi
	.RE
	..
	.de UL
	\\$1\l'\|0\(ul'\\$2
	..
	.TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures"
	.BS
	.SH NAME
	Tcl_Main, Tcl_SetMainLoop \- main program and event loop definition for Tcl-based applications
	.SH SYNOPSIS
	.nf
	\fB#include <tcl.h>\fR
	.sp
	\fBTcl_Main\fR(\fIargc, argv, appInitProc\fR)
	.sp
	\fBTcl_SetMainLoop\fR(\fImainLoopProc\fR)
	.SH ARGUMENTS
	.AS Tcl_AppInitProc *appInitProc
	.AP int argc in
	Number of elements in \fIargv\fR.
	.AP char *argv[] in
	Array of strings containing command-line arguments.
	.AP Tcl_AppInitProc *appInitProc in
	Address of an application-specific initialization procedure.
	The value for this argument is usually \fBTcl_AppInit\fR.
	.AP Tcl_MainLoopProc *mainLoopProc in
	Address of an application-specific event loop procedure.
	.BE

	.SH DESCRIPTION
	.PP
	\fBTcl_Main\fR can serve as the main program for Tcl-based shell
	applications. A ``shell application'' is a program
	like tclsh or wish that supports both interactive interpretation
	of Tcl and evaluation of a script contained in a file given as
	a command line argument. \fBTcl_Main\fR is offered as a convenience
	to developers of shell applications, so they do not have to
	reproduce all of the code for proper initialization of the Tcl
	library and interactive shell operation. Other styles of embedding
	Tcl in an application are not supported by \fBTcl_Main\fR. Those
	must be achieved by calling lower level functions in the Tcl library
	directly.

	The \fBTcl_Main\fR function has been offered by the Tcl library
	since release Tcl 7.4. In older releases of Tcl, the Tcl library
	itself defined a function \fBmain\fR, but that lacks flexibility
	of embedding style and having a function \fBmain\fR in a library
	(particularly a shared library) causes problems on many systems.
	Having \fBmain\fR in the Tcl library would also make it hard to use
	Tcl in C++ programs, since C++ programs must have special C++
	\fBmain\fR functions.
	.PP
	Normally each shell application contains a small \fBmain\fR function
	that does nothing but invoke \fBTcl_Main\fR.
	\fBTcl_Main\fR then does all the work of creating and running a
	\fBtclsh\fR-like application.
	.PP
	\fBTcl_Main\fR is not provided by the public interface of Tcl's
	stub library. Programs that call \fBTcl_Main\fR must be linked
	against the standard Tcl library. Extensions (stub-enabled or
	not) are not intended to call \fBTcl_Main\fR.
	.PP
	\fBTcl_Main\fR is not thread-safe. It should only be called by
	a single master thread of a multi-threaded application. This
	restriction is not a problem with normal use described above.
	.PP
	\fBTcl_Main\fR and therefore all applications based upon it, like
	\fBtclsh\fR, use \fBTcl_GetStdChannel\fR to initialize the standard
	channels to their default values. See \fBTcl_StandardChannels\fR for
	more information.
	.PP
	\fBTcl_Main\fR supports two modes of operation, depending on the
	values of \fIargc\fR and \fIargv\fR. If \fIargv[1]\fR exists and
	does not begin with the character \fI-\fR, it is taken to be the
	name of a file containing a \fIstartup script\fR, which \fBTcl_Main\fR
	will attempt to evaluate. Otherwise, \fBTcl_Main\fR will enter an
	interactive mode.
	.PP
	In either mode, \fBTcl_Main\fR will define in its master interpreter
	the Tcl variables \fIargc\fR, \fIargv\fR, \fIargv0\fR, and
	\fItcl_interactive\fR, as described in the documentation for \fBtclsh\fR.
	.PP
	When it has finished its own initialization, but before it processes
	commands, \fBTcl_Main\fR calls the procedure given by the
	\fIappInitProc\fR argument. This procedure provides a ``hook'' for
	the application to perform its own initialization of the interpreter
	created by \fBTcl_Main\fR, such as defining application-specific
	commands. The procedure must have an interface that matches the
	type \fBTcl_AppInitProc\fR:
	.CS
	typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR);
	.CE

	\fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR; for more
	details on this procedure, see the documentation for \fBTcl_AppInit\fR.
	.PP
	When the \fIappInitProc\fR is finished, \fBTcl_Main\fR enters one
	of its two modes. If a startup script has been provided, \fBTcl_Main\fR
	attempts to evaluate it. Otherwise, interactive mode begins with
	examination of the variable \fItcl_rcFileName\fR in the master
	interpreter. If that variable exists and holds the name of a readable
	file, the contents of that file are evaluated in the master interpreter.
	Then interactive operations begin,
	with prompts and command evaluation results written to the standard
	output channel, and commands read from the standard input channel
	and then evaluated. The prompts written to the standard output
	channel may be customized by defining the Tcl variables \fItcl_prompt1\fR
	and \fItcl_prompt2\fR as described in the documentation for \fBtclsh\fR.
	The prompts and command evaluation results are written to the standard
	output channel only if the Tcl variable \fItcl_interactive\fR in the
	master interpreter holds a non-zero integer value.
	.PP
	.VS 8.4
	\fBTcl_SetMainLoop\fR allows setting an event loop procedure to be run.
	This allows, for example, Tk to be dynamically loaded and set its event
	loop. The event loop will run following the startup script. If you
	are in interactive mode, setting the main loop procedure will cause the
	prompt to become fileevent based and then the loop procedure is called.
	When the loop procedure returns in interactive mode, interactive operation
	will continue.
	The main loop procedure must have an interface that matches the type
	\fBTcl_MainLoopProc\fR:
	.CS
	typedef void Tcl_MainLoopProc(void);
	.CE
	.VE 8.4
	.PP
	\fBTcl_Main\fR does not return. Normally a program based on
	\fBTcl_Main\fR will terminate when the \fBexit\fR command is
	evaluated. In interactive mode, if an EOF or channel error
	is encountered on the standard input channel, then \fBTcl_Main\fR
	itself will evaluate the \fBexit\fR command after the main loop
	procedure (if any) returns. In non-interactive mode, after
	\fBTcl_Main\fR evaluates the startup script, and the main loop
	procedure (if any) returns, \fBTcl_Main\fR will also evaluate
	the \fBexit\fR command.

	.SH "SEE ALSO"
	tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3),
	exit(n)

	.SH KEYWORDS
	application-specific initialization, command-line arguments, main program