Index for Section 3

Alphabetical listing for S

Bottom of page

st_addr_to_file(3)
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
  obj	    Specifies an object handle, as returned by the st_obj_open
	    function.

  addr	    Specifies a text address from the object.

  file	    Specifies an address to which st_addr_to_file writes the handle
	    of the file containing the specified text address.

  proc	    Specifies an address to which st_addr_to_proc writes the handle
	    of the procedure containing the specified text address.

  line	    Specifies an address to which st_addr_to_line writes the source
	    line number corresponding to the specified text address.

  sym	    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.

  byte_offset
	    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
  /usr/include/st.h
    header file that contains all definitions and function prototypes for
    libst.a functions

  /usr/include/cmplrs/demangle_string.h
    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)

Index for Section 3

Alphabetical listing for S

Top of page