DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

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 elements in  argv.

       char              *argv[]        (in)      Array  of strings containing
                                                  command-line arguments.

       Tcl_AppInitProc   *appInitProc   (in)      Address of  an  application-
                                                  specific initialization pro-
                                                  cedure.  The value for  this
                                                  argument      is     usually
                                                  Tcl_AppInit.

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


DESCRIPTION

       Tcl_Main can serve as the main program  for  Tcl-based  shell  applica-
       tions.   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.

       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
       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 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 mas-
       ter  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 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 interpreter 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 argu-
       ment.  This procedure provides a ``hook'' for the application  to  per-
       form  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);

       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  vari-
       able tcl_rcFileName 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 stan-
       dard  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 output chan-
       nel 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 opera- |
       tion  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 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 evaluate the exit command.


SEE ALSO

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


KEYWORDS

       application-specific  initialization, command-line arguments, main pro-
       gram

Tcl                                   8.4                          Tcl_Main(3)

Man(1) output converted with man2html