LoadLibrary

LoadLibrary maps the specified executable module into the address space of the calling process.

Syntax

HINSTANCE LoadLibrary(
    [in]    LPCTSTR lpLibFileName
);

Parameters

[in] LpLibFileName

Pointer to a null-terminated string that names the RTDLL module (a DLL file). The name specified is the module's filename. It is not related to the name stored in the library module itself, as specified by the library keyword in the module definition (DEF) file.

If the string specifies a path but the path does not exist in the specified directory, the function fails.

If the string does not specify a path but only a file name, it first checks the directory where the parent process that is loading the library resides. Failing this, searches for files within the Search Path directories configured in the wRTOS Settings or Managed Code library.

Search executes in this order:

1. The application directory of the current process.
2. The directories in the Search Path, as configured in the wRTOS Settings (using the directory order specified in the search path).

The length of lpLibFileName should not be greater than MAX_PATH.

If no filename extension is specified in the lpLibFileName parameter, the default library extension .RTDLL is appended.

The .exe extension and DLL names without an extension (i.e., the trailing dot convention) are not supported.

Note: LoadLibrary does not support loading RTSS and RTDLL files with pathnames containing Unicode characters with code points greater than 255. These characters include Japanese, Chinese, Greek, Hebrew, Cyrillic, Korean characters, and characters from many other non-Latin languages. This includes all ASCII and ISO Latin-1 characters, such as 'µ', 'ö', 'é', 'ß', 'ñ', 'ç', etc.

Return Value

If the function succeeds, it returns a handle to the module. If the function fails, it returns NULL. Call GetLastError to get extended error information.

Remarks

LoadLibrary can map an RTDLL module and return a handle that can be used in GetProcAddress to get the address of an RTDLL function.

If the module's RTDLL is not already mapped for the calling process, the system calls the RTDLL's DllMain function with the DLL_PROCESS_ATTACH value.

If the RTDLL's entry-point function does not return TRUE, LoadLibrary fails and returns NULL.

Note: It is not safe to call LoadLibrary from DllMain.

Module handles are not global or inheritable. A call to LoadLibrary by one process does not produce a handle that another process can use, for example, in calling GetProcAddress. The other process must make its own call to LoadLibrary for the module before calling GetProcAddress.

Loaded Modules Maximum

The default maximum number of loaded RTSS and RTDLL modules in a Real-time process is 64. If this number is exceeded, an error will appear advising that it be increased. Follow the steps below to increase the maximum number of loaded RTSS and RTDLL modules.

To increase the maximum number of loaded modules:

1. Open Registry Editor.
2. Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\wRTOS\
3. Do one of the following:
1. Double-click MaxModules.
2. Right-click MaxModules and then choose Modify.
4. To increase the maximum number of loaded RTSS and RTDLL modules, increase the Value data value.
5. Select OK.

Requirements

See Also:

• DllMain
• GetProcAddress