st_addr_to_file(3)

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_addr_to_sym,
  st_data_addr_to_sym, st_text_addr_to_sym - convert an address in an object
  to a file handle, procedure handle, line number, or symbol handle and
  offset

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_addr_to_sym(
	  st_obj_t *obj,
	  st_addr_t addr,
	  st_sym_t *sym,
	  int *byte_offset );

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

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

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

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_addr_to_sym(), st_data_addr_to_sym(),
      or st_text_addr_to_sym() writes the handle of the symbol lower or equal
      to the specified address.

  byte_offset
      Specifies an address to which st_addr_to_sym(), st_data_addr_to_sym(),
      or st_text_addr_to_sym() writes the difference between the specified
      address and the address of the symbol indicated by sym.

DESCRIPTION
  These functions convert an address in an object to a file handle, procedure
  handle, line number, or symbol handle and offset:

  st_addr_to_file
      Returns the file handle corresponding to the specified text address.

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

  st_addr_to_line
      Returns the source line number corresponding to the specified text
      address.

  st_addr_to_sym
      Returns the handle of a symbol with an address lower or equal to the
      specified address and a byte offset that is set to the difference
      between the specified address and the address of the symbol.

  st_data_addr_to_sym
      Returns the handle of a symbol with an address lower or equal to the
      specified data address and a byte offset that is set to the difference
      between the specified data address and the address of the symbol.

      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 data address may fall in padding between
      variables, st_data_addr_to_sym() may return a symbol that does not
      actually contain the specified data 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.

  st_text_addr_to_sym
      Returns the handle of a symbol with an address 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 address of the symbol.

      Use the st_text_addr_to_sym() function on text and read-only data only
      (that is, for addresses that fall in the text segment of the object).
      You cannot use st_text_addr_to_sym() on local variables.

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 nonzero 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

SEE ALSO
  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)

  Programmer's Guide
Index for
Section 3
Alphabetical
listing for S
Top of
page