VxWorks Reference Manual : Libraries
moduleLib - object module management library
moduleCreate( ) - create and initialize a module
moduleDelete( ) - delete module ID information (use unld( ) to reclaim space)
moduleShow( ) - show the current status for all the loaded modules
moduleSegGet( ) - get (delete and return) the first segment from a module
moduleSegFirst( ) - find the first segment in a module
moduleSegNext( ) - find the next segment in a module
moduleCreateHookAdd( ) - add a routine to be called when a module is added
moduleCreateHookDelete( ) - delete a previously added module create hook routine
moduleFindByName( ) - find a module by name
moduleFindByNameAndPath( ) - find a module by file name and path
moduleFindByGroup( ) - find a module by group number
moduleIdListGet( ) - get a list of loaded modules
moduleInfoGet( ) - get information about an object module
moduleCheck( ) - verify checksums on all modules
moduleNameGet( ) - get the name associated with a module ID
moduleFlagsGet( ) - get the flags associated with a module ID
This library is a class manager, using the standard VxWorks class/object facilities. The library is used to keep track of which object modules have been loaded into VxWorks, to maintain information about object module segments associated with each module, and to track which symbols belong to which module. Tracking modules makes it possible to list which modules are currently loaded, and to unload them when they are no longer needed.
The module object contains the following information:
- name
- linked list of segments, including base addresses
and sizes
- symbol group number
- format of the object module (a.out, COFF, ECOFF, etc.)
- the symFlag passed to ld( ) when the module was
loaded. (For more information about symFlag and the
loader, see the manual entry for loadLib.)Multiple modules with the same name are allowed (the same module may be loaded without first being unloaded) but "find" functions find the most recently created module.
The symbol group number is a unique number for each module, used to identify the module's symbols in the symbol table. This number is assigned by moduleLib when a module is created.
In general, users will not access these routines directly, with the exception of moduleShow( ), which displays information about currently loaded modules. Most calls to this library will be from routines in loadLib and unldLib.
moduleLib.h
moduleLib, loadLib, Tornado User's Guide: Cross-Development
moduleCreate( ) - create and initialize a module
MODULE_ID moduleCreate ( char * name, /* module name */ int format, /* object module format */ int flags /* symFlag as passed to loader (see loadModuleAt()) */ )
This routine creates an object module descriptor.
The arguments specify the name of the object module file, the object module format, and an argument specifying which symbols to add to the symbol table. See the loadModuleAt( ) description of symFlag for possibles flags values.
Space for the new module is dynamically allocated.
MODULE_ID, or NULL if there is an error.
moduleDelete( ) - delete module ID information (use unld( ) to reclaim space)
STATUS moduleDelete ( MODULE_ID moduleId /* module to delete */ )
This routine deletes a module descriptor, freeing any space that was allocated for the use of the module ID.
This routine does not free space allocated for the object module itself -- this is done by unld( ).
OK or ERROR.
moduleShow( ) - show the current status for all the loaded modules
STATUS moduleShow ( char * moduleNameOrId, /* name or ID of the module to show */ int options /* display options */ )
This routine displays a list of the currently loaded modules and some information about where the modules are loaded.
The specific information displayed depends on the format of the object modules. In the case of a.out and ECOFF object modules, moduleShow( ) displays the start of the text, data, and BSS segments.
If moduleShow( ) is called with no arguments, a summary list of all loaded modules is displayed. It can also be called with an argument, moduleNameOrId, which can be either the name of a loaded module or a module ID. If it is called with either of these, more information about the specified module will be displayed.
OK or ERROR.
moduleLib, VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell
moduleSegGet( ) - get (delete and return) the first segment from a module
SEGMENT_ID moduleSegGet ( MODULE_ID moduleId /* module to get segment from */ )
This routine returns information about the first segment of a module descriptor, and then deletes the segment from the module.
A pointer to the segment ID, or NULL if the segment list is empty.
moduleSegFirst( ) - find the first segment in a module
SEGMENT_ID moduleSegFirst ( MODULE_ID moduleId /* module to get segment from */ )
This routine returns information about the first segment of a module descriptor.
A pointer to the segment ID, or NULL if the segment list is empty.
moduleSegNext( ) - find the next segment in a module
SEGMENT_ID moduleSegNext ( SEGMENT_ID segmentId /* segment whose successor is to be found */ )
This routine returns the segment in the list immediately following segmentId.
A pointer to the segment ID, or NULL if there is no next segment.
moduleCreateHookAdd( ) - add a routine to be called when a module is added
STATUS moduleCreateHookAdd ( FUNCPTR moduleCreateHookRtn /* routine called when module is added */ )
This routine adds a specified routine to a list of routines to be called when a module is created. The specified routine should be declared as follows:
void moduleCreateHook ( MODULE_ID moduleId /* the module ID */ )This routine is called after all fields of the module ID have been filled in.
Modules do not have information about their object segments when they are created. This information is not available until after the entire load process has finished.
OK or ERROR.
moduleLib, moduleCreateHookDelete( )
moduleCreateHookDelete( ) - delete a previously added module create hook routine
STATUS moduleCreateHookDelete ( FUNCPTR moduleCreateHookRtn /* routine called when module is added */ )
This routine removes a specified routine from the list of routines to be called at each moduleCreate( ) call.
OK, or ERROR if the routine is not in the table of module create hook routines.
moduleLib, moduleCreateHookAdd( )
moduleFindByName( ) - find a module by name
MODULE_ID moduleFindByName ( char * moduleName /* name of module to find */ )
This routine searches for a module with a name matching moduleName.
MODULE_ID, or NULL if no match is found.
moduleFindByNameAndPath( ) - find a module by file name and path
MODULE_ID moduleFindByNameAndPath ( char * moduleName, /* file name to find */ char * pathName /* path name to find */ )
This routine searches for a module with a name matching moduleName and path matching pathName.
MODULE_ID, or NULL if no match is found.
moduleFindByGroup( ) - find a module by group number
MODULE_ID moduleFindByGroup ( int groupNumber /* group number to find */ )
This routine searches for a module with a group number matching groupNumber.
MODULE_ID, or NULL if no match is found.
moduleIdListGet( ) - get a list of loaded modules
int moduleIdListGet ( MODULE_ID * idList, /* array of module IDs to be filled in */ int maxModules /* max modules idList can accommodate */ )
This routine provides the calling task with a list of all loaded object modules. An unsorted list of module IDs for no more than maxModules modules is put into idList.
The number of modules put into the ID list, or ERROR.
moduleInfoGet( ) - get information about an object module
STATUS moduleInfoGet ( MODULE_ID moduleId, /* module to return information about */ MODULE_INFO * pModuleInfo /* pointer to module info struct */ )
This routine fills in a MODULE_INFO structure with information about the specified module.
OK or ERROR.
moduleCheck( ) - verify checksums on all modules
STATUS moduleCheck ( int options /* validation options */ )
This routine verifies the checksums on the segments of all loaded modules. If any of the checksums are incorrect, a message is printed to the console, and the routine returns ERROR.
By default, only the text segment checksum is validated.
Bits in the options parameter may be set to control specific checks:
- MODCHECK_TEXT
- Validate the checksum for the TEXT segment (default).
- MODCHECK_DATA
- Validate the checksum for the DATA segment.
- MODCHECK_BSS
- Validate the checksum for the BSS segment.
- MODCHECK_NOPRINT
- Do not print a message (moduleCheck( ) still returns ERROR on failure.)
See the definitions in moduleLib.h
OK, or ERROR if the checksum is invalid.
moduleNameGet( ) - get the name associated with a module ID
char * moduleNameGet ( MODULE_ID moduleId )
This routine returns a pointer to the name associated with a module ID.
A pointer to the module name, or NULL if the module ID is invalid.
moduleFlagsGet( ) - get the flags associated with a module ID
int moduleFlagsGet ( MODULE_ID moduleId )
This routine returns the flags associated with a module ID.
The flags associated with the module ID, or NULL if the module ID is invalid.