Tcl_Exit(3) Tcl Library Procedures Tcl_Exit(3) 







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)








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










  
int status (in)

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

  
ClientData clientData (in)

  
Arbitrary one-word value to pass to proc.
    
    

    

  










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 application. 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 application 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 argument 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);



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 extensions are loaded
    and unloaded; if extension A loads extension 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 channel 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.










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







  

    8.5
    Tcl