manpagez: man pages & more
man Tcl_Finalize(3)
Home | html | info | man
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

       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.   Procedure  to
       invoke  before  exiting  application,  or (for Tcl_SetExitProc) NULL to
       uninstall the current application exit procedure.   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  any-
       place 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  ter-
       minate  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 applica-
       tion 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  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 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 mem-
       ory.   Proc  should match the type Tcl_ExitProc: typedef void Tcl_Exit-
       Proc(ClientData clientData); The clientData parameter to proc 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 proc.

       Tcl_DeleteExitHandler and Tcl_DeleteThreadExitHandler may be called  to
       delete a previously-created exit handler.  It removes the handler indi-
       cated by proc and clientData so that no call to proc 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  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 argu-
       ment 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                                   8.5                          Tcl_Exit(3)

Exit 8.5.4 - Generated Mon Aug 18 18:30:29 CDT 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.