 |
Index for
Section 3 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
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 demangling
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
obj Specifies an object handle, as returned by the st_obj_open() function.
sym Specifies a symbol handle.
value
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.
sym_type
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 definition begins with the prefix st, for example,
stProc.
sym_class
Specifies an address to which st_sym_class() returns the class of the
specified symbol. Symbol classes are defined in
/usr/include/symconst.h. Each symbol class definition begins with the
prefix sc, for example, scText.
file
Specifies an address to which st_sym_to_file() returns the handle of
the file that contains the given symbol.
name
Specifies an address to which st_sym_name() returns a pointer to a
null-terminated string containing the name of the given symbol.
name_buf
Specifies the address of a buffer to which st_sym_name_copy() returns a
copy of the specified symbol's name.
buflen
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.
truncated
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.
osym
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_external_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.
esym
Specifies an address to which st_end_sym() or st_proc_end_sym() returns
the ending symbol handle of the block or procedure, respectively, that
contains the specified symbol.
frame_offset
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.
byte_offset
Specifies an address to which st_frame_offset_to_sym() returns the
offset into the variable to which frame_offset corresponds.
size
Specifies an address to which st_sym_size() returns the size in bytes
of the given symbol.
weak, local, global
Specify Boolean variables for return values.
flag
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 containing 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. Symbols
may represent files, procedures, or local or global symbols.
st_sym_value, st_sym_type, and st_sym_class
Return the value, type, and class of a given symbol.
st_sym_to_file
Returns the handle of the file that contains the given symbol.
st_sym_name, st_free_name
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 allocates 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 previously
specified to st_sym_name(). Otherwise, you may inadvertently release
memory used for some other purpose.
st_sym_name_copy
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 number of
truncated characters in truncated. For C++ names, this function is
useful because it avoids returning dynamically allocated buffers that
must later be released by calls to st_free_name(). For non-C++ names,
however, it involves more overhead.
st_sym_to_outer_scope_sym
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.
st_end_sym, st_proc_end_sym
Return the ending symbol handle of the block or procedure,
respectively, containing the specified symbol.
st_external_name_sym
Returns the symbol handle for the named external symbol.
st_frame_offset_to_sym
Returns the symbol corresponding to the specified frame offset in the
given procedure. The frame offset must be a positive number and a
relative offset from the virtual frame pointer for a procedure.
Frequently, 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_offset_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.
st_sym_size
Returns the size in bytes of the specified symbol.
st_is_sym_weak, st_is_sym_local, st_is_sym_global
These routines are Boolean 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
handle, it returns ST_E_INVALID_SYM to indicate that the given symbol
cannot be weak.
st_get_mangled_name_flag, st_set_mangled_name_flag
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 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
/usr/include/symconst.h
Header file that defines symbol types
/usr/include/symconst.h
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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|