Content-type: text/html Man page of st_sym_value

st_sym_value

Section: C Library Functions (3)
Index Return to Main Contents
 

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 - Access information about the symbols in an object  

LIBRARY

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

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 );

 

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 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 definition begins with the prefix st: stProc, for example. 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: scText, for example. Specifies 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_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. Specifies an address to which st_end_sym or *Lst_proc_end_sym returns the ending symbol handle of the block or procedure, respectively, that contains the specified 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 offset 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.  

DESCRIPTION

These functions return information about the symbols in an object. Symbols may represent files, procedures, or local or global symbols.

The st_sym_value, st_sym_type, and st_sym_class functions return the value, type, and class of a given symbol.

The st_sym_to_file function returns the handle 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 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.

The st_sym_name_copy function 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. This function is useful in that, for C++ names, 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.

The st_sym_to_outer_scope_sym function returns the symbol handle of the enclosing block or procedure for the specified symbol. Thi function is helpful when you are processing local symbols or alternate entries. The st_end_sym and set_proc_end_sym functions return the ending symbol handle of the block or procedure, respectively, containing the specified symbol.

The st_external_name_sym function returns the symbol handle for the named external symbol.

The st_frame_offset_to_sym function 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. st_frame_offset_to_sym 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.

The st_sym_size function returns the size in bytes of the specified 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 operations for C++ objects Header file that defines symbol types Header file that defines symbol classes  

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_proc_addr(3)

delim off


 

Index

NAME
LIBRARY
SYNOPSIS
PARAMETERS
DESCRIPTION
RETURN VALUES
FILES
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:40:44 GMT, October 02, 2010