VxWorks Reference Manual : Libraries
symLib - symbol table subroutine library
symLibInit( ) - initialize the symbol table library
symTblCreate( ) - create a symbol table
symTblDelete( ) - delete a symbol table
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
symFindByValueAndType( ) - 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.
If you use the symLib subroutines 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 you use the symLib subroutines to manipulate the VxWorks system symbol table (whose ID is recorded in the global sysSymTbl), 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.)
Tables are created with symTblCreate( ), which returns a symbol table ID. This ID serves as a handle for symbol table operations, including the adding to, removing from, and searching of tables. All operations on a symbol table are interlocked by means of a mutual-exclusion semaphore in the symbol table structure. Tables are deleted with symTblDelete( ).
Symbols are added to a symbol table with symAdd( ). Each symbol in the symbol table has a name, a value, and a type. Symbols are removed from a symbol table 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 for fast look-up by name, e.g., by symFindByName( ). The size of the hash table is specified during the creation of a symbol table. Look-ups by value, e.g., symFindByValue( ), must search the table linearly; these look-ups can thus 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. Whether or not symbol tables can accept name clashes is set by a parameter when the symbol table is created with symTblCreate( ). If name clashes are not allowed, symAdd( ) will return 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 will be permitted. In such cases, symFindByName( ) will return the value most recently added, although all versions of the symbol can be found by symEach( ).
symLib.h
symLibInit( ) - initialize the symbol table library
STATUS symLibInit (void)
This routine initializes the symbol table package. If the configuration macro INCLUDE_SYM_TBL is defined, symLibInit( ) is called by the root task, usrRoot( ), in usrConfig.c.
OK, or ERROR if the library could not be initialized.
symTblCreate( ) - create a symbol table
SYMTAB_ID symTblCreate ( int hashSizeLog2, /* size of hash table as a power of 2 */ BOOL sameNameOk, /* allow 2 symbols of same name & type */ PART_ID symPartId /* memory part ID for symbol allocation */ )
This routine 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.
Symbol table ID, or NULL if memory is insufficient.
symTblDelete( ) - delete a symbol table
STATUS symTblDelete ( SYMTAB_ID symTblId /* ID of symbol table to delete */ )
This routine deletes a specified symbol table. It deallocates all associated memory, including the hash table, and marks the table as invalid.
Deletion of a table that still contains symbols results in 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 symbol table ID is invalid.
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 manual entry for moduleLib.
OK, or ERROR if the symbol table is invalid or there is insufficient memory for the symbol to be allocated.
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. 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.
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.
To search the global VxWorks symbol table, specify sysSymTbl as symTblId.
OK, or ERROR if the symbol table ID is invalid or the symbol cannot be found.
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.
To search the global VxWorks symbol table, specify sysSymTbl as symTblId.
OK, or ERROR if the symbol table ID is invalid or the symbol is not found.
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.
For the name buffer, allocate MAX_SYS_SYM_LEN + 1 bytes. The value MAX_SYS_SYM_LEN is defined in sysSymTbl.h.
To search the global VxWorks symbol table, specify sysSymTbl as symTblId.
OK, or ERROR if value is less than the lowest value in the table.
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.
For the name buffer, allocate MAX_SYS_SYM_LEN + 1 bytes. The value MAX_SYS_SYM_LEN is defined in sysSymTbl.h.
To search the global VxWorks symbol table, specify sysSymTbl as symTblId.
OK, or ERROR if value is less than the lowest value in the table.
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.