manpagez: man(ual) pages & more
man exit(3)
Home | html | info | man
Exit(3)                 Tcl Library Procedures                 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.
       Your code should always invoke Tcl_Finalize when Tcl is being unloaded,
       to  ensure  proper cleanup. 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_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 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.


SEE ALSO

       Exit(3)


KEYWORDS

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



Tcl                                   8.5                          Exit(3)

tcl 8.6.0 - Generated Sun Jan 6 09:26:13 CST 2013
© manpagez.com 2000-2017
Individual documents may contain additional copyright information.