Manual Pages for UNIX Operating System command usage for man Tcl_CreateExitHandler

Tcl Library Procedures                             Tcl_Exit(3TCL)



_________________________________________________________________

NAME
     Tcl_Exit,        Tcl_Finalize,        Tcl_CreateExitHandler,
     Tcl_DeleteExitHandler,  Tcl_ExitThread,  Tcl_FinalizeThread,
     Tcl_CreateThreadExitHandler,  Tcl_DeleteThreadExitHandler  -
     end the application or thread (and invoke exit handlers)

SYNOPSIS
     #include 

     Tcl_Exit(status)

     Tcl_Finalize()

     Tcl_CreateExitHandler(proc, clientData)

     Tcl_DeleteExitHandler(proc, clientData)

     Tcl_ExitThread(status)

     Tcl_FinalizeThread()

     Tcl_CreateThreadExitHandler(proc, clientData)

     Tcl_DeleteThreadExitHandler(proc, clientData)

ARGUMENTS
     int            status       (in)      Provides   information
                                           about why the applica-
                                           tion or thread exited.
                                           Exact  meaning  may be
                                           platform-specific.   0
                                           usually means a normal
                                           exit,   any    nonzero
                                           value   usually  means
                                           that     an      error
                                           occurred.

     Tcl_ExitProc   *proc        (in)      Procedure  to   invoke
                                           before  exiting appli-
                                           cation.

     ClientData     clientData   (in)      Arbitrary     one-word
                                           value to pass to proc.
_________________________________________________________________


DESCRIPTION
     The procedures described here provide a  graceful  mechanism
     to end the execution of a Tcl application. Exit handlers are
     invoked to cleanup the application's state before ending the



Tcl                     Last change: 8.1                        1






Tcl Library Procedures                             Tcl_Exit(3TCL)



     execution of Tcl code.

     Invoke Tcl_Exit to end a Tcl application and  to  exit  from
     this process. This procedure is invoked by the exit command,
     and can be invoked anyplace else to terminate  the  applica-
     tion.   No-one  should ever invoke the exit system procedure
     directly;  always invoke Tcl_Exit instead, so  that  it  can
     invoke  exit handlers.  Note that if other code invokes exit
     system procedure directly, or otherwise causes the  applica-
     tion   to  terminate  without  calling  Tcl_Exit,  the  exit
     handlers will not be run.  Tcl_Exit internally  invokes  the
     exit  system  call,  thus  it  never  returns control to its
     caller.

     Tcl_Finalize is similar to Tcl_Exit except that it does  not
     exit from the current process.  It is useful for cleaning up
     when a process is finished using Tcl but wishes to  continue
     executing,  and  when  Tcl  is  used in a dynamically loaded
     extension that is about to be unloaded.  On some systems Tcl
     is  automatically notified when it is being unloaded, and it
     calls Tcl_Finalize  internally;  on  these  systems  it  not
     necessary  for  the  caller to explicitly call Tcl_Finalize.
     However, to ensure  portability,  your  code  should  always
     invoke  Tcl_Finalize  when  Tcl is being unloaded, to ensure
     that the code will work on all platforms.  Tcl_Finalize  can
     be safely called more than once.

     Tcl_ExitThread is used to terminate the current  thread  and  |
     invoke  per-thread exit handlers.  This finalization is done  |
     by Tcl_FinalizeThread, which you can call if you  just  want  |
     to  clean  up  per-thread  state  and invoke the thread exit  |
     handlers.  Tcl_Finalize  calls  Tcl_FinalizeThread  for  the  |
     current thread automatically.

     Tcl_CreateExitHandler arranges for proc  to  be  invoked  by
     Tcl_Finalize   and   Tcl_Exit.   Tcl_CreateThreadExitHandler
     arranges for proc to be invoked  by  Tcl_FinalizeThread  and
     Tcl_ExitThread.  This provides a hook for cleanup operations
     such as flushing buffers and freeing  global  memory.   Proc
     should match the type Tcl_ExitProc:
          typedef void Tcl_ExitProc(ClientData clientData);
     The clientData parameter to proc is a copy of the clientData
     argument      given      to     Tcl_CreateExitHandler     or
     Tcl_CreateThreadExitHandler when the callback  was  created.
     Typically,  clientData points to a data structure containing
     application-specific information about what to do in proc.

     Tcl_DeleteExitHandler and Tcl_DeleteThreadExitHandler may be
     called  to  delete  a  previously-created  exit handler.  It
     removes the handler indicated by proc and clientData so that
     no  call  to  proc  will be made.  If no such handler exists
     then  Tcl_DeleteExitHandler  or  Tcl_DeleteThreadExitHandler



Tcl                     Last change: 8.1                        2






Tcl Library Procedures                             Tcl_Exit(3TCL)



     does nothing.

     Tcl_Finalize  and  Tcl_Exit  execute  all  registered   exit  |
     handlers, in reverse order from the order in which they were  |
     registered.  This matches the natural order in which  exten-  |
     sions  are  loaded and unloaded; if extension A loads exten-  |
     sion B, it usually unloads B before it itself  is  unloaded.  |
     If  extension  A  registers its exit handlers before loading  |
     extension B, this ensures that any exit handlers for B  will  |
     be executed before the exit handlers for A.                   |

     Tcl_Finalize and Tcl_Exit call  Tcl_FinalizeThread  and  the  |
     thread  exit  handlers after the process-wide exit handlers.  |
     This is because thread finalization shuts down the I/O chan-  |
     nel  system,  so  any  attempt  at  I/O  by  the global exit  |
     handlers will vanish into the bitbucket.


KEYWORDS
     callback, cleanup, dynamic loading, end  application,  exit,
     unloading, thread

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

     _______________________________________
    |   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.1                        3