VxWorks Reference Manual : 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

loadLib, usrLib, symLib, memLib, VxWorks Programmer's Guide: Basic 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 | LOCAL | 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( )

---

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 | LOCAL | GLOBAL | */
    char * *ppText, /* load text segment at addr. pointed to by this ptr, */
                    /* load addr. via this ptr */
    char * *ppData, /* load data segment at addr. pointed to by this */
                    /* return load addr. via this ptr */
    char * *ppBss   /* load BSS segment at addr. pointed to by this pointer, */
                    /* 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. In this case, NULL will be returned after the module is loaded.

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( ).

In addition, 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.

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 internally use another storage class known as 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 VxWorks loader is most often used to load partially linked object modules. When the VxWorks loader encounters a variable labeled as common, memory for the variable is allocated, with malloc( ), and the variable is entered in the system symbol table (if specified) at that address. Note that most UNIX loaders have an option that forces resolution of the common storage while leaving the module relocatable (e.g., 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, or the file format is illegal.

SEE ALSO

loadLib, VxWorks Programmer's Guide: Basic OS