st_proc_addr(3) 					     Library Functions Manual						   st_proc_addr(3)

NAME

       st_is_alternate_entry,	  st_proc_addr,     st_proc_sym,     st_proc_name,    st_proc_to_file,	  st_proc_start_line,	 st_proc_end_line,
       st_outer_proc_end_line,	st_check_proc_line_range,  st_proc_sort,  st_proc_sorted_start,  st_proc_sorted_next,  st_foreach_proc,   st_fore-
       ach_obj_proc, st_foreach_proc_sorted - Access information about the procedures in an object

LIBRARY

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

SYNOPSIS

       #include <st.h>

       st_status_t st_is_alternate_entry (
	       st_obj_t *obj,
	       st_proc_t proc,
	       st_bool_t *alt );

       st_status_t st_proc_addr (
	       st_obj_t *obj,
	       st_proc_t proc,
	       st_addr_t *proc_addr );

       st_status_t st_proc_sym (
	       st_obj_t *obj,
	       st_proc_t proc,
	       st_sym_t *sym );

       st_status_t st_proc_name (
	       st_obj_t *obj,
	       st_proc_t proc,
	       char **name );

       st_status_t st_proc_to_file (
	       st_obj_t *obj,
	       st_proc_t proc,
	       st_file_t *file );

       st_status_t st_proc_start_line (
	       st_obj_t *obj,
	       st_proc_t proc,
	       st_line_t *sline );

       st_status_t st_proc_end_line (
	       st_obj_t *obj,
	       st_proc_t proc,
	       st_line_t *eline );

       st_status_t st_outer_proc_end_line (
	       st_obj_t  *obj,
	       st_proc_t proc,
	       st_line_t *eline );

       st_status_t st_check_proc_line_range (
	       st_obj_t *obj,
	       st_proc_t proc,
	       unsigned long line,
	       st_proc_t *oproc );

       st_status_t st_proc_sort (
	       st_obj_t *obj ); st_status_t st_proc_sorted_start (
	       st_obj_t *obj,
	       st_proc_t *pstart );

       st_status_t st_proc_sorted_next (
	       st_obj_t *obj,
	       st_proc_t proc,
	       st_proc_t *result );

       st_status_t st_foreach_proc (
	       st_obj_t *obj,
	       st_file_t file,
	       st_status_t (*routine) __((st_obj_t *obj,
					     st_proc_t proc,
					     st_any_t  data,
					     st_any_t *result)),
	       st_any_t data,
	       st_any_t *result );

       st_status_t st_foreach_obj_proc (
	       st_obj_t *obj,
	       st_status_t (*routine) __((st_obj_t  *obj,
					     st_proc_t proc,
					     st_any_t  data,
					     st_any_t  *result)),
	       st_any_t data,
	       st_any_t *result );

       st_status_t st_foreach_obj_proc_sorted (
	       st_obj_t *obj,
	       st_status_t (*routine) __((st_obj_t *obj,
					     st_proc_t proc,
					     st_any_t data,
					     st_any_t *result)),
	       st_any_t data,
	       st_any_t *result );

PARAMETERS

       Specifies  an  object  handle,  as  returned  by the st_obj_open function.  Specifies a procedure handle, as returned by a function such as
       st_obj_proc_start.  Specifies an address to which st_is_alternate_entry returns a Boolean value of TRUE if the specified  procedure  is	an
       alternate  entry or a nested routine.  Specifies an address to which st_proc_addr returns the starting address of the procedure as it would
       reside in memory when the object is executing.  Specifies an address to which st_proc_sym returns the symbol handle for the specified  pro-
       cedure.	 Specifies  an	address  to  which st_proc_name returns the null-terminated string of the procedure name.  Specifies an address to
       which st_proc_to_file returns the handle of the file that contains the specified procedure, or a file handle that st_foreach_proc  uses	to
       locate procedures for which to run the specified routine.  Specifies an address to which st_proc_start_line writes the starting line number
       for the specified procedure.  This number identifies the line in the source file at which the procedure is defined.  Specifies  an  address
       to which st_proc_end_line writes the ending line number for the specified procedure.  This number identifies the line in the source file at
       which the procedure ends.  If the specified procedure is an alternate entry or a nested procedure, st_outer_proc_end_line returns the  end-
       ing line of the procedure containing the specified procedure to this location.  Specifies a line number that st_check_proc_line_range is to
       determine is within the range of lines within the specified procedure.  Specifies an address to which  st_check_proc_line_range	returns  a
       procedure  handle  if  the specified line number is within the range of lines in the specified procedure, or -1 if it is not.  Specifies an
       address to which st_proc_sorted_start the handle of the first procedure in the sorted procedure table created by its implicit call  of  (or
       prior  explicit call to) st_proc_sort.  For the st_proc_sorted_next function, specifies an address to which the function returns the proce-
       dure that follows proc in the sorted procedure table. For the st_foreach_proc, st_foreach_obj_proc), and  st_foreach_obj_proc_sorted  func-
       tions, specifies an address to receive the return value from the specified routine.  The called routine must be written to return 0 to ter-
       minate its execution within the procedure list, and ST_FOREACH_CONTINUE to continue to the next	procedure.   Specifies	a  routine  to	be
       called  for  each  procedure  in  the  specified  file (st_foreach_proc), object (st_foreach_obj_proc), or sorted procedure table (st_fore-
       ach_obj_proc_sorted).  Specifies data to be input to or output from the routine to  be  called  for  each  object  in  the  specified  file
       (st_foreach_proc), object (st_foreach_obj_proc), or sorted procedure table (st_foreach_obj_proc_sorted).

DESCRIPTION

       These functions return information about a procedure or perform operations on the procedures in an object or file.

       The st_is_alternate_entry function determines whether the specified procedure is an alternate entry or nested routine.

       The st_proc_addr function returns the starting address of the procedure as it would reside in memory when the object is executing.

       The st_proc_sym function returns the symbol handle for the specified procedure.

       The  st_proc_name function returns the null-terminated string of the procedure name. Because the returned procedure name is for read-access
       only, the calling program should make any modifications to a copy of this string.

       The st_proc_to_file function returns the handle of the file that contains the specified procedure.

       The st_proc_start_line and st_proc_end_line functions return the numbers of the line in the source file at which the procedure  is  defined
       and  the  line at which the procedure ends, respectively.  The st_outer_proc_end_line function returns the ending line number of the proce-
       dure that contains the specified procedure, and is used for procedures that are alternate entries or nested procedures.	If  the  specified
       procedure  is  neither  an  alternate entry or a nested procedure, st_outer_proc_end_line returns the line at which the specified procedure
       ends.

       The st_check_proc_line_range function determines whether the specified line number is within the range of lines in the specified procedure.
       If  the	line  number  is  within  range,  the function returns the procedure handle.  If not, it returns -1 to the location to which oproc
       points.	Use st_check_proc_line_range when calling st_foreach_proc, st_foreach_obj_proc, st_foreach_obj_proc_sorted to operate on  all  the
       procedures  in a given file, object, or sorted procedure list. The line parameter is defined as an unsigned long to allow it to be used for
       this purpose.

       The st_proc_sort function creates a table of procedures sorted by increasing address order.  It includes all procedures	in  the  specified
       object in the sorted procedure table.  The sorted procedure table enables faster search operations on the procedure addresses by other rou-
       tines.  Any libst routines that require a sorted procedure table implicitly call st_proc_sort if the table does	not  already  exist.   The
       st_proc_sorted_start  function  returns	the handle of the first procedure in the sorted procedure table.  The st_proc_sorted_next function
       returns the handle of the procedure that follows proc in the sorted procedure table.

									  Note
       Use the st_obj_proc_start and st_obj_proc_next functions to access procedures in the order that they appear in  the  object,  that  is,	in
       their link order.  Use the st_proc_sorted_start and st_proc_sorted_next functions to access procedures in ascending address order.

       Note that some objects may have multiple procedures at the same address.

       Use st_obj_proc_count to determine the number of procedures in an object or sorted procedure table.

       The  st_foreach_proc, st_foreach_obj_proc, and st_foreach_obj_proc_sorted functions provide a means of calling a routine once for each pro-
       cedure in the specified file, object, or sorted procedure table.   You must write the called routine so that it returns 0 to terminate  its
       execution within the procedure list, and ST_FOREACH_CONTINUE to continue to the next procedure.

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.

       The st_foreach_proc, st_foreach_obj_proc, and st_foreach_obj_proc_sorted functions return ST_E_NULL_ARGUMENT if a  null	object	handle	or
       routine pointer are supplied.  It returns a value of 0 (zero) when the called routine returns 0 to it.  Otherwise, it returns ST_OBJ_END to
       indicate that it has reached the end of the procedures without a successful return from the called routine.

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_addr_to_file(3), st_file_lang(3), st_obj_open(3), st_obj_file_start(3), st_objlist_append(3), st_sym_value(3)

       delim off

																   st_proc_addr(3)