st_addr_to_file(3)					     Library Functions Manual						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 han-
       dle, 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  alter-
       nate 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  seg-
       ments  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 opera-
       tions 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

																st_addr_to_file(3)