exc_remove_pc_range_table man page on DigitalUNIX

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

exc_add_pc_range(3)					   exc_add_pc_range(3)

NAME
       exc_add_pc_range_table,	 exc_remove_pc_range_table,   exc_lookup_func‐
       tion_table,	      find_rpd,		    exc_lookup_function_entry,
       exc_remote_lookup_function_entry,		     exc_add_gp_range,
       exc_remove_gp_range, exc_lookup_gp - routines to support	 mapping  pro‐
       gram counters to the data structures defined at run time

SYNOPSIS
       #include <excpt.h>

       void exc_add_pc_range_table(
	       PRUNTIME_FUNCTION pbase,
	       pdsc_count count ); void exc_remove_pc_range_table(
	       PRUNTIME_FUNCTION  pbase	 ); PRUNTIME_FUNCTION exc_lookup_func‐
       tion_table(
	       exc_address pc ); PRUNTIME_FUNCTION find_rpd(
	       exc_address pc ); PRUNTIME_FUNCTION exc_lookup_function_entry(
	       exc_address pc ); void exc_add_gp_range(
	       exc_address begin_address,
	       unsigned long length,
	       exc_address gp ); void exc_remove_gp_range(
	       exc_address begin_address ); exc_address exc_lookup_gp(
		exc_address pc	);  PRUNTIME_FUNCTION  exc_remote_lookup_func‐
       tion_entry(
	       void *handle,
	       int (*fetch_from_process) (void *handle, void *addr, void *buf‐
       fer, long size),
	       exc_address pc,
	       exc_address crd_handle,
	       PRUNTIME_FUNCTION *func_entry,
	       PRUNTIME_FUNCTION *crd_base );

LIBRARY
       Exception Handling Library (libexc.a)

PARAMETERS
       Pointer to the base of a code-range descriptor table.  Number of	 code-
       range  descriptors  in the table pointed to by pbase.  Address within a
       range of code for which the base of a code-range descriptor table is to
       be  returned.  First address for which the gp argument applies.	Number
       of bytes from begin_address for which the gp argument applies.  Address
       of  the	global	pointer	 used  to refer to the Global Offset Table and
       small data sections (see the Calling Standard for Alpha Systems and the
       Object File/Symbol Table Format Specification).

       The     following     parameter	   descriptions	    apply    to	   the
       exc_remote_lookup_function_entry() routine. How	these  parameters  are
       interpreted depends on whether the process involved in the operation is
       local or remote.	 Remote lookup: A pointer to  an  arbitrary  block  of
       memory,	set  up and managed by the user application and passed through
       the exception handling routines. This allows the author of the function
       identified  by  the fetch_from_process parameter to maintain any neces‐
       sary state. The state maintained here  will  most  likely  include  the
       identity of the process to be unwound.

	      Local  lookup:  This  parameter  is ignored.  Remote lookup: The
	      address of an application-specific  function  contained  in  the
	      user  application that calls exc_remote_lookup_function_entry().
	      If fetch_from_process is NULL,  the  lookup  of  the  code-range
	      descriptor  takes	 place	in  the	 local	process,  not a remote
	      process.

	      The function  identified	by  the	 fetch_from_process  parameter
	      takes  the  following  arguments:	 The handle parameter that was
	      passed into  exc_remote_lookup_function_entry().	 The  starting
	      address in the remote process from which to copy memory.	A buf‐
	      fer in the local process into which data from the remote process
	      is copied.  The number of bytes to copy from addr to buffer. The
	      region of memory pointed to by buffer  must  be  at  least  size
	      bytes in length.

	      The  function  identified	 by  the  fetch_from_process parameter
	      returns 0 (zero) to indicate success and nonzero to  indicate  a
	      failure  in  accessing  the remote address space. A failure will
	      also cause an exception status to be raised.

	      Local lookup: Must be NULL (by definition).  Remote lookup:  The
	      program counter (PC) value in the remote process for which code-
	      range descriptor information is to be returned.

	      Local lookup: The	 program  counter  (PC)	 value	in  the	 local
	      process  for  which  code-range  descriptor information is to be
	      returned.	   Remote   lookup:   The   address   of   the	  cell
	      exc_crd_list_head	 in  the process whose function entry is being
	      looked up. The means by which this address  is  communicated  to
	      the process calling exc_remote_lookup_function_entry() is appli‐
	      cation specific.	Remote lookup: The address of a PRUNTIME_FUNC‐
	      TION  allocated  by the caller, into which the appropriate code-
	      range descriptor in the remote process  is  written.  The	 PRUN‐
	      TIME_FUNCTION must point to struct pdsc_crd, which is also allo‐
	      cated by the caller. The code-range descriptor does not need  to
	      be initialized in any way.

	      In  the  event of a lookup failure (that is, the function return
	      value is zero), the contents of the structure  pdsc_crd  pointed
	      to by this PRUNTIME_FUNCTION are unpredictable.

	      Local  lookup:  The  address  of a PRUNTIME_FUNCTION. If a PRUN‐
	      TIME_FUNCTION is passed, the contents of	the  PRUNTIME_FUNCTION
	      is  written  with the address of the appropriate pdsc_crd struc‐
	      ture. May be NULL.   Remote  lookup:  The	 address  of  a	 PRUN‐
	      TIME_FUNCTION, where the base address of the code-range descrip‐
	      tor table is written.  (Note: this pointer is  written  with  an
	      address  in  the remote address space. Do not try to dereference
	      this pointer.)

	      Local lookup: Same meaning as remote lookup case, except may  be
	      NULL.

DESCRIPTION
       The  exception system needs to access procedure-specific information at
       run time in order to perform unwinds and call handlers. You  find  this
       information by mapping a PC to a procedure and its structures.

       The   PRUNTIME_FUNCTION	typedef	 points	 to  a	code-range  descriptor
       (pdsc(4)). A code-range descriptor represents a range of addresses.  To
       support	very  high levels of optimization, one procedure can be repre‐
       sented by many code-range  descriptors  (but  a	code-range  descriptor
       belongs to only one procedure).

       The  code-range descriptor provides the key to access all of the infor‐
       mation that the exception system requires about a  procedure  (although
       some  of	 it  may  be  available only indirectly through the code-range
       descriptor).

       The assembler automatically generates  code-range  descriptors  in  the
       section of a relocatable object file that the linker merges into a sin‐
       gle code-range descriptor table for each executable and shared  object.
       The  linker  also  generates code in the and sections so that each exe‐
       cutable	 and	shared	  object    will    register	(by    calling
       exc_add_pc_range_table())      and      deregister      (by     calling
       exc_remove_pc_range_table()) their code-range descriptor tables at  run
       time with the exception system (if present).

       You  may	 need  to  call	 these	routines manually if you are using the
       exception system and generate or load code yourself without using stan‐
       dard Tru64 UNIX system libraries and services.

       The  exception  system  maintains  the  list  of	 registered code-range
       descriptor tables. The exc_lookup_function_table()  routine  returns  a
       pointer to the base of a code-range descriptor table containing a range
       of code that includes the address supplied in the  pc  argument.	  This
       routine	returns	 a  NULL  (zero-value)	pointer if an entry for the pc
       argument is not found.

       The exc_lookup_function_entry() and find_rpd() routines each  return  a
       PRUNTIME_FUNCTION for the address supplied by the pc argument.

					Note

       The  find_rpd() routine is an old ULTRIX libexc interface. It continues
       to work on Tru64 UNIX systems if its callers treat its return  argument
       as  an opaque pointer. If they explicitly access fields in the returned
       structure, they will encounter incompatibilities.

       The exc_remote_lookup_function_entry() routine can look up a code-range
       descriptor  in  either the local process or a remote process.  When the
       correct code-range descriptor is located, it is copied into  the	 local
       address space in storage indicated by the func_entry parameter. In nor‐
       mal remote unwinding  use,  exc_remote_lookup_function_entry()  is  not
       called  from  the  application,	but  is	 used  as a utility routine by
       exc_remote_virtual_unwind().  In	 both  cases   (local	and   remote),
       exc_remote_lookup_function_entry()  returns  the	 address  of the code-
       range descriptor if successful and zero otherwise.  (Note:  the	return
       value  from  exc_remote_lookup_function_entry()	is  an	address in the
       remote address space. Do not try to dereference this pointer.)

       Remote lookup of a code-range descriptor by the exc_remote_lookup_func‐
       tion_entry()  function  can  involve either a local process or a remote
       process -- unlike the other lookup and find functions that operate only
       on   local   processes.	  Remote   lookup   is	 controlled   by   the
       fetch_from_process parameter. This parameter is a pointer to (or handle
       for) an application-supplied function that knows how to access the mem‐
       ory of the process (local or remote) being acted on: If the user appli‐
       cation  passes  a  NULL	value in the fetch_from_process parameter, the
       lookup operation is being performed on the local process.

	      This allows the lookup routine to make certain optimizations  in
	      its processing.  If the user application passes the address of a
	      routine in the fetch_from_process parameter, the lookup  routine
	      is  not  allowed	to  assume  anything  about  the process it is
	      accessing, and only the fetch routine is	allowed	 to  know  the
	      identity	of  the	 process being acted on. It might be the local
	      process, it might be another process in the system, it might  be
	      a	 process  on  another  system on the network, or it might be a
	      corefile from a long-deceased process.

       To summarize, remote lookup is the capability  to  look	up  code-range
       descriptors  in a process that is not necessarily the process doing the
       lookup.

       The unwind functions typically call some of these lookup and find func‐
       tions  to  obtain enough information to virtually unwind procedure con‐
       texts.

       The gp is not in the code-range or  procedure  descriptors  (  pdsc(4))
       because	the same gp can be used for many routines and including the gp
       would  waste  space.   Instead,	 the   linker	generates   calls   to
       exc_add_gp_range() in the section of an executable or shared object and
       exc_remove_gp_range() in the section. Many executables  have  only  one
       such call each in their and sections.

       The  exc_lookup_gp()  routine returns a NULL (zero value) pointer if an
       entry for the pc parameter is not found.

FILES
       /usr/ccs/lib/cmplrs/cc/libexc.a -- exception handling library
       /usr/include/excpt.h -- include file
       /usr/include/pdsc.h -- include file
       /usr/include/signal.h -- include file
       /usr/include/machine/fpu.h -- include file

SEE ALSO
       Functions:  exception_intro(3),	 exception_dispatcher(3),   signal(2),
       sigaction(2), setjmp(3), exc_unwind(3), __exc_last_chance(3), ieee(3).

       Files: excpt(4), c_excpt(4), signal(4), pdsc(4).

       Calling Standard for Alpha Systems

       Object File/Symbol Table Format Specification

       Assembly Language Programmer's Guide

							   exc_add_pc_range(3)
[top]

List of man pages available for DigitalUNIX

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