Seth Woolley's Man Viewer

Tcl_Main(3) - Tcl_Main, Tcl_SetMainLoop, Tcl_Main, Tcl_SetMainLoop - main program and event loop definition for Tcl-based applications - man 3 Tcl_Main

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

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
       Number of elements in(1,8) argv.  Array of strings  containing  command-line
       arguments.   Address  of  an application-specific initialization proce-
       dure.  The value for this argument is usually Tcl_AppInit.  Address  of
       an application-specific event loop procedure.


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(1,8) a file(1,n) 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(1,8) an application are not supported by  Tcl_Main.   Those
       must  be  achieved  by calling lower level functions in(1,8) 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(1,8)  a library (particularly a shared library) causes
       problems on many systems.  Having main in(1,8) the Tcl  library  would  also
       make  it  hard to use Tcl in(1,8) 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(5,8) 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(1,n) 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(1,8) its master(5,8) interpreter the Tcl
       variables argc, argv, argv0, and tcl_interactive, as described  in(1,8)  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(1,8) the master(5,8) interpreter.  If that variable exists
       and holds the name of a readable file(1,n), the contents of  that  file(1,n)  are
       evaluated  in(1,8)  the  master(5,8)  interpreter.   Then  interactive operations
       begin, with prompts and command evaluation results written to the stan-
       dard  output channel, and commands read(2,n,1 builtins) 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(1,8) the documentation for tclsh.   The  prompts
       and command evaluation results are written to the standard output chan-
       nel only if(3,n) the Tcl variable tcl_interactive in(1,8) the master(5,8)  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(7,n,1 builtins)  its  event
       loop.   The  event  loop will run following the startup script.  If you
       are in(1,8) 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(1,8) interactive mode, interactive opera-
       tion  will  continue.   The  main loop procedure must have an interface
       that matches the  type  Tcl_MainLoopProc:  typedef  void  Tcl_MainLoop-
       Proc(void);

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


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


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



Tcl                                   8.4                          Tcl_Main(3)

References for this manual (incoming links)