Content-type: text/html Man page of st_addr_to_file

st_addr_to_file

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

st_addr_to_file, st_addr_to_proc, st_addr_to_line, st_data_addr_to_sym - Convert an address in an object to a file handle, procedure handle, line number, or symbol handle and offset.  

LIBRARY

Symbol Table and Object File Access Library (libst.a)  

SYNOPSIS

#include <st.h>

st_status_t st_addr_to_file (
        st_obj_t *obj,
        st_addr_t addr,
        st_file_t *file );

st_status_t st_addr_to_proc (
        st_obj_t *obj,
        st_addr_t addr,
        st_proc_t *proc );

st_status_t st_addr_to_line (
        st_obj_t *obj,
        st_addr_t addr,
        st_line_t *line );

st_status_t st_data_addr_to_sym (
        st_obj_t *obj,
        st_addr_t addr,
        st_sym_t *sym,
        int *byte_offset );

 

PARAMETERS

Specifies an object handle, as returned by the st_obj_open function. Specifies a text address from the object. Specifies an address to which st_addr_to_file writes the handle of the file containing the specified text address. Specifies an address to which st_addr_to_proc writes the handle of the procedure containing the specified text address. Specifies an address to which st_addr_to_line writes the source line number corresponding to the specified text address. Specifies an address to which st_data_addr_to_sym writes the symbol handle of the data variable lower or equal to the specified text address. Specifies an address to which st_data_addr_to_sym writes the difference between the specified text address and the start of the data symbol indicated by sym.  

DESCRIPTION

The st_addr_to_file, st_addr_to_proc, st_addr_to_line, and st_data_addr_to_sym functions convert an address in an object to a file handle, procedure handle, line number, or symbol handle and offset.

The st_addr_to_file function returns the file handle corresponding to the specified text address.

The st_addr_to_proc function returns the handle of the procedure containing the specified text address. If the procedure contains alternate entry points, the function returns the handle of the entry point that has the nearest address preceding the specified text address.

The st_addr_to_line function returns the source line number corresponding to the specified text address.

The st_data_addr_to_sym function returns the symbol handle of the data or variable lower or equal to the specified text address and a byte offset that is set to the difference between the specified text address and the start of the data symbol.

Notes

Use the st_data_addr_to_sym function on initialized and uninitialized data only (that is, for addresses that fall in the data or bss segments of the object. You cannot use st_data_addr_to_sym on local variables or for data allocated on the heap (for example, data allocated with malloc).

Because the specified text address may fall in padding between variables, st_data_addr_to_sym may return a symbol that does not actually contain the specified text address. To determine if this is the case, specify the returned symbol handle in calls to st_sym_value or st_sym_size to obtain the address and size of the symbol.

 

RETURN VALUES

All functions indicate success by returning a value of 0 (zero). A positive return value is an errno value from a system call. A negative return value is a library error or informational code. The library codes are documented in st.h.

Return parameters are set to 0 or -1 when an error occurs. Address parameters are set to 0 while file and procedure handles are set to -1. An exception to this is if a NULL pointer for the object or other return parameter is input. In these cases, the return parameters will be unchanged. A non-zero return status is the recommended method for detecting an error return from a libst function.  

FILES

header file that contains all definitions and function prototypes for libst.a functions header file that controls name-demangling operations for C++ objects  

RELATED INFORMATION

Commands: atom(1)

Functions: libst_intro(3), st_file_lang(3), st_obj_file_start(3), st_obj_open(3), st_objlist_append(3), st_proc_addr(3), st_sym_value(3) delim off


 

Index

NAME
LIBRARY
SYNOPSIS
PARAMETERS
DESCRIPTION
RETURN VALUES
FILES
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:41:18 GMT, October 02, 2010