ADC Home > Reference Library > Reference > Mac OS X > Mac OS X Man Pages

 

This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).



Tcl_Exit(3)                                Tcl Library Procedures                                Tcl_Exit(3)



____________________________________________________________________________________________________________

NAME
       Tcl_Exit,  Tcl_Finalize,  Tcl_CreateExitHandler,  Tcl_DeleteExitHandler,  Tcl_ExitThread,  Tcl_Final-izeThread, Tcl_FinalizeThread,
       izeThread, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler - 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)

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

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

       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 porta-bility, portability,
       bility, 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 cur- |
       rent thread automatically.

       Tcl_CreateExitHandler arranges for proc  to  be  invoked  by  Tcl_Finalize  and  Tcl_Exit.   Tcl_Cre-ateThreadExitHandler Tcl_CreateThreadExitHandler
       ateThreadExitHandler  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 han- |
       dlers 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.


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



Tcl                                                  8.1                                         Tcl_Exit(3)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.