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
SysModuleInfoType Struct
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
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
Miscellaneous Loader Constants
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
sysPatchLaunchCmdClearInfo
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
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
SysGetEntryAddresses Function
Purpose
Retrieve addresses of one or more entry points exported by a loaded executable module.
Declared In
Loader.h
Prototype
status_t SysGetEntryAddresses ( uint32_trefNum
, uint32_tstartEntryNum
, uint32_tnumEntries
, 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, orsysEntryNumMain
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
issysEntryNumMain
, 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
isNULL
, or eitherstartEntryNum
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
SysGetModuleDatabase Function
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_trefNum
, 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 notNULL
and the database that contains the executable module identified byrefNum
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
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_trefNum
, BooleanwantStructure
, 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 whenwantStructure
istrue
. -
sysErrParamErr
-
refNum
doesn't reference a loaded shared library. The memory pointed to byaddressP
is set toNULL
.
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
SysGetModuleInfo Function
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_tdbType
, uint32_tdbCreator
, uint16_trsrcID
, 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
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 ( DatabaseIDdbID
, uint16_trsrcID
, 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
Purpose
Retrieve the reference number of the calling module.
Declared In
Loader.h
Prototype
uint32_t SysGetRefNum ( void )
Parameters
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
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_tdbType
, uint32_tdbCreator
, uint16_trsrcID
, uint32_tflags
, 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.
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
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 ( DatabaseIDdbID
, uint16_trsrcID
, uint32_tflags
, 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
Purpose
Register a patch that is not packaged in a resource database of type 'apch'
.
Declared In
Loader.h
Prototype
status_t SysRegisterPatch ( uint32_ttype
, uint32_tcreator
, uint16_trsrcID
)
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
SysUnloadModule Function
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
Purpose
Unregister a patch that was registered with SysRegisterPatch()
.
Declared In
Loader.h
Prototype
status_t SysUnregisterPatch ( uint32_ttype
, uint32_tcreator
, uint16_trsrcID
)
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
Application-Defined Functions
SysMainEntryPtrType Function
Purpose
The prototype of the main entry point of any executable module.
Declared In
Loader.h
Prototype
uint32_t ( *SysMainEntryPtrType ) ( uint16_tcmd
, MemPtrcmdPBP
, uint16_tlaunchFlags
)
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.