Query: uwx_register_callbacks
OS: hpux
Section: 3x
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
uwx_register_callbacks(3X) uwx_register_callbacks(3X)NAMEuwx_register_callbacks() - register callback routines for stack unwindSYNOPSISDESCRIPTIONis part of the Unwind Express Library for Integrity system; see uwx(3X). registers two callback routines, a copy-in callback and a lookup- ip callback, with the unwind environment. For self-unwinding, two routines -- and -- are provided in the Unwind Express library for this purpose. For other unwinding applications, the client must supply these routines. The callback routines provide the interface between the unwind engine and the specific environment in which unwinding is taking place. This interface uses a "token" by which the callback routines can maintain and share state information. The token is an arbitrary pointer- sized value that is provided by the client, and passed to the callback routines when they are called by the unwind engine. The lookup-ip callback routine is called by the unwind engine to lookup an Instruction Pointer (IP) and find the load module associated with that IP. The copy-in callback routine is called to read data from the memory space of the process being unwound. Parameters env A pointer to an unwind environment object. tok The "token"--an arbitrary value provided by the client to be passed to the callback routines. When using the provided call- backs for self-unwinding, this parameter must be the pointer to the self-info object returned by copyin Pointer to the copy-in callback routine. For self-unwinding, this parameter should be the address of the routine. lookupip Pointer to the lookup-ip callback routine. For self-unwinding, this parameter should be the address of the routine. The Callback Token The token, declared as type is typically a pointer to a callback information structure defined by and provided by the client. This struc- ture contains information that the client needs to share with the callback routines it provides. The structure may also provide a storage area where the callback routines can maintain cached information. For a cross-unwind, the callback information structure needs to contain information about the target process (e.g., thread or process id), along with some address space mapping information. The callback information structure also needs to contain a copy of or a reference to the initial context from which the unwind was initi- ated. The unwind environment itself tracks only the state of preserved registers and the key stack marker values (ip, sp, bsp, cfm); if execution stops in a leaf function or early in a function prologue, some important values may exist in scratch registers (e.g., the return pointer, rp, may still be in BR0). When the unwind engine determines that it needs the value from a register that it doesn't already have, it uses the copy-in callback to obtain that value. The Lookup IP callback The lookup-ip callback is used for obtaining information for a given IP. Its prototype is given in as follows: The unwind engine passes the following parameters to the callback routine: request Identifies the type of request that the unwind engine is making. ip The IP for which information is needed. tok The callback token. resultp Address of a result vector pointer. The unwind engine uses this callback for four types of requests: Requests the callback to lookup information for the given IP. The callback must allocate a result vector, place the load information in the vector, and return a pointer to the result vector in Informs the callback when it is safe to free the result vector. A pointer to the vector returned by the lookup request is passed in (*resultp). The ip parameter is not used for this request. (If the result vector was not dynamically allocated, this request can be ignored.) Requests the callback to return symbolic information for the IP. If symbolic information is available, the callback must allocate a result vector, place the symbolic information in the vector, and return a pointer to the result vector in Requests the callback to return the name of the module containing the IP. If the module name is available, the callback must allocate a result vector, place the module name in the vector, and return a pointer to the result vector in In order to step from one frame to a previous frame on the stack, starts with the current IP and makes a request to obtain information about this IP. The and requests are used only if the client makes a specific request for symbolic information that is not already avail- able for the current frame. The parameter is both an input and an output parameter to the lookup-ip callback routine. As an input parameter, it points to an array of key/value pairs of unsigned 64-bit integers. The first value in each pair is a key, and the second value in each pair is a corresponding value. The vector is terminated by a key/value pair whose key is 0. The vector may contain the following keys: Version number of the current callback interface. The value corresponding to this key is currently 3. This version number changes only when the callback interface adds new fea- tures that a client may wish to check for. Current value of the predicate registers. This is provided only for requests, and only if the predicates are currently known. Starting address of the current function. This is provided only for and requests, and only if the starting address of the function is currently available. (This value can assist the callback routine in locating the proper symbol name.) An inline context identifier. This is provided only for requests in response to a call to the entry point. See uwx_step_inline(3X) and uwx_find_source_info(3X) for more information about stepping over inlined calls. In response to the request, the callback must return one of the following status codes: A load module was found. The result vector contains load module and unwind table information. No information found for this IP. An error occurred. In the normal case, the callback obtains the following information about the given IP: base address of its text segment, starting and end- ing addresses of the unwind table, and (optional) unwind flags. It places this information in the result vector, and returns the status code. The result vector is an array of key/value pairs. The first value in each pair is a key, and the second value in each pair is a corre- sponding value. The vector is terminated by a key/value pair whose key is 0. The following keys can be returned in the result vector: Base address of text segment. Starting address of unwind table. Ending address of unwind table. Unwind flags (HP-UX only). Value of the gp register for this load module. On HP-UX, the load information can be obtained with the and routines. The routine returns a descriptor containing the base address of the text segment and the address of the unwind header, and the routine returns the name of that load module. The unwind header contains the unwind flags, and the segment-relative offsets of the beginning and end of the unwind table. The callback must convert the segment-rela- tive offsets to virtual addresses by adding the base address of the text segment. The unwind flags contain a version number of the unwind table format, and a flag that indicates whether the unwind table contains 32-bit or 64-bit entries. (On other operating systems, unwind tables always contain 64-bit entries, so the unwind flags do not need to be provided.) If the callback does not find any information it returns the status code. It should leave the resultp parameter unmodified. When the callback returns the unwind engine will assume that the IP belongs to a leaf procedure with default unwind properties, and will attempt to unwind accordingly. If any error condition occurs that would prevent the unwind engine from unwinding correctly, the callback should return and leave the resultp parameter unmodified. In response to the or request, the callback must return one of the following status codes: Symbolic information was found for this IP. No symbolic information found for this IP. An error occurred. When returning with status, the result vector can contain the following keys: Pointer to name of the load module containing the IP. Pointer to name of the function containing the IP. Address of the start of function containing the IP. Pointer to name of an inlined function name (if the current context is in an inlined call). Pointer to name of the source file containing the current function. Source line number within the source file corresponding to the IP. An inline context identifier for use in stepping through inlined calls (if the current context is in an inlined call). In all cases when the callback returns a pointer to a string, the unwind engine copies the string into a string pool within the unwind environment. The client may deallocate or reuse its string storage after the request. The Copy-In Callback The copy-in callback is used for obtaining values from the address space of the process being unwound. Its prototype is given in as fol- lows: The unwind engine passes the following parameters to the callback routine: request Identifies the type of request that the unwind engine is making. loc Address in local memory where the requested data should be placed. This address will always be properly aligned for an object of the requested length. rem Address in remote memory from which remote data should be read, or the identifier of a register to be read from the con- text of the target process. len Number of bytes to read from the target address space. For requests, it will always be either 4 or 8; for all other requests, it will always be 8. tok The callback token. The unwind engine uses this callback for four types of requests: Read data from the unwind information area of the target process. Since this area is in the text segment, a debugger may choose to read this information directly from the file or from a copy in local memory instead of from the target process. Read data from the memory stack of the target process. Read data from the register stack backing store of the target process. Special considerations may be necessary for portions of the backing store. (For example, on HP-UX, reading from an area between BSP and BSPSTORE using either or the library requires a special request type.) Read data from a register in the current process context. If unwinding was initiated or resumed from a signal context record, this request should read data from the signal context record. For all but requests, the rem parameter contains the address in remote memory from which data should be read. This address will always be properly aligned for an object of the requested length. For requests, the rem parameter contains the register identifier of the register whose value is needed. The register identifier will be one of the following: predicates (PR0-PR63) (1 - 31) (2 - 127) (0 - 7) On a successful copy in operation, the callback must return the number of bytes read (which must match the len parameter). If an error occurs, the callback should return 0.RETURN VALUEreturns on successful registration of the callback routines. See uwx(3X) for error codes.AUTHORThe Unwind Express Library was developed by Hewlett-Packard.SEE ALSOdlgetname(3C), dlmodinfo(3C), uc_access(3), uwx(3X), uwx_add_to_bsp(3X), uwx_find_source_info(3X), uwx_find_symbol(3X), uwx_free(3X), uwx_get_abi_context_code(3X), uwx_get_funcstart(3X), uwx_get_module_info(3X), uwx_get_nat(3X), uwx_get_reg(3X), uwx_get_source_info(3X), uwx_get_sym_info(3X), uwx_init(3X), uwx_init_context(3X), uwx_register_alloc_cb(3X), uwx_release_symbol_cache(3X), uwx_self_do_con- text_frame(3X), uwx_self_free_info(3X), uwx_self_init_context(3X), uwx_self_init_info(3X), uwx_set_nofr(3X), uwx_set_remote(3X), uwx_step(3X), uwx_step_inline(3X). Integrity Systems Only uwx_register_callbacks(3X)