DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_Main(3tcl)




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

     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
                                                  command-line
                                                  arguments.

     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 interpretation 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 initialization  of  the
     Tcl  library  and interactive shell operation.  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.

Tcl                     Last change: 8.4                        1

Tcl_Main(3)          Tcl Library Procedures           Tcl_Main(3)

     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 flex-
     ibility  of  embedding style and having a function main in a
     library (particularly a shared library) causes  problems  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  func-
     tion  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 standard
     channels to their default values.  See  Tcl_StandardChannels
     for more information.

     Tcl_Main supports two modes of operation, depending  on  the
     values of argc and argv.  If the first few arguments in argv
     match ?-encoding name? fileName,  where  fileName  does  not
     begin with the character -, then fileName is taken to be the
     name of a file containing a  startup  script,  and  name  is
     taken to be the name of the encoding of the contents of that
     file, 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_interactive,  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 initialization of the
     interpreter  created   by   Tcl_Main,   such   as   defining
     application-specific  commands.   The procedure must have an
     interface that matches the type Tcl_AppInitProc:
          typedef int Tcl_AppInitProc(Tcl_Interp *interp);

Tcl                     Last change: 8.4                        2

Tcl_Main(3)          Tcl Library Procedures           Tcl_Main(3)

     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_rcFileName in the mas-
     ter 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 documentation for tclsh.  The  prompts  and
     command  evaluation results are written to the standard out-
     put 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 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 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 evaluated.
     In interactive mode, if an EOF or channel error  is  encoun-
     tered  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 evaluate the exit com-
     mand.


SEE ALSO

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


KEYWORDS

     application-specific initialization, command-line arguments,
     main program

Tcl                     Last change: 8.4                        3


Man(1) output converted with man2html