Manual Pages for UNIX Operating System command usage for man Tcl_Main

Tcl Library Procedures                             Tcl_Main(3TCL)



_________________________________________________________________

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

     Tcl_AppInitProc   *appInitProc   (in)      Address   of   an
                                                application-
                                                specific initial-
                                                ization      pro-
                                                cedure.       The
                                                value   for  this
                                                argument is  usu-
                                                ally 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  con-
     venience 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



Tcl                     Last change: 8.4                        1






Tcl Library Procedures                             Tcl_Main(3TCL)



     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 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_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 initializa-
     tion of the interpreter created by Tcl_Main, such as  defin-
     ing  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.



Tcl                     Last change: 8.4                        2






Tcl Library Procedures                             Tcl_Main(3TCL)



     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(3TCL),
     Tcl_StandardChannels(3TCL), Tcl_AppInit(3TCL), exit(1T)


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

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:




Tcl                     Last change: 8.4                        3






Tcl Library Procedures                             Tcl_Main(3TCL)



     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tcl is available on http://opensolaris.org.













































Tcl                     Last change: 8.4                        4