Tcl_Main(3)           Tcl Library Procedures          Tcl_Main(3)



_________________________________________________________________

NAME
       Tcl_Main,  Tcl_SetMainLoop  -  main program and event loop
       definition for Tcl-based applications

SYNOPSIS
       #include 

       Tcl_Main(argc, argv, appInitProc)

       Tcl_SetMainLoop(mainLoopProc)

ARGUMENTS
       int               argc           (in)      Number of  ele-
                                                  ments  in argv.

       char              *argv[]        (in)      Array        of
                                                  strings    con-
                                                  taining    com-
                                                  mand-line argu-
                                                  ments.

       Tcl_AppInitProc   *appInitProc   (in)      Address  of  an
                                                  application-
                                                  specific   ini-
                                                  tialization
                                                  procedure.  The
                                                  value  for this
                                                  argument     is
                                                  usually
                                                  Tcl_AppInit.

       Tcl_MainLoopProc  *mainLoopProc  (in)      Address  of  an
                                                  application-
                                                  specific  event
                                                  loop procedure.
_________________________________________________________________


DESCRIPTION
       Tcl_Main 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  interpreta-
       tion of Tcl and evaluation of a script contained in a file
       given as a command line argument.  Tcl_Main is offered  as
       a convenience to developers of shell applications, so they
       do not have to reproduce all of the code for  proper  ini-
       tialization of the Tcl library and interactive shell oper-
       ation.  Other styles of embedding Tcl  in  an  application
       are  not supported by Tcl_Main.  Those must be achieved by
       calling lower level functions in the Tcl library directly.

       The  Tcl_Main 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 main, but that lacks
       flexibility of embedding style and having a function  main
       in  a library (particularly a shared library) causes prob-
       lems on many systems.  Having  main  in  the  Tcl  library
       would  also make it hard to use Tcl in C++ programs, since
       C++ programs must have special C++ main functions.

       Normally each shell  application  contains  a  small  main
       function  that does nothing but invoke Tcl_Main.  Tcl_Main
       then does all the work of creating and  running  a  tclsh-
       like application.

       Tcl_Main  is not provided by the public interface of Tcl's
       stub library.  Programs that call Tcl_Main must be  linked
       against  the  standard  Tcl  library.   Extensions  (stub-
       enabled or not) are not intended to call Tcl_Main.

       Tcl_Main 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.

       Tcl_Main  and  therefore  all  applications based upon it,
       like tclsh, use Tcl_GetStdChannel to initialize the  stan-
       dard  channels  to their default values. See Tcl_Standard-
       Channels for more information.

       Tcl_Main supports two modes of operation, depending on the
       values  of  argc and argv.  If argv[1] exists and does not
       begin with the character -, it is taken to be the name  of
       a  file  containing  a startup script, which Tcl_Main will
       attempt to evaluate.  Otherwise, Tcl_Main  will  enter  an
       interactive mode.

       In  either mode, Tcl_Main will define in its master inter-
       preter the Tcl variables argc, argv, argv0, and tcl_inter-
       active, as described in the documentation for tclsh.

       When it has finished its own initialization, but before it
       processes commands, Tcl_Main calls the procedure given  by
       the  appInitProc  argument.   This  procedure  provides  a
       ``hook'' for the application to perform its  own  initial-
       ization  of  the  interpreter created by Tcl_Main, such as
       defining  application-specific  commands.   The  procedure
       must  have an interface that matches the type Tcl_AppInit-
       Proc:
              typedef int Tcl_AppInitProc(Tcl_Interp *interp);

       AppInitProc is almost always a pointer to Tcl_AppInit; for
       more  details on this procedure, see the documentation for
       Tcl_AppInit.

       When the appInitProc is finished, Tcl_Main enters  one  of
       its  two  modes.   If  a startup script has been provided,
       Tcl_Main attempts to evaluate it.  Otherwise,  interactive
       mode  begins  with examination of the variable tcl_rcFile-
       Name 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
       tcl_prompt1 and tcl_prompt2 as described in the documenta-
       tion  for  tclsh.   The  prompts  and  command  evaluation
       results are written to the standard output channel only if
       the Tcl variable tcl_interactive in the master interpreter
       holds a non-zero integer value.

       Tcl_SetMainLoop 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 proce- |
       dure is called.  When the loop procedure returns in inter- |
       active  mode,  interactive  operation  will continue.  The |
       main loop procedure must have an  interface  that  matches |
       the type Tcl_MainLoopProc:                                 |
              typedef void Tcl_MainLoopProc(void);                |

       Tcl_Main  does  not  return.   Normally a program based on
       Tcl_Main will terminate when the exit  command  is  evalu-
       ated.   In interactive mode, if an EOF or channel error is
       encountered on the standard input channel,  then  Tcl_Main
       itself  will evaluate the exit command after the main loop
       procedure (if  any)  returns.   In  non-interactive  mode,
       after  Tcl_Main evaluates the startup script, and the main
       loop procedure (if any) returns, Tcl_Main will also evalu-
       ate the exit command.


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


KEYWORDS
       application-specific  initialization,  command-line  argu-
       ments, main program



Tcl                            8.4                    Tcl_Main(3)