DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_CreateExitHandler(3tcl)




Tcl_Exit(3)          Tcl Library Procedures           Tcl_Exit(3)

_________________________________________________________________


NAME

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


SYNOPSIS

     #include <tcl.h>

     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)

     Tcl_ExitProc *                                                |
     Tcl_SetExitProc(proc)                                         |


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,    or     (for
                                           Tcl_SetExitProc)  NULL
                                           to    uninstall    the
                                           current    application
                                           exit procedure.

     ClientData clientData (in)            Arbitrary     one-word

Tcl                     Last change: 8.5                        1

Tcl_Exit(3)          Tcl Library Procedures           Tcl_Exit(3)

                                           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
     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.  If an application exit handler has  been  installed  |
     (see Tcl_SetExitProc), that handler is invoked with an argu-  |
     ment consisting of the exit status (cast to ClientData); the  |
     application exit handler should not return control to Tcl.

     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);

Tcl                     Last change: 8.5                        2

Tcl_Exit(3)          Tcl Library Procedures           Tcl_Exit(3)

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

     Tcl_SetExitProc  installs  an  application   exit   handler,  |
     returning  the previously-installed application exit handler  |
     or NULL if no application  handler  was  installed.   If  an  |
     application  exit  handler  is  installed, that exit handler  |
     takes over complete responsibility for finalization of Tcl's  |
     subsystems  via  Tcl_Finalize  at  an appropriate time.  The  |
     argument passed to proc when it is invoked will be the  exit  |
     status  code  (as  passed  to Tcl_Exit) cast to a ClientData  |
     value.


KEYWORDS

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

Tcl                     Last change: 8.5                        3


Man(1) output converted with man2html