Seth Woolley's Man Viewer

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

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

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 - end the application or thread (and invoke
       exit(3,n,1 builtins) handlers)

SYNOPSIS
       #include <tcl.h>

       Tcl_Exit(status)

       Tcl_Finalize()

       Tcl_CreateExitHandler(proc(5,n), clientData)

       Tcl_DeleteExitHandler(proc(5,n), clientData)

       Tcl_ExitThread(status)

       Tcl_FinalizeThread()

       Tcl_CreateThreadExitHandler(proc(5,n), clientData)

       Tcl_DeleteThreadExitHandler(proc(5,n), clientData)

ARGUMENTS
       Provides information about why the application or thread exited.  Exact
       meaning  may  be platform-specific.  0 usually means a normal exit(3,n,1 builtins), any
       nonzero value usually means  that  an  error(8,n)  occurred.   Procedure  to
       invoke before exiting application.  Arbitrary one-word value to pass to
       proc(5,n).


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(3,n,1 builtins) from this process.
       This  procedure is invoked by the exit(3,n,1 builtins) command, and can be invoked any-
       place else to terminate the application.  No-one should ever invoke the
       exit(3,n,1 builtins)  system  procedure  directly;   always invoke Tcl_Exit instead, so
       that it can invoke exit(3,n,1 builtins) handlers.  Note that if(3,n) other code invokes exit(3,n,1 builtins)
       system  procedure directly, or otherwise causes the application to ter-
       minate without calling Tcl_Exit, the exit(3,n,1 builtins) handlers  will  not  be  run.
       Tcl_Exit internally invokes the exit(3,n,1 builtins) system call, thus it never returns
       control to its caller.

       Tcl_Finalize is similar to Tcl_Exit except that it does not  exit(3,n,1 builtins)  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(1,8)  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  plat-
       forms. Tcl_Finalize can be safely called more than once.

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

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

       Tcl_DeleteExitHandler and Tcl_DeleteThreadExitHandler may be called  to
       delete a previously-created exit(3,n,1 builtins) handler.  It removes the handler indi-
       cated by proc(5,n) and clientData so that no call to proc(5,n) will be made.   If
       no  such handler exists then Tcl_DeleteExitHandler or Tcl_DeleteThread-
       ExitHandler does nothing.


       Tcl_Finalize and Tcl_Exit execute  all  registered  exit(3,n,1 builtins)  handlers,  in(1,8)
       reverse  order  from  the  order  in(1,8)  which they were registered.  This
       matches the natural order in(1,8) which extensions are loaded and  unloaded;
       if(3,n) extension A loads extension B, it usually unloads B before it itself
       is unloaded.  If extension A registers its exit(3,n,1 builtins) handlers before loading
       extension B, this ensures that any exit(3,n,1 builtins) handlers for B will be executed
       before the exit(3,n,1 builtins) handlers for A.

       Tcl_Finalize and Tcl_Exit call Tcl_FinalizeThread and the  thread  exit(3,n,1 builtins)
       handlers  after the process-wide exit(3,n,1 builtins) handlers.  This is because thread
       finalization shuts down the I/O channel system, so any attempt  at  I/O
       by the global exit(3,n,1 builtins) handlers will vanish into the bitbucket.


KEYWORDS
       callback,  cleanup,  dynamic loading, end application, exit(3,n,1 builtins), unloading,
       thread



Tcl                                   8.1                          Tcl_Exit(3)

References for this manual (incoming links)