NAME    [Toc]    [Back]

       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    [Toc]    [Back]

       #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    [Toc]    [Back]

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

PARAMETERS    [Toc]    [Back]

       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_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.  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    [Toc]    [Back]

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

       Returns  the  file  handle  corresponding to the specified
       text address.  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.  Returns the  source
       line  number  corresponding to the specified text address.
       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.  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.  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    [Toc]    [Back]

       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    [Toc]    [Back]

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

SEE ALSO    [Toc]    [Back]

       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



                                               st_addr_to_file(3)