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

FreeBSD Manual Pages


home | help
Tcl_Exit(3)		    Tcl	Library	Procedures		   Tcl_Exit(3)


       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)

       #include	<tcl.h>



       Tcl_CreateExitHandler(proc, clientData)

       Tcl_DeleteExitHandler(proc, clientData)



       Tcl_CreateThreadExitHandler(proc, clientData)

       Tcl_DeleteThreadExitHandler(proc, clientData)

       Tcl_ExitProc *							       |
       Tcl_SetExitProc(proc)						       |

       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-

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

       ClientData clientData (in)	     Arbitrary one-word	value to  pass
					     to	proc.

       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.
       On some systems Tcl is automatically notified  when  it	is  being  un-
       loaded,	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  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.

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

Tcl				      8.5			   Tcl_Exit(3)


Want to link to this manual page? Use this URL:

home | help