Tornado API Reference : Target Server Internal Routines
symlib - symbol table subroutine library
symAdd( ) - create and add a symbol to a symbol table, including a group number
symRemove( ) - remove a symbol from a symbol table
symFindByName( ) - look up a symbol by name
symFindByNameAndType( ) - look up a symbol by name and type
symFindByValue( ) - look up a symbol by value
symByValueFind( ) - look up a symbol by value
symFindByValueAndType( ) - look up a symbol by value and type
symByValueAndTypeFind( ) - look up a symbol by value and type
symEach( ) - call a routine to examine each entry in a symbol table
This library provides facilities for managing symbol tables. A symbol table associates a name and type with a value. A name is simply an arbitrary, null-terminated string. A symbol type is a small integer (typedef SYM_TYPE), and its value is a character pointer. Though commonly used as the basis for object loaders, symbol tables may be used whenever efficient association of a value with a name is needed.
The target server uses only one symbol table. This table is accessed through the global variable tgtSymTbl, which is of the type SYMTAB_ID.
Each symbol in the symbol table has a name, a value, and a type. Symbols are added to a symbol table with symAdd( ) and removed with symRemove( ).
Symbols can be accessed by either name or value. The routine symFindByName( ) searches the symbol table for a symbol of a specified name. The routine symFindByValue( ) finds the symbol with the value closest to a specified value. The routines symFindByNameAndType( ) and symFindByValueAndType( ) allow the symbol type to be used as an additional criterion in the searches.
Symbols in the symbol table are hashed by name into a hash table to optimize looking up symbols by name with symFindByName( ). The size of the hash table is specified during the creation of a symbol table. Looking up symbols by value, with symFindByValue( ) for example, requires a linear search of the table, which can be much slower.
The routine symEach( ) allows each symbol in the symbol table to be examined by a user-specified function.
Name clashes occur when a symbol added to a table is identical in name and type to a previously added symbol. By default name clashes are allowed so adding multiple symbols with the same name and type is permitted. symFindByName( ) returns the value most recently added, although all versions of the symbol can be found by symEach( ).
symLib.h
symlib, loadlib, API Programmer's Guide: Object Module Loader
symAdd( ) - create and add a symbol to a symbol table, including a group number
STATUS symAdd ( SYMTAB_ID symTblId, /* symbol table to add symbol to */ char * name, /* pointer to symbol name string */ char * value, /* symbol address */ SYM_TYPE type, /* symbol type */ UINT16 group /* symbol group */ )
This routine allocates a symbol name and adds it to a specified symbol table symTblId with the specified parameters value, type, and group. The group parameter specifies the group number assigned to a module when it is loaded; see the reference entry for the VxWorks library moduleLib.
OK or ERROR if the symbol table is invalid or there is insufficient memory for the symbol to be allocated.
symlib, API Programmer's Guide: Object Module Loader
symRemove( ) - remove a symbol from a symbol table
STATUS symRemove ( SYMTAB_ID symTblId, /* symbol tbl to remove symbol from */ char * name, /* name of symbol to remove */ SYM_TYPE type /* type of symbol to remove */ )
This routine removes a symbol of matching name and type from a specified symbol table. The symbol is deallocated if found.
OK or ERROR if the symbol is not found or could not be deallocated.
symlib, API Programmer's Guide: Object Module Loader
symFindByName( ) - look up a symbol by name
STATUS symFindByName ( SYMTAB_ID symTblId, /* ID of symbol table to look in */ char * name, /* symbol name to look for */ char * * pValue, /* where to put symbol value */ SYM_TYPE * pType /* where to put symbol type */ )
This routine searches a symbol table for a symbol matching a specified name. If the symbol is found, its value and type are copied to pValue and pType. If multiple symbols have the same name but differ in type, the routine chooses the matching symbol most recently added to the symbol table.
OK or ERROR if the symbol table ID is invalid or the symbol cannot be found.
symlib, API Programmer's Guide: Object Module Loader
symFindByNameAndType( ) - look up a symbol by name and type
STATUS symFindByNameAndType ( SYMTAB_ID symTblId, /* ID of symbol table to look in */ char * name, /* symbol name to look for */ char * * pValue, /* where to put symbol value */ SYM_TYPE * pType, /* where to put symbol type */ SYM_TYPE sType, /* symbol type to look for */ SYM_TYPE mask /* bits in sType to pay attention to */ )
This routine searches a symbol table for a symbol matching both name and type (name and sType). If the symbol is found, its value and type are copied to pValue and pType. The mask parameter can be used to match sub-classes of type.
OK or ERROR if the symbol table ID is invalid or the symbol is not found.
symlib, API Programmer's Guide: Object Module Loader
symFindByValue( ) - look up a symbol by value
STATUS symFindByValue ( SYMTAB_ID symTblId, /* ID of symbol table to look in */ UINT value, /* value of symbol to find */ char * name, /* where to put symbol name string */ int * pValue, /* where to put symbol value */ SYM_TYPE * pType /* where to put symbol type */ )
This routine searches a symbol table for a symbol matching a specified value. If there is no matching entry, it chooses the table entry with the next lower value. The symbol name (with terminating EOS), the actual value, and the type are copied to name, pValue, and pType.
OK or ERROR if value is less than the lowest value in the table.
symlib, API Programmer's Guide: Object Module Loader
symByValueFind( ) - look up a symbol by value
STATUS symByValueFind ( SYMTAB_ID symTblId, /* ID of symbol table to look in */ UINT value, /* value of symbol to find */ char * * name, /* where to put symbol name string */ int * pValue, /* where to put symbol value */ SYM_TYPE * pType /* where to put symbol type */ )
This routine searches a symbol table for a symbol matching a specified value. If there is no matching entry, it chooses the table entry with the next lower value. The symbol name (with terminating EOS), the actual value, and the type are copied to name, pValue, and pType. name is a pointer allocated by the function and the memory must be freed after the use of name.
OK or ERROR if value is less than the lowest value in the table.
symlib, API Programmer's Guide: Object Module Loader
symFindByValueAndType( ) - look up a symbol by value and type
STATUS symFindByValueAndType ( SYMTAB_ID symTblId, /* ID of symbol table to look in */ UINT value, /* value of symbol to find */ char * name, /* where to put symbol name string */ int * pValue, /* where to put symbol value */ SYM_TYPE * pType, /* where to put symbol type */ SYM_TYPE sType, /* symbol type to look for */ SYM_TYPE mask /* bits in sType to pay attention to */ )
This routine searches a symbol table for a symbol matching both value and type (value and sType). If there is no matching entry, it chooses the table entry with the next lower value. The symbol name (with terminating EOS), the actual value, and the type are copied to name, pValue, and pType. The mask parameter can be used to match sub-classes of type.
OK or ERROR if value is less than the lowest value in the table.
symlib, API Programmer's Guide: Object Module Loader
symByValueAndTypeFind( ) - look up a symbol by value and type
STATUS symByValueAndTypeFind ( SYMTAB_ID symTblId, /* ID of symbol table to look in */ UINT value, /* value of symbol to find */ char * * ppName, /* where to put symbol name string */ int * pValue, /* where to put symbol value */ SYM_TYPE * pType, /* where to put symbol type */ SYM_TYPE sType, /* symbol type to look for */ SYM_TYPE mask /* bits in sType to pay attention to */ )
This routine searches a symbol table for a symbol matching both value and type (value and sType). If there is no matching entry, it chooses the table entry with the next lower value. The symbol name (with terminating EOS), the actual value, and the type are copied to name, pValue, and pType. The mask parameter can be used to match sub-classes of type. name is a pointer allocated by the function and the memory must be freed after the use of name.
OK or ERROR if value is less than the lowest value in the table.
symlib, API Programmer's Guide: Object Module Loader
symEach( ) - call a routine to examine each entry in a symbol table
SYMBOL * symEach ( SYMTAB_ID symTblId, /* pointer to symbol table */ FUNCPTR routine, /* func to call for each tbl entry */ int routineArg /* arbitrary user-supplied arg */ )
This routine calls a user-supplied routine to examine each entry in the symbol table; it calls the specified routine once for each entry. The routine should be declared as follows:
BOOL routine ( char *name, /* entry name */ int val, /* value associated with entry */ SYM_TYPE type, /* entry type */ int arg, /* arbitrary user-supplied arg */ UINT16 group /* group number */ )The user-supplied routine should return TRUE if symEach( ) is to continue calling it for each entry or FALSE if it is done and symEach( ) can exit.
A pointer to the last symbol reached or NULL if all symbols are reached.
symlib, API Programmer's Guide: Object Module Loader