VxWorks API Reference : OS Libraries

loadLib

NAME

loadLib - object module loader

ROUTINES

loadModule( ) - load an object module into memory
loadModuleAt( ) - load an object module into memory

DESCRIPTION

This library provides a generic object module loading facility. Any supported format files may be loaded into memory, relocated properly, their external references resolved, and their external definitions added to the system symbol table for use by other modules and from the shell. Modules may be loaded from any I/O stream which allows repositioning of the pointer. This includes netDrv, nfs, or local file devices. It does not include sockets.

EXAMPLE

    fdX = open ("/devX/objFile", O_RDONLY);
    loadModule (fdX, LOAD_ALL_SYMBOLS);
    close (fdX);

This code fragment would load the object file "objFile" located on device "/devX/" into memory which would be allocated from the system memory pool. All external and static definitions from the file would be added to the system symbol table.

This could also have been accomplished from the shell, by typing:

    -> ld (1) </devX/objFile

INCLUDE FILE

loadLib.h

SEE ALSO

usrLib, symLib, memLib, VxWorks Programmer's Guide: Basic OS

---

OS Libraries : Routines

loadModule( )

NAME

loadModule( ) - load an object module into memory

SYNOPSIS

MODULE_ID loadModule
    (
    int              fd,      /* fd of file to load */
    int              symFlag  /* symbols to add to table (LOAD_[NO
    ALL]_SYMBOLS) */ GLOBAL
    )

DESCRIPTION

This routine loads an object module from the specified file, and places the code, data, and BSS into memory allocated from the system memory pool.

This call is equivalent to loadModuleAt( ) with NULL for the addresses of text, data, and BSS segments. For more details, see the manual entry for loadModuleAt( ).

RETURNS

MODULE_ID, or NULL if the routine cannot read the file, there is not enough memory, or the file format is illegal.

SEE ALSO

loadLib, loadModuleAt( )

---

OS Libraries : Routines

loadModuleAt( )

NAME

loadModuleAt( ) - load an object module into memory

SYNOPSIS

MODULE_ID loadModuleAt
    (
    int    fd,                /* fd from which to read module */
    int    symFlag,           /* symbols to add to table (LOAD_[NO
    char * *ppText,           /* load text segment at addr. pointed to by */
                              /* this ptr, return load addr. via this ptr */ 
    char * *ppData,           /* load data segment at addr. pointed to by */
                              /* this pointer, return load addr. via this */
                              /* ptr */ 
    char * *ppBss             /* load BSS segment at addr. pointed to by */
                              /* this pointer, return load addr. via this */
                              /* ptr */ 
    )

DESCRIPTION

This routine reads an object module from fd, and loads the code, data, and BSS segments at the specified load addresses in memory set aside by the user using malloc( ), or in the system memory partition as described below. The module is properly relocated according to the relocation commands in the file. Unresolved externals will be linked to symbols found in the system symbol table. Symbols in the module being loaded can optionally be added to the system symbol table.

LINKING UNRESOLVED EXTERNALS

As the module is loaded, any unresolved external references are resolved by looking up the missing symbols in the the system symbol table. If found, those references are correctly linked to the new module. If unresolved external references cannot be found in the system symbol table, then an error message ("undefined symbol: ...") is printed for the symbol, but the loading/linking continues. The partially resolved module is not removed, to enable the user to examine the module for debugging purposes. Care should be taken when executing code from the resulting module. Executing code which contains references to unresolved symbols may have unexpected results and may corrupt the system's memory.

Even though a module with unresolved symbols remains loaded after this routine returns, NULL will be returned to enable the caller to detect the failure programatically. To unload the module, the caller may either call the unload routine with the module name, or look up the module using the module name and then unload the module using the returned MODULE_ID. See the library entries for moduleLib and unldLib for details. The name of the module is the name of the file loaded with the path removed.

ADDING SYMBOLS TO THE SYMBOL TABLE

The symbols defined in the module to be loaded may be optionally added to the system symbol table, depending on the value of symFlag:

LOAD_NO_SYMBOLS

add no symbols to the system symbol table

LOAD_LOCAL_SYMBOLS

add only local symbols to the system symbol table

LOAD_GLOBAL_SYMBOLS

add only external symbols to the system symbol table

LOAD_ALL_SYMBOLS

add both local and external symbols to the system symbol table

HIDDEN_MODULE

do not display the module via moduleShow( ).

Obsolete symbols:

For backward compatibility with previous releases, the following symbols are also added to the symbol table to indicate the start of each segment: filename_text, filename_data, and filename_bss, where filename is the name associated with the fd. Note that these symbols are not available when the ELF format is used. Also they will disappear with the next VxWorks release. The moduleLib API should be used instead to get segment information.

RELOCATION

The relocation commands in the object module are used to relocate the text, data, and BSS segments of the module. The location of each segment can be specified explicitly, or left unspecified in which case memory will be allocated for the segment from the system memory partition. This is determined by the parameters ppText, ppData, and ppBss, each of which can have the following values:

NULL

no load address is specified, none will be returned;

A pointer to LD_NO_ADDRESS

no load address is specified, the return address is referenced by the pointer;

A pointer to an address

the load address is specified.

The ppText, ppData, and ppBss parameters specify where to load the text, data, and bss sections respectively. Each of these parameters is a pointer to a pointer; for example, **ppText gives the address where the text segment is to begin.

For any of the three parameters, there are two ways to request that new memory be allocated, rather than specifying the section's starting address: you can either specify the parameter itself as NULL, or you can write the constant LD_NO_ADDRESS in place of an address. In the second case, loadModuleAt( ) routine replaces the LD_NO_ADDRESS value with the address actually used for each section (that is, it records the address at *ppText, *ppData, or *ppBss).

The double indirection not only permits reporting the addresses actually used, but also allows you to specify loading a segment at the beginning of memory, since the following cases can be distinguished:

(1)	Allocate memory for a section (text in this example): ppText == NULL
(2)	Begin a section at address zero (the text section, below): *ppText == 0

Note that loadModule( ) is equivalent to this routine if all three of the segment-address parameters are set to NULL.

COMMON

Some host compiler/linker combinations use another storage class internally called "common". In the C language, uninitialized global variables are eventually put in the bss segment. However, in partially linked object modules they are flagged internally as "common" and the static linker (host) resolves these and places them in bss as a final step in creating a fully linked object module. However, the target loader is most often used to load partially linked object modules. When the target loader encounters a variable labeled "common", its behavior depends on the following flags :

LOAD_COMMON_MATCH_NONE

Allocate memory for the variable with malloc( ) and enter the variable in the target symbol table (if specified) at that address. This is the default.

LOAD_COMMON_MATCH_USER

Search for the symbol in the target symbol table, excluding the vxWorks image symbols. If several symbols exist, then the order of matching is: (1) bss, (2) data. If no symbol is found, act like the default.

LOAD_COMMON_MATCH_ALL

Search for the symbol in the target symbol table, including the vxWorks image symbols. If several symbols exist, then the order of matching is: (1) bss, (2) data. If no symbol is found, act like the default.

Note that most UNIX loaders have an option that forces resolution of the common storage while leaving the module relocatable (for example, with typical BSD UNIX loaders, use options "-rd").

EXAMPLES

Load a module into allocated memory, but do not return segment addresses:

    module_id = loadModuleAt (fd, LOAD_GLOBAL_SYMBOLS, NULL, NULL, NULL);

Load a module into allocated memory, and return segment addresses:

    pText = pData = pBss = LD_NO_ADDRESS;
    module_id = loadModuleAt (fd, LOAD_GLOBAL_SYMBOLS, &pText, &pData, &pBss);

Load a module to off-board memory at a specified address:

    pText = 0x800000;                 /* address of text segment        */
    pData = pBss = LD_NO_ADDRESS      /* other segments follow by default */
    module_id = loadModuleAt (fd, LOAD_GLOBAL_SYMBOLS, &pText, &pData, &pBss);

RETURNS

MODULE_ID, or NULL if the file cannot be read, there is not enough memory, the file format is illegal, or there were unresolved symbols.

SEE ALSO

loadLib, VxWorks Programmer's Guide: Basic OS