st_sym_value(3)st_sym_value(3)NAME
st_sym_value, st_sym_type, st_sym_class, st_sym_to_file, st_sym_name,
st_sym_name_copy, st_free_name, st_sym_to_outer_scope_sym, st_end_sym,
st_proc_end_sym, st_external_name_sym, st_frame_offset_to_sym,
st_sym_size, st_is_sym_weak, st_is_sym_local, st_is_sym_global,
st_get_mangled_name_flag, st_set_mangled_name_flag - access information
about the symbols in an object, and access or set symbol name deman‐
gling controls
SYNOPSIS
#include <st.h>
st_status_t st_sym_value(
st_obj_t *obj,
st_sym_t sym,
unsigned long *value ); st_status_t st_sym_type(
st_obj_t *obj,
st_sym_t sym,
unsigned int *sym_type ); st_status_t st_sym_class(
st_obj_t *obj,
st_sym_t sym,
unsigned int *sym_class ); st_status_t st_sym_to_file(
st_obj_t *obj,
st_sym_t sym,
st_file_t *file ); st_status_t st_sym_name(
st_obj_t *obj,
st_sym_t sym,
char **name) ); st_status_t st_sym_name_copy(
st_obj_t *obj,
st_sym_t sym,
char *name_buf,
int buflen,
int *truncated ); void st_free_name(
st_obj_t *obj,
char *name ); st_status_t st_sym_to_outer_scope_sym(
st_obj_t *obj,
st_sym_t sym,
st_sym_t *osym ); st_status_t st_end_sym(
st_obj_t *obj,
st_sym_t sym,
st_sym_t *esym ); st_status_t st_proc_end_sym(
st_obj_t *obj,
st_sym_t sym,
st_sym_t *esym ); st_status_t st_external_name_sym(
st_obj_t *obj,
const char *name,
st_sym_t *osym ); st_status_t st_frame_offset_to_sym(
st_obj_t *obj,
st_proc_t proc,
int frame_offset,
st_sym_t *osym,
int *byte_offset ); st_status_t st_sym_size(
st_obj_t *obj,
st_sym_t sym,
unsigned long *size ); st_status_t st_is_sym_weak(
st_obj_t *obj,
st_sym_t symbol,
st_bool_t *weak ); st_status_t st_is_sym_local(
st_obj_t *obj,
st_sym_t symbol,
st_bool_t *local ); st_status_t st_is_sym_global(
st_obj_t *obj,
st_sym_t symbol,
st_bool_t *global ); st_status_t st_set_mangled_name_flag(
st_obj_t *obj,
unsigned int flag,
); st_status_t st_get_mangled_name_flag(
st_obj_t *obj,
unsigned int *flag,
);
LIBRARY
Symbol Table and Object File Access Library (libst.a)
PARAMETERS
Specifies an object handle, as returned by the st_obj_open() function.
Specifies a symbol handle. Specifies an address to which
st_sym_value() returns the value of the specified symbol. The value of
a symbol depends on its type and class. For procedures, data symbols,
or bss symbols, the value is the address. For members of structures or
unions, the value is the offset to the field from the start of the
structure. For local symbols or arguments, the value is its relative
offset from the procedure's frame pointer. Specifies an address to
which st_sym_type() returns the type of the specified symbol. Symbol
types are defined in /usr/include/symconst.h. Each symbol type defini‐
tion begins with the prefix st, for example, stProc. Specifies an
address to which st_sym_class() returns the class of the specified sym‐
bol. Symbol classes are defined in /usr/include/symconst.h. Each symbol
class definition begins with the prefix sc, for example, scText. Spec‐
ifies an address to which st_sym_to_file() returns the handle of the
file that contains the given symbol. Specifies an address to which
st_sym_name() returns a pointer to a null-terminated string containing
the name of the given symbol. Specifies the address of a buffer to
which st_sym_name_copy() returns a copy of the specified symbol's name.
Specifies the length of the buffer (name_buf) to which
st_sym_name_copy() returns a copy of the specified symbol's name. You
should add one for the name string's null terminator to this count.
Specifies an address to which st_sym_name_copy() returns the number of
characters by which the symbol name returned to name_buf exceeds the
number specified in buflen. If the name exceeds buflen characters,
st_sym_name_copy() truncates it. Specifies an address for a symbol
handle. st_sym_to_outer_scope_sym() returns the symbol handle of the
block or procedure that contains the specified symbol. st_exter‐
nal_name_sym() returns the symbol handle of the named external symbol.
st_frame_offset_to_sym() returns the symbol handle corresponding to the
specified frame offset in the given procedure. Specifies an address to
which st_end_sym() or st_proc_end_sym() returns the ending symbol han‐
dle of the block or procedure, respectively, that contains the speci‐
fied symbol. Specifies a positive number that is a relative offset
from the virtual frame pointer for a procedure (often the stack
pointer) that st_frame_offset_to_sym() uses to obtain a symbol handle.
Specifies an address to which st_frame_offset_to_sym() returns the off‐
set into the variable to which frame_offset corresponds. Specifies an
address to which st_sym_size() returns the size in bytes of the given
symbol. Specify Boolean variables for return values. Specifies an
address to which st_get_mangled_name_flag() returns the current state
of the specified object's name-demangling flags, or an address contain‐
ing the flag values that st_set_mangled_name_flag() is to write to the
specified object's name-demangling flags. Valid name-demangling flags
are defined in /usr/include/cmplrs/demangle_string.h.
DESCRIPTION
These functions return information about the symbols in an object. Sym‐
bols may represent files, procedures, or local or global symbols.
Return the value, type, and class of a given symbol. Returns the han‐
dle of the file that contains the given symbol. The st_sym_name()
function returns a pointer to a null-terminated string containing the
name of the given symbol. If the symbol represents a C++ name and name-
demangling is enabled (the default), st_sym_name() dynamically allo‐
cates the buffer in which it stores the name. Otherwise, it sets name
to the address of the string in the object. In either case, the caller
should not modify the returned name buffer, but instead should make
modifications to a copy of the name.
To release a buffer that may have been dynamically allocated by
st_sym_name(), use the st_free_name() function. Ensure that you
specify the same symbol handle to st_free_name() that you previ‐
ously specified to st_sym_name(). Otherwise, you may inadver‐
tently release memory used for some other purpose. Returns a
copy of the specified symbol name to a user-supplied buffer. If
the name string, including its null terminator, exceeds buflen
characters, st_sym_name_copy() truncates it, returning the num‐
ber of truncated characters in truncated. For C++ names, this
function is useful because it avoids returning dynamically allo‐
cated buffers that must later be released by calls to
st_free_name(). For non-C++ names, however, it involves more
overhead. Returns the symbol handle of the enclosing block or
procedure for the specified symbol. This function is helpful
when you are processing local symbols or alternate entries.
Return the ending symbol handle of the block or procedure,
respectively, containing the specified symbol. Returns the sym‐
bol handle for the named external symbol. Returns the symbol
corresponding to the specified frame offset in the given proce‐
dure. The frame offset must be a positive number and a relative
offset from the virtual frame pointer for a procedure. Fre‐
quently, but not always, this is the stack pointer. For example,
if an instruction references a local variable with 20($sp), then
the frame offset would be 20. The symbol that st_frame_off‐
set_to_sym() returns may be a parameter to the procedure or a
local symbol. The st_frame_offset_to_sym() function sets byte-
offset to the offset (always greater or equal to zero) into the
variable to which the frame_offset corresponds. The byte_offset
from a variable may span compiler temporaries on the stack. To
check this case, use st_sym_size() to obtain the size of the
returned symbol and compare it to the byte offset. Returns the
size in bytes of the specified symbol. These routines are Bool‐
ean functions that return a flag that indicates whether a given
symbol belongs to each category. Note that only global symbols
can be weak. If st_is_sym_weak() is passed a local symbol han‐
dle, it returns ST_E_INVALID_SYM to indicate that the given sym‐
bol cannot be weak. The st_get_mangled_name_flag function
returns the current state of the name-demangling flags for the
specified object.
The st_set_mangled_name_flag() function sets the name-demangling
flags for the specified object to the value contained in the
address specified in the flag parameter.
Name demangling is enabled or disabled at the object level only
for C++ files. By default, name demangling is enabled when an
object is opened. The name demangling flags have an effect on
the C++ name translations that are performed when functions such
as st_sym_name() are called. Valid name-demangling flags are
defined in /usr/include/cmplrs/demangle_string.h.
RETURN VALUES
All functions indicate success by returning a value of 0 (zero). A pos‐
itive 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
Header file that contains all definitions and function prototypes for
libst.a functions Header file that controls name-demangling operations
for C++ objects Header file that defines symbol types Header file that
defines symbol classes
SEE ALSO
Commands: atom(1)
Functions: libst_intro(3), st_addr_to_file(3), st_file_lang(3),
st_obj_calls(3), st_obj_open(3), st_obj_file_start(3),
st_objlist_append(3), st_proc_addr(3)st_sym_value(3)
