OSDynLoad_Acquire

Syntax

#include <cafe/os/OSDynLoad.h>

int OSDynLoad_Acquire(char const * apBaseModuleName,
		      OSDynLoad_ModuleHandle * apRetHandle);

Parameters

apBaseModuleName Base module name (no path or extension) to load. If the module is already loaded, it is not loaded again, and a handle to the existing module is returned.
NOTE:
If the module's base file name (not including its extension) includes a "." character, then the extension must be included. For example, if a module's full file name is system.dll.rpl, then the full file name must be passed.
apRetHandle Pointer to the handle variable to receive the handle to the loaded module This handle value is used in other OSDynLoad function calls.  NULL (or 0) is never a valid handle value. If the function fails, the return handle value will always be set to 0 unless the pointer to the handle itself is an invalid pointer.

Return Values

Returns an OSDYNLOAD_ERR_xxx error code (see OSDynLoad.h).

The following table lists the most common errors that might be returned.

Error Cause Possible Solution
IOS_ERROR_NOEXISTS,
-6,
0xFFFFFFFA
Tried to load USER_FILE for PID that the process has not started, or tried to load SHARED_FILE and title with shared data is not installed in the system. Ensure that the file is in the expected location. If you do not need that file, you may ignore the error.
FSA_STATUS_INVALID_PATH,
-196642,
0xFFFCFFDE
Module not found because path to file is not valid. Ensure that the file is in the expected location. If you do not need that file, you may ignore the error.
FSA_STATUS_NOT_FOUND,
-196631,
0xFFFCFFE9
Module not found. Ensure that the file is in the expected location. If you do not need that file, you may ignore the error.
IOS_ERROR_INVALID_SIZE,
-23,
0xFFFFFFE9
Module not found because the size of the file is not valid. Ensure that the file is in the expected location. If you do not need that file, you may ignore the error.
FSA_STATUS_MEDIA_NOT_READY,
-196672,
0xFFFCFFC0
Module not found because disc was ejected. Reinsert the disc.
IOS_ERROR_TIMEOUT,
-32,
0xFFFFFFE0
Module not loaded after a reasonable length of time. Reboot console.

NULL (or 0) is never a valid handle value.  If the function fails, the return handle value will always be set to 0 unless the pointer to the handle itself is not a valid pointer.

Description

This function is the main RPL loader function. The function takes the base module name to load, and returns a handle to the loaded module.

Loading of dependencies is automatic. If one RPL implicitly uses another RPL as a result of linking to an import library, then the dependency is automatically loaded at the same time.

Loading of RPLs consumes memory from 3 heaps: the System heap (for tracking structures), the loader heap for code, import and export sections, and the heap currently associated with OSDynLoad_GetAllocator (normally the default heap) for RPL DATA, BSS and RODATA.  Loading many RPLs can quickly exhaust the System heap. The System heap can be increased with the makerpl tool's -h option.

OSDynLoad_Acquire can be called on any core. The acquired RPL can be used on any core. The loader will load the RPL using the CPU core which calls the OSDynLoad_Acquire function.

Do Not Call From

None.

See Also

OSDynLoad_AddNotifyCallback
OSDynLoad_DelNotifyCallback
OSDynLoad_FindExport
OSDynLoad_FindTag
OSDynLoad_GetAllocator
OSDynLoad_GetLoaderHeapStatistics
OSDynLoad_GetModuleName
OSDynLoad_IsModuleLoaded
OSDynLoad_Release
OSDynLoad_SetAllocator
makerpl

Revision History

2014/02/27 Note that a file name with a "." must include the extension.
2013/11/01 Added OSDynLoad_IsModuleLoaded.
2013/05/08 Automated cleanup pass.
2011/03/11 Initial version.


CONFIDENTIAL