Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
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
       int status (in)			     Provides  information  about  why
					     the application or	thread exited.
					     Exact  meaning  may  be platform-
					     specific.	0 usually means	a nor-
					     mal exit, any nonzero value  usu-
					     ally  means  that	an  error  oc-
					     curred.

       Tcl_ExitProc *proc (in)		     Procedure to invoke before	 exit-
					     ing  application, or (for Tcl_Se-
					     tExitProc)	NULL to	uninstall  the
					     current  application  exit	proce-
					     dure.

       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 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 in-
       stalled (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.
       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 in-
       voked 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  re-
       verse order from	the order in which they	were registered.  This matches
       the  natural  order in which extensions are loaded and unloaded;	if ex-
       tension 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(n)

KEYWORDS
       abort, callback,	cleanup, dynamic loading, end application,  exit,  un-
       loading,	thread

Tcl				      8.5			   Tcl_Exit(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_CreateThreadExitHandler.tcl86&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help