VxWorks Reference Manual : Wind Foundation Classes
VXWSymTab - symbol table class
VXWSymTab::VXWSymTab( ) - create a symbol table
VXWSymTab::VXWSymTab( ) - create a symbol-table object
VXWSymTab::~VXWSymTab( ) - delete a symbol table
VXWSymTab::add( ) - create and add a symbol to a symbol table, including a group number
VXWSymTab::each( ) - call a routine to examine each entry in a symbol table
VXWSymTab::findByName( ) - look up a symbol by name
VXWSymTab::findByNameAndType( ) - look up a symbol by name and type
VXWSymTab::findByValue( ) - look up a symbol by value
VXWSymTab::findByValueAndType( ) - look up a symbol by value and type
VXWSymTab::remove( ) - remove a symbol from a symbol table
This class 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.
If you use the VXWSymTab class to manage symbol tables local to your own applications, the values for SYM_TYPE objects are completely arbitrary; you can use whatever one-byte integers are appropriate for your application.
If the VxWorks system symbol table is configured into your target system, you can use the VXWSymTab class to manipulate it based on its symbol-table ID, recorded in the global sysSymTbl; see VXWSymTab::VXWSymTab( ) to construct an object based on this global. In the VxWorks target-resident global symbol table, the values for SYM_TYPE are N_ABS, N_TEXT, N_DATA, and N_BSS (defined in a_out.h); these are all even numbers, and any of them may be combined (via boolean or) with N_EXT (1). These values originate in the section names for a.out object code format, but the VxWorks system symbol table uses them as symbol types across all object formats. (The VxWorks system symbol table also occasionally includes additional types, in some object formats.)
All operations on a symbol table are interlocked by means of a mutual-exclusion semaphore in the symbol table structure.
Symbols are added to a symbol table with VXWSymTab::add( ). Each symbol in the symbol table has a name, a value, and a type. Symbols are removed from a symbol table with VXWSymTab::remove( ).
Symbols can be accessed by either name or value. The routine VXWSymTab::findByName( ) searches the symbol table for a symbol of a specified name. The routine VXWSymTab::findByValue( ) finds the symbol with the value closest to a specified value. The routines VXWSymTab::findByNameAndType( ) and VXWSymTab::findByValueAndType( ) 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 for fast look-up by name, for instance with VXWSymTab::findByName( ). The size of the hash table is specified during the creation of a symbol table. Look-ups by value, such as with VXWSymTab::findByValue( ), must search the table linearly; these look-ups can thus be much slower.
The routine VXWSymTab::each( ) 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. Whether or not symbol tables can accept name clashes is set by a parameter when the symbol table is created with VXWSymTab::VXWSymTab( ). If name clashes are not allowed, VXWSymTab::add( ) returns an error if there is an attempt to add a symbol with identical name and type. If name clashes are allowed, adding multiple symbols with the same name and type is not an error. In such cases, VXWSymTab::findByName( ) returns the value most recently added, although all versions of the symbol can be found by VXWSymTab::each( ).
vxwSymLib.h
VXWSymTab, VXWModule
VXWSymTab::VXWSymTab( ) - create a symbol table
VXWSymTab ( int hashSizeLog2, BOOL sameNameOk, PART_ID symPartId )
This constructor creates and initializes a symbol table with a hash table of a specified size. The size of the hash table is specified as a power of two. For example, if hashSizeLog2 is 6, a 64-entry hash table is created.
If sameNameOk is FALSE, attempting to add a symbol with the same name and type as an already-existing symbol results in an error.
Memory for storing symbols as they are added to the symbol table will be allocated from the memory partition symPartId. The ID of the system memory partition is stored in the global variable memSysPartId, which is declared in memLib.h.
N/A
VXWSymTab::VXWSymTab( ) - create a symbol-table object
VXWSymTab ( SYMTAB_ID aSymTabId )
This constructor creates a symbol table object based on an existing symbol table. For example, the following statement creates a symbol-table object for the VxWorks system symbol table (assuming you have configured a target-resident symbol table into your VxWorks system):
VXWSymTab sSym; ... sSym = VXWSymTab (sysSymTbl);
VXWSymTab::~VXWSymTab( ) - delete a symbol table
~VXWSymTab ()
This routine deletes a symbol table; it deallocates all memory associated with its symbol table, including the hash table, and marks the table as invalid.
Deletion of a table that still contains symbols throws an error. Successful deletion includes the deletion of the internal hash table and the deallocation of memory associated with the table. The table is marked invalid to prohibit any future references.
OK, or ERROR if the table still contains symbols.
VXWSymTab::add( ) - create and add a symbol to a symbol table, including a group number
STATUS add ( char * name, char * value, SYM_TYPE type, UINT16 group )
This routine allocates a symbol name and adds it to its symbol table with the specified parameters value, type, and group. The group parameter specifies the group number assigned to a module when it is loaded on the target; see the manual entry for moduleLib.
OK, or ERROR if there is insufficient memory for the symbol to be allocated.
VXWSymTab::each( ) - call a routine to examine each entry in a symbol table
SYMBOL * each ( FUNCPTR routine, int routineArg )
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 must have the following type signature:
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 must return TRUE if VXWSymTab::each( ) is to continue calling it for each entry, or FALSE if it is done and VXWSymTab::each( ) can exit.
A pointer to the last symbol reached, or NULL if all symbols are reached.
VXWSymTab::findByName( ) - look up a symbol by name
STATUS findByName ( char * name, char * *pValue, SYM_TYPE * pType ) const
This routine searches its 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 cannot be found.
VXWSymTab::findByNameAndType( ) - look up a symbol by name and type
STATUS findByNameAndType ( char * name, char * *pValue, SYM_TYPE * pType, SYM_TYPE goalType, SYM_TYPE mask ) const
This routine searches its symbol table for a symbol matching both name and type (name and goalType). 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 is not found.
VXWSymTab::findByValue( ) - look up a symbol by value
STATUS findByValue ( UINT value, char * name, int * pValue, SYM_TYPE * pType ) const
This routine searches its 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.
VXWSymTab::findByValueAndType( ) - look up a symbol by value and type
STATUS findByValueAndType ( UINT value, char * name, int * pValue, SYM_TYPE * pType, SYM_TYPE goalType, SYM_TYPE mask ) const
This routine searches a symbol table for a symbol matching both value and type (value and goalType). 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.
VXWSymTab::remove( ) - remove a symbol from a symbol table
STATUS remove ( char * name, SYM_TYPE type )
This routine removes a symbol of matching name and type from its symbol table. The symbol is deallocated if found. Note that VxWorks symbols in a standalone VxWorks image (where the symbol table is linked in) cannot be removed.
OK, or ERROR if the symbol is not found or could not be deallocated.