Funzione LoadLibraryA (libloaderapi.h)
Carica il modulo specificato nello spazio indirizzi del processo chiamante. Il modulo specificato può causare il caricamento di altri moduli.
Per altre opzioni di caricamento, usare la funzione LoadLibraryEx .
Sintassi
HMODULE LoadLibraryA(
[in] LPCSTR lpLibFileName
);
Parametri
[in] lpLibFileName
Nome del modulo. Può trattarsi di un modulo di libreria (un file .dll) o un modulo eseguibile (un file .exe).
Se il modulo specificato è un modulo eseguibile, le importazioni statiche non vengono caricate; Al contrario, il modulo viene caricato come se da LoadLibraryEx con il DONT_RESOLVE_DLL_REFERENCES flag .
Il nome specificato è il nome file del modulo e non è correlato al nome archiviato nel modulo di libreria stesso, come specificato dalla parola chiave LIBRARY nel file module-definition (.def).
Se la stringa specifica un percorso completo, la funzione cerca solo il percorso del modulo.
Se la stringa specifica un percorso relativo o un nome di modulo senza un percorso, la funzione usa una strategia di ricerca standard per trovare il modulo; per altre informazioni, vedere la sezione Osservazioni.
Se la funzione non riesce a trovare il modulo, la funzione ha esito negativo. Quando si specifica un percorso, assicurarsi di usare le barre rovesciata (\), non le barre (/). Per altre informazioni sui percorsi, vedere Denominazione di un file o di una directory.
Se la stringa specifica un nome di modulo senza un percorso e l'estensione del nome file viene omessa, la funzione aggiunge l'estensione della libreria predefinita ".DLL" al nome del modulo. Per impedire alla funzione di aggiungere ".DLL" al nome del modulo, includere un carattere punto finale (.) nella stringa del nome del modulo.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle per il modulo.
Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
Per abilitare o disabilitare i messaggi di errore visualizzati dal caricatore durante il caricamento della DLL, usare la funzione SetErrorMode .
LoadLibrary può essere usato per caricare un modulo di libreria nello spazio indirizzi del processo e restituire un handle che può essere usato in GetProcAddress per ottenere l'indirizzo di una funzione DLL. LoadLibrary può essere usato anche per caricare altri moduli eseguibili. Ad esempio, la funzione può specificare un file .exe per ottenere un handle che può essere usato in FindResource o LoadResource. Tuttavia, non usare LoadLibrary per eseguire un file .exe. Usare invece la funzione CreateProcess .
Se il modulo specificato è una DLL non già caricata per il processo chiamante, il sistema chiama la funzione DllMain della DLL con il valore DLL_PROCESS_ATTACH . Se DllMain restituisce TRUE, LoadLibrary restituisce un handle al modulo. Se DllMain restituisce FALSE, il sistema scarica la DLL dallo spazio indirizzi del processo e LoadLibrary restituisce NULL. Non è sicuro chiamare LoadLibrary da DllMain. Per altre informazioni, vedere la sezione Osservazioni in DllMain.
Gli handle di modulo non sono globali o ereditabili. Una chiamata a LoadLibrary da un processo non produce un handle che un altro processo può usare, ad esempio chiamando GetProcAddress. L'altro processo deve effettuare la propria chiamata a LoadLibrary per il modulo prima di chiamare GetProcAddress.
Se lpFileName non include un percorso e sono presenti più moduli caricati con lo stesso nome di base ed estensione, la funzione restituisce un handle al modulo caricato per primo.
Se non viene specificata alcuna estensione di file nel parametro lpFileName , viene aggiunta l'estensione della libreria predefinita .dll. Tuttavia, la stringa del nome file può includere un carattere punto finale (.) per indicare che il nome del modulo non ha estensione. Quando non viene specificato alcun percorso, la funzione cerca moduli caricati il cui nome di base corrisponde al nome di base del modulo da caricare. Se il nome corrisponde, il caricamento ha esito positivo. In caso contrario, la funzione cerca il file.
La prima directory cercata è la directory contenente il file di immagine usato per creare il processo chiamante . Per altre informazioni, vedere la funzione CreateProcess . In questo modo è possibile trovare file DLL (Dynamic Link Library) privati associati a un processo senza aggiungere la directory installata del processo alla variabile di ambiente PATH. Se viene specificato un percorso relativo, l'intero percorso relativo viene aggiunto a ogni token nell'elenco dei percorsi di ricerca dll. Per caricare un modulo da un percorso relativo senza eseguire ricerche in un altro percorso, usare GetFullPathName per ottenere un percorso nonrelative e chiamare LoadLibrary con il percorso nonrelative. Per altre informazioni sull'ordine di ricerca dll, vedere Ordine di ricerca della libreria a collegamento dinamico.
Il percorso di ricerca può essere modificato usando la funzione SetDllDirectory . Questa soluzione è consigliata anziché usare SetCurrentDirectory o impostare come hardcoded il percorso completo della DLL.
Se viene specificato un percorso ed è presente un file di reindirizzamento per l'applicazione, la funzione cerca il modulo nella directory dell'applicazione. Se il modulo esiste nella directory dell'applicazione, LoadLibrary ignora il percorso specificato e carica il modulo dalla directory dell'applicazione. Se il modulo non esiste nella directory dell'applicazione, LoadLibrary carica il modulo dalla directory specificata. Per altre informazioni, vedere Reindirizzamento della libreria di collegamento dinamico.
Se si chiama LoadLibrary con il nome di un assembly senza specifica di percorso e l'assembly è elencato nel manifesto compatibile con il sistema, la chiamata viene reindirizzata automaticamente all'assembly side-by-side.
Il sistema gestisce un conteggio dei riferimenti per processo in tutti i moduli caricati. La chiamata a LoadLibrary incrementa il conteggio dei riferimenti. La chiamata alla funzione FreeLibrary o FreeLibraryAndExitThread decrementa il conteggio dei riferimenti. Il sistema scarica un modulo quando il numero di riferimenti raggiunge zero o quando il processo termina (indipendentemente dal conteggio dei riferimenti).
Windows Server 2003 e Windows XP: Il compilatore Visual C++ supporta una sintassi che consente di dichiarare le variabili locali del thread: _declspec(thread). Se si usa questa sintassi in una DLL, non sarà possibile caricare la DLL in modo esplicito usando LoadLibrary nelle versioni di Windows precedenti a Windows Vista. Se la DLL verrà caricata in modo esplicito, è necessario usare le funzioni di archiviazione locale del thread anziché _declspec(thread).If your DLL will loaded explicitly, you must use the thread local storage functions instead of _declspec(thread). Per un esempio, vedere Uso dell'archiviazione locale dei thread in una libreria a collegamento dinamico.
Osservazioni sulla sicurezza
Non utilizzare la funzione SearchPath per recuperare un percorso di una DLL per una successiva chiamata LoadLibrary . La funzione SearchPath usa un ordine di ricerca diverso da LoadLibrary e non usa la modalità di ricerca sicura dei processi, a meno che non sia abilitata in modo esplicito chiamando SetSearchPathMode con BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE. È quindi probabile che SearchPath cerchi la DLL specificata nella directory di lavoro corrente dell'utente. Se un utente malintenzionato ha copiato una versione dannosa di una DLL nella directory di lavoro corrente, il percorso recuperato da SearchPath punterà alla DLL dannosa, che LoadLibrary caricherà.Non fare ipotesi sulla versione del sistema operativo in base a una chiamata LoadLibrary che cerca una DLL. Se l'applicazione è in esecuzione in un ambiente in cui la DLL non è presente in modo legittimo, ma una versione dannosa della DLL si trova nel percorso di ricerca, è possibile caricare la versione dannosa della DLL. Usare invece le tecniche consigliate descritte in Recupero della versione di sistema.
Esempio
Per un esempio, vedere Uso di Run-Time collegamento dinamico.
Nota
L'intestazione libloaderapi.h definisce LoadLibrary come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | libloaderapi.h (include Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |
Vedere anche
Funzioni della libreria a collegamento dinamico