Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

30    Loader

System Management

Exploring Palm OS®

The Program Loader is responsible for loading and unloading executable programs in the calling process. It also provides the means for retrieving information about executable modules and means for patching shared library entries. This chapter provides reference material for the loader as well as the dynamic linker, which links executables with shared libraries. The contents of this chapter are organized into the following sections:

Loader Structures and Types
Loader Constants
Loader Launch Codes
Loader Functions and Macros
Application-Defined Functions

The header file Loader.h declares the API that this chapter describes.

See Chapter 6, "Shared Libraries," for guidance on using, creating, and patching shared libraries.

Loader Structures and Types ^TOP^

SysModuleInfoType Struct ^TOP^

Purpose

Contains module information retrieved with SysGetModuleInfo().

Declared In

Loader.h

Prototype

typedef struct SysModuleInfoType {
   uint32_t revision;
   uint32_t entries;
   uint32_t dataSize;
   uint32_t minArch;
   uint32_t minOS;
   uint32_t currArch;
   uint32_t currOS;
} SysModuleInfoType

Fields

revision
The module revision number specified as a pslib command-line parameter when the module was built.
entries
The total number of entry points exported by this module.
dataSize
The amount of memory, in bytes, needed to hold the module's data segment.
minArch
The minimum required processor architecture.
minOS
The minimum required OS version.
currArch
The processor architecture of the device on which this is running.
currOS
The OS version of the device on which this is running.

SysPatchInfoType Struct ^TOP^

Purpose

Accompanies a sysPatchLaunchCmdSetInfo launch code and identifies both the shared library being patched and the patch's location within the call chain.

Declared In

Loader.h

Prototype

typedef struct SysPatchInfoType {
   uint32_t refNum;
   uint32_t type;
   uint32_t creator;
   uint16_t rsrcID;
   uint16_t reserved;
   uint32_t index;
   status_t (*sysGetNextPatchP) (uint32_t,
      uint32_t, uint32_t, void **);
} SysPatchInfoType

Fields

refNum
Reference number identifying the patched shared library.
type
The type of the database that contains the shared library.
creator
The creator ID of the database that contains the shared library.
rsrcID
The resource ID of the shared library resource containing the code for the executable module being patched.
reserved
Reserved for future use.
index
An index that identifies this patch's position within the call chain. The first patch in the call chain has index number zero.
sysGetNextPatchP
Pointer to a function that retrieves the address of the next patching procedure in a patched call chain.

Comments

This structure accompanies a sysPatchLaunchCmdSetInfo launch code. Both are sent to a patch when the shared library that it patches is being loaded. Upon receipt of sysPatchLaunchCmdSetInfo, the patch will likely want to use the information in this structure to set aside pointers to functions in the next patch in the call chain. This allows the patch, after it has done its work, to invoke the next patch in the chain.

For sample code showing how a patch can record function addresses from in the next patch in the chain, see Listing 6.3.

Loader Constants ^TOP^

Miscellaneous Loader Constants ^TOP^

Purpose

Loader.h declares these constants.

Declared In

Loader.h

Constants

#define sysDoNotVerifySignature ((uint32_t)0x00000001)
A flag that can be passed to SysLoadModule() so that the program loader doesn't perform verification of the digital signature on the executable module even if the security property of the calling process requires that the digital signature be verified. This behavior is useful for certain type of applications—like web browsers—that have their own ways of verifying the integrity of downloaded programs.
#define sysEntryNumMain ((uint32_t)0xffffffff)
Pass this as the starting entry number parameter of SysGetEntryAddresses() to retrieve only the address of the main entry point.

Loader Launch Codes ^TOP^

sysPatchLaunchCmdClearInfo ^TOP^

Purpose

Informs a patch that a target shared library has been unloaded.

Declared In

CmnLaunchCodes.h

Prototype

#define sysPatchLaunchCmdClearInfo 0x7ff3


Parameters

The cmdPBP parameter for this launch code is a pointer to a SysPatchInfoType structure.

Comments

A patch's PilotMain() function receives this launch code once for each of the shared libraries it patches. Thus, if a given patch patches multiple shared libraries, it will receive this launch code multiple times.

See Also

sysPatchLaunchCmdSetInfo

sysPatchLaunchCmdSetInfo ^TOP^

Purpose

Informs a patch that one of the shared libraries it wants to patch is being loaded.

Declared In

CmnLaunchCodes.h

Prototype

#define sysPatchLaunchCmdSetInfo 0x7ffb


Parameters

The cmdPBP parameter for this launch code is a pointer to a SysPatchInfoType structure.

Comments

A patch's PilotMain() function receives this launch code once for each of the shared libraries it patches. Thus, if a given patch patches multiple shared libraries, it will receive this launch code multiple times.

This launch code provides the patch with a good opportunity to retrieve and save addresses of functions in the next patch in the call chain.

For sample code showing how a patch can record function addresses from in the next patch in the chain, see Listing 6.3.

See Also

SysGetModuleGlobals(), sysPatchLaunchCmdSetInfo

Loader Functions and Macros ^TOP^

SysGetEntryAddresses Function ^TOP^

Purpose

Retrieve addresses of one or more entry points exported by a loaded executable module.

Declared In

Loader.h

Prototype

status_t SysGetEntryAddresses (
   uint32_t refNum,
   uint32_t startEntryNum,
   uint32_t numEntries,
   void **addressP
)

Parameters

refNum
Reference number of the executable module as returned by a call to SysLoadModule().
startEntryNum
Entry number of the first of numEntries entry point addresses to be retrieved, or sysEntryNumMain to retrieve only the address of the main entry point. Exported entry point index values begin at zero.
numEntries
Total number of entry point addresses to retrieve. If startEntryNum is sysEntryNumMain, this parameter is ignored.
addressP
Pointer to a buffer that receives the returned addresses. The size of this buffer should be no less than numEntries*4 bytes.

Returns

Returns errNone if the operation succeeded, or one of the following otherwise:

sysErrParamErr
refNum doesn't reference a loaded shared library, addressP is NULL, or either startEntryNum or (startEntryNum + numEntries - 1) is outside the range of exported entry points.

Comments

A shared library can have multiple exported entries, each identified by an entry number assigned when the shared library is built. Entry numbers are assigned in the shared library definition file (SLD), where the names of exported entries are listed in the order of increasing entry numbers starting from zero.

See Also

SysGetModuleGlobals()

SysGetModuleDatabase Function ^TOP^

Purpose

Retrieve the database ID, an open reference, or both for a database that contains a loaded executable module.

Declared In

Loader.h

Prototype

status_t SysGetModuleDatabase (
   uint32_t refNum,
   DatabaseID *dbIDP,
   DmOpenRef *openRefP
)

Parameters

refNum
Reference number of the loaded executable module as returned by a call to SysLoadModule().
dbIDP
Database ID of the database that contains the executable module. Pass NULL for this parameter if you don't need the database ID.
openRefP
Open reference of the database that contains the executable module. Pass NULL for this parameter if you don't need the reference.

Returns

Returns errNone if the operation succeeded, or one of the following otherwise:

sysErrParamErr
refNum doesn't identify a loaded executable module.
sysErrNoFreeResource
openRefP is not NULL and the database that contains the executable module identified by refNum could not be opened.

Comments


WARNING! Do not call DmCloseDatabase() with the DmOpenRef you obtain from this function. The referenced database was opened by the system in read-only mode with overlays. It will be closed automatically when the module is unloaded.

See Also

SysGetModuleInfo(), SysGetModuleInfoByDatabaseID()

SysGetModuleGlobals Function ^TOP^

Purpose

Retrieve the address of the C global structure or the address of the data segment of a loaded executable module.

Declared In

Loader.h

Prototype

status_t SysGetModuleGlobals (
   uint32_t refNum,
   Boolean wantStructure,
   void **globalsP
)

Parameters

refNum
Reference number of an executable module as returned by a call to SysLoadModule().
wantStructure
Pass true to retrieve the base address of the C global structure, false to retrieve the address of the executable module's data segment.
globalsP
Pointer to a memory location into which the address of the C global structure or data segment is to be written.

Returns

Returns errNone if the operation succeeded. Returns one of the following otherwise:

sysErrNotSupported
The executable module specified by refNum doesn't have a C global structure or doesn't allow it to be retrieved. In this case, the address of the module's data segment will returned in *globalsP. This error can be returned only when wantStructure is true.
sysErrParamErr
refNum doesn't reference a loaded shared library. The memory pointed to by addressP is set to NULL.

Comments

This function provides an indirect way for an executable module to access another executable module's global data. Patches can utilize this function to gain access to the globals of the original shared library.

Whether SysGetModuleGlobals() is able to return the address of the globals structure depends on whether the module identified by refNum defines such a structure and whether it returns the structure's address in response to the sysLaunchCmdGetGlobals launch code. SysGetModuleGlobals() returns sysErrNotSupported if wantStructure is true and the module doesn't allow the globals structure address to be retrieved.

Note that if you retrieve the address of the executable module's data segment, you must possess sufficient knowledge of the memory map of the module's data segment in order to access data located at particular offsets.

If *globalsP is NULL after retrieving the base address of the module's data segment, the executable module has no static data.

See Also

SysGetEntryAddresses()

SysGetModuleInfo Function ^TOP^

Purpose

Retrieve information about an executable module, given the type and creator of the database containing the executable module.

Declared In

Loader.h

Prototype

status_t SysGetModuleInfo (
   uint32_t dbType,
   uint32_t dbCreator,
   uint16_t rsrcID,
   SysModuleInfoType *infoP
)

Parameters

dbType
Type of the database that contains the executable module.
dbCreator
Creator ID of the database that contains the executable module.
rsrcID
ID number of the resources in the database that contain the code, data, and relocation information of the executable module.
infoP
Pointer to a SysModuleInfoType structure into which the module information is written.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

sysErrModuleNotFound
Module not found.
sysErrModuleInvalid
Code resource has an invalid or corrupted format.

Comments

This function is usually called by a client to get information about an executable module before actually loading it. The information returned includes the module's revision number, the total number of exported entries, and the size of the module's data segment.

See Also

SysGetModuleDatabase(), SysGetModuleInfoByDatabaseID(), SysLoadModule()

SysGetModuleInfoByDatabaseID Function ^TOP^

Purpose

Retrieve information about an executable module, given the database ID of the database containing the executable module.

Declared In

Loader.h

Prototype

status_t SysGetModuleInfoByDatabaseID (
   DatabaseID dbID,
   uint16_t rsrcID,
   SysModuleInfoType *infoP
)

Parameters

dbID
Database ID of the database that contains the executable module.
rsrcID
ID number of the resources in the database that contain the code, data and relocation information of the executable module.
infoP
Pointer to a SysModuleInfoType structure into which the module information is written.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

sysErrModuleNotFound
Module not found.
sysErrModuleInvalid
Code resource has an invalid or corrupted format.

Comments

This function is usually called by a client to get information about an executable module before actually loading it. The information returned includes the module's revision number, the total number of exported entries, and the size of the module's data segment.

See Also

SysGetModuleDatabase(), SysGetModuleInfo(), SysLoadModuleByDatabaseID()

SysGetRefNum Function ^TOP^

Purpose

Retrieve the reference number of the calling module.

Declared In

Loader.h

Prototype

uint32_t SysGetRefNum (
   void
)

Parameters

None.

Returns

Reference number of the calling module.

Comments

This function is often used along with SysGetModuleDatabase() to retrieve information about the database that contains the calling module. The reference number returned by this function has the same value that was returned by SysLoadModule() when the module was loaded.

SysLoadModule Function ^TOP^

Purpose

Load an executable module and make it ready for execution in the calling process, given the type and creator of the database that contains the executable module and the resource ID of the resource containing the executable module.

Declared In

Loader.h

Prototype

status_t SysLoadModule (
   uint32_t dbType,
   uint32_t dbCreator,
   uint16_t rsrcID,
   uint32_t flags,
   uint32_t *refNumP
)

Parameters

dbType
Type of the database that contains the executable module.
dbCreator
Creator ID of the database that contains the executable module.
rsrcID
ID number of the resources in the database that contain the code, data and relocation information for the executable module.
flags
Bits set or cleared in this 32-bit word indicate specific requirements that must be met while loading the executable module. See the Comments section, below, for more information on this argument.
refNumP
If the module is successfully loaded, the location to which this parameter points receives the reference number of the newly-loaded executable module.

Returns

Returns errNone if the operation succeeded, or one of the following otherwise:

sysErrModuleNotFound
Module not found.
sysErrModuleInvalid
Code resource has an invalid or corrupted format.
sysErrInvalidSignature
Module found but has no valid signature.
sysErrNoFreeRAM
There isn't enough free RAM to load the executable module.
sysErrCPUArchitecture
The program requires a different CPU architecture to run.
sysErrOSVersion
The program requires a higher version of the operating system in order to run.
sysErrRAMModuleNotAllowed
The program requires a higher version of the operating system in order to run.
sysErrNoFreeResource

Comments

A single resource database can contain multiple executable modules, each identified by a unique resource ID within that database. Each executable module is composed of several resources of different types, all of which have the same unique resource ID number within the containing database. The resource ID number is specified to pslib when the module is built. The same ID number should be specified when the executable is placed into the resource database (PRC file). By default, the resource ID number is zero.

Set the flags argument to 0 if the code has no special security requirements. A value of zero instructs the program loader to perform verification of digital signatures on the executable program according to the security property of the calling process. If the digital signature verification fails, the program loader doesn't load the program; sysErrInvalidSignature is returned to the caller.

Set the flags argument to sysDoNotVerifySignature to prevent the program loader from performing any verification of the executable module's digital signature, even if the security property of the calling process requires that the signature be verified. This is useful for certain type of applications—like web browsers—that have their own ways of verifying the integrity of downloaded programs.


NOTE: If there are multiple versions of the same database, the newest will be loaded.

If SysLoadModule() is successful, once the loaded module is no longer needed call SysUnloadModule() to unload the executable module.

See Also

SysGetEntryAddresses(), SysGetModuleInfo(), SysLoadModuleByDatabaseID(), SysUnloadModule()

SysLoadModuleByDatabaseID Function ^TOP^

Purpose

Load an executable module and make it ready for execution in the calling process, given the database ID of the database that contains the executable module.

Declared In

Loader.h

Prototype

status_t SysLoadModuleByDatabaseID (
   DatabaseID dbID,
   uint16_t rsrcID,
   uint32_t flags,
   uint32_t *refNumP
)

Parameters

dbID
Database ID of database that contains the executable module.
rsrcID
ID number of the resources in the database that contain the code, data and relocation information for the executable module.
flags
Bits set or cleared in this 32-bit word indicate specific requirements that must be met while loading the executable module. See the Comments section under SysLoadModule() for more information on this argument.
refNumP
If the module is successfully loaded, the location to which this parameter points receives the reference number of the newly-loaded executable module.

Returns

Returns errNone if the operation succeeded, or one of the following otherwise:

sysErrModuleNotFound
Module not found.
sysErrModuleInvalid
Code resource has an invalid or corrupted format.
sysErrInvalidSignature
Module found but has no valid signature.
sysErrNoFreeRAM
There isn't enough free RAM to load the executable module.
sysErrCPUArchitecture
The program requires a different CPU architecture to run.
sysErrOSVersion
The program requires a higher version of the operating system in order to run.
sysErrRAMModuleNotAllowed
The program requires a higher version of the operating system in order to run.
sysErrNoFreeResource

Comments

This function performs the same operation as SysLoadModule() except that it takes a database ID as input to identify the containing database of the executable module. This function is often used to load plug-ins.

See the SysLoadModule() function's Comments section for additional information on the loading of executable modules.

See Also

SysGetModuleInfoByDatabaseID(), SysLoadModule(), SysUnloadModule()

SysRegisterPatch Function ^TOP^

Purpose

Register a patch that is not packaged in a resource database of type 'apch'.

Declared In

Loader.h

Prototype

status_t SysRegisterPatch (
   uint32_t type,
   uint32_t creator,
   uint16_t rsrcID
)

Parameters

type
Type of the database that contains the patch.
creator
Creator ID of the database that contains the patch.
rsrcID
ID number of the resource in the database that contains the patch.

Returns

Returns errNone if the operation succeeded, or one of the following otherwise:

sysErrModuleNotFound
Patch not found.
sysErrModuleInvalid
Patch resources have invalid or corrupted format.
sysErrNoFreeRAM
There isn't enough free RAM to register the patch.

See Also

SysUnregisterPatch()

SysUnloadModule Function ^TOP^

Purpose

Unload an executable module and free resources that were allocated when it was loaded.

Declared In

Loader.h

Prototype

status_t SysUnloadModule (
   uint32_t refNum
)

Parameters

refNum
Reference number of the executable module returned by a former call to SysLoadModule().

Returns

Returns errNone if the operation succeeded, or sysErrParamErr if refNum doesn't refer to a loaded shared library.

See Also

SysLoadModule(), SysLoadModuleByDatabaseID()

SysUnregisterPatch Function ^TOP^

Purpose

Unregister a patch that was registered with SysRegisterPatch().

Declared In

Loader.h

Prototype

status_t SysUnregisterPatch (
   uint32_t type,
   uint32_t creator,
   uint16_t rsrcID
)

Parameters

type
Type of the database that contains the patch.
creator
Creator ID of the database that contains the patch.
rsrcID
ID number of the resource in the database that contains the patch.

Returns

Returns errNone if the operation succeeded, or one of the following otherwise:

sysErrModuleNotFound
Patch not found.
sysErrNoFreeRAM
Out of free RAM while unregistering the patch.

See Also

SysRegisterPatch()

Application-Defined Functions ^TOP^

SysMainEntryPtrType Function ^TOP^

Purpose

The prototype of the main entry point of any executable module.

Declared In

Loader.h

Prototype

uint32_t (
   *SysMainEntryPtrType
) (
   uint16_t cmd,
   MemPtr cmdPBP,
   uint16_t launchFlags
)

Parameters

cmd
The launch code to which your executable module is to respond. See Chapter 2, "Application Start and Stop," of Exploring Palm OS: Programming Basics for a list of predefined launch codes.
cmdPBP
A pointer to a structure containing any launch command-specific parameters, or NULL if the launch code has none. See the description of each launch code for a description of the parameter structure that accompanies it, if any.
launchFlags
Flags that indicate whether your application is now the active application, whether it already was the active application, and so on. See "Launch Flags" of Exploring Palm OS: Programming Basics for a list of launch flags.

Returns

Your executable module should return errNone if your application processed the launch code successfully of if the launch code is not recognized. Return an appropriate error code for recognized launch codes if there was a problem. When application invokes your executable module using SysAppLaunch(), the value you return from this function is returned to the caller.

Comments

See Chapter 2, "Application Start and Stop," of Exploring Palm OS: Programming Basics for a discussion on how applications receive and handle launch codes, with examples.