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.

       Tcl_SetExitProc can not be used in stub-enabled extensions. Its	symbol
       entry  in  the  stub  table is deprecated and it	will be	removed	in Tcl
       9.0.

SEE ALSO
       exit(n)

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

Tcl				      8.5			   Tcl_Exit(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_CreateExitHandler.tcl87&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help