Tk_CreateErrorHandler man page on Peanut

Man page or keyword search:  
man Server   7435 pages
apropos Keyword Search (all sections)
Output format
Peanut logo
[printable version]

Tk_CreateErrorHandler(3)     Tk Library Procedures    Tk_CreateErrorHandler(3)

______________________________________________________________________________

NAME
       Tk_CreateErrorHandler, Tk_DeleteErrorHandler - handle X protocol errors

SYNOPSIS
       #include <tk.h>

       Tk_ErrorHandler
       Tk_CreateErrorHandler(display, error, request, minor, proc, clientData)

       Tk_DeleteErrorHandler(handler)

ARGUMENTS
       Display *display (in)			Display whose errors are to be
						handled.

       int error (in)				Match only error  events  with
						this  value  in the error_code
						field.	If -1, then match  any
						error_code value.

       int request (in)				Match  only  error events with
						this value in the request_code
						field.	 If -1, then match any
						request_code value.

       int minor (in)				Match only error  events  with
						this  value  in the minor_code
						field.	If -1, then match  any
						minor_code value.

       Tk_ErrorProc *proc (in)			Procedure  to  invoke whenever
						an error event is received for
						display	  and  matches	error,
						request,  and	minor.	  NULL
						means	ignore	 any  matching
						errors.

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

       Tk_ErrorHandler handler (in)		Token  for  error  handler  to
						delete (return	value  from  a
						previous  call to Tk_CreateEr‐
						rorHandler).
_________________________________________________________________

DESCRIPTION
       Tk_CreateErrorHandler arranges for a particular procedure (proc) to  be
       called  whenever	 certain protocol errors occur on a particular display
       (display).  Protocol errors occur when the X protocol  is  used	incor‐
       rectly,	such  as  attempting to map a window that does not exist.  See
       the Xlib documentation for XSetErrorHandler for more information on the
       kinds  of  errors  that	can occur.  For proc to be invoked to handle a
       particular error, five things must occur:

       [1]    The error must pertain to display.

       [2]    Either the error argument	 to  Tk_CreateErrorHandler  must  have
	      been  -1,	 or the error argument must match the error_code field
	      from the error event.

       [3]    Either the request argument to Tk_CreateErrorHandler  must  have
	      been  -1,	 or  the  request argument must match the request_code
	      field from the error event.

       [4]    Either the minor argument	 to  Tk_CreateErrorHandler  must  have
	      been  -1,	 or the minor argument must match the minor_code field
	      from the error event.

       [5]    The protocol request to which the error pertains must have  been
	      made  when  the  handler was active (see below for more informa‐
	      tion).

       Proc should have arguments and result that match the following type:
	      typedef int Tk_ErrorProc(
		  ClientData clientData,
		  XErrorEvent *errEventPtr);
       The clientData parameter to proc is a copy of the  clientData  argument
       given  to  Tcl_CreateErrorHandler when the callback was created.	 Typi‐
       cally, clientData points to a data  structure  containing  application-
       specific	  information	that   is  needed  to  deal  with  the	error.
       ErrEventPtr is a pointer to the X  error	 event.	  The  procedure  proc
       should  return  an  integer  value.  If it returns 0 it means that proc
       handled the error completely and there is no need  to  take  any	 other
       action  for the error.  If it returns non-zero it means proc was unable
       to handle the error.

       If a value of NULL is specified for proc, all matching errors  will  be
       ignored:	  this will produce the same result as if a procedure had been
       specified that always returns 0.

       If more than more than one handler matches  a  particular  error,  then
       they  are  invoked  in  turn.   The handlers will be invoked in reverse
       order of creation:  most recently declared handler first.  If any  han‐
       dler  returns  0, then subsequent (older) handlers will not be invoked.
       If no handler returns 0, then Tk invokes	 X's  default  error  handler,
       which  prints  an error message and aborts the program.	If you wish to
       have a default handler that deals with errors that no other handler can
       deal with, then declare it first.

       The  X documentation states that “the error handler should not call any
       functions (directly or indirectly) on the display  that	will  generate
       protocol	 requests  or that will look for input events.”	 This restric‐
       tion applies to handlers declared by Tk_CreateErrorHandler; disobey  it
       at your own risk.

       Tk_DeleteErrorHandler  may  be  called  to  delete a previously-created
       error handler.  The handler argument identifies the error handler,  and
       should be a value returned by a previous call to Tk_CreateEventHandler.

       A  particular  error  handler applies to errors resulting from protocol
       requests generated between the call to  Tk_CreateErrorHandler  and  the
       call  to	 Tk_DeleteErrorHandler.	  However, the actual callback to proc
       may not occur  until  after  the	 Tk_DeleteErrorHandler	call,  due  to
       buffering  in  the  client and server.  If an error event pertains to a
       protocol request made just before calling  Tk_DeleteErrorHandler,  then
       the  error  event  may  not have been processed before the Tk_DeleteEr‐
       rorHandler call.	 When this situation arises, Tk will save  information
       about  the  handler  and invoke the handler's proc later when the error
       event finally arrives.  If an application wishes	 to  delete  an	 error
       handler	and  know  for certain that all relevant errors have been pro‐
       cessed, it should first call Tk_DeleteErrorHandler and then call XSync;
       this  will  flush out any buffered requests and errors, but will result
       in a performance penalty because it requires communication to and  from
       the  X  server.	 After the XSync call Tk is guaranteed not to call any
       error handlers deleted before the XSync call.

       For the Tk error handling mechanism to work properly, it	 is  essential
       that  application  code never calls XSetErrorHandler directly; applica‐
       tions should use only Tk_CreateErrorHandler.

KEYWORDS
       callback, error, event, handler

Tk						      Tk_CreateErrorHandler(3)
[top]

List of man pages available for Peanut

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net