Función LoadLibraryA (libloaderapi.h)

Artículo
08/24/2023

Carga el módulo especificado en el espacio de direcciones del proceso de llamada. El módulo especificado puede hacer que se carguen otros módulos.

Para obtener opciones de carga adicionales, use la función LoadLibraryEx .

Sintaxis

HMODULE LoadLibraryA(
  [in] LPCSTR lpLibFileName
);

Parámetros

[in] lpLibFileName

El nombre del módulo. Puede ser un módulo de biblioteca (un archivo .dll) o un módulo ejecutable (un archivo .exe). Si el módulo especificado es un módulo ejecutable, no se cargan las importaciones estáticas; en su lugar, loaded the module is loaded as if by LoadLibraryEx with the DONT_RESOLVE_DLL_REFERENCES flag.

El nombre especificado es el nombre de archivo del módulo y no está relacionado con el nombre almacenado en el propio módulo de biblioteca, tal y como especifica la palabra clave LIBRARY en el archivo module-definition (.def).

Si la cadena especifica una ruta de acceso completa, la función solo busca esa ruta de acceso para el módulo.

Si la cadena especifica una ruta de acceso relativa o un nombre de módulo sin una ruta de acceso, la función usa una estrategia de búsqueda estándar para buscar el módulo; para obtener más información, vea los comentarios.

Si la función no encuentra el módulo, se produce un error en la función. Al especificar una ruta de acceso, asegúrese de usar barras diagonales inversas (\), no barras diagonales (/). Para obtener más información sobre las rutas de acceso, consulte Nomenclatura de un archivo o directorio.

Si la cadena especifica un nombre de módulo sin una ruta de acceso y se omite la extensión de nombre de archivo, la función anexa la extensión de biblioteca predeterminada ".DLL" al nombre del módulo. Para evitar que la función anexe ".DLL" al nombre del módulo, incluya un carácter de punto final (.) en la cadena de nombre del módulo.

Valor devuelto

Si la función es correcta, el valor devuelto es un identificador del módulo.

Si la función no se realiza correctamente, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Para habilitar o deshabilitar los mensajes de error mostrados por el cargador durante las cargas dll, use la función SetErrorMode .

LoadLibrary se puede usar para cargar un módulo de biblioteca en el espacio de direcciones del proceso y devolver un identificador que se puede usar en GetProcAddress para obtener la dirección de una función DLL. LoadLibrary también se puede usar para cargar otros módulos ejecutables. Por ejemplo, la función puede especificar un archivo .exe para obtener un identificador que se puede usar en FindResource o LoadResource. Sin embargo, no use LoadLibrary para ejecutar un archivo .exe. En su lugar, use la función CreateProcess .

Si el módulo especificado es un archivo DLL que aún no se ha cargado para el proceso de llamada, el sistema llama a la función DllMain del archivo DLL con el valor DLL_PROCESS_ATTACH . Si DllMain devuelve TRUE, LoadLibrary devuelve un identificador al módulo. Si DllMain devuelve FALSE, el sistema descarga el archivo DLL desde el espacio de direcciones del proceso y LoadLibrary devuelve NULL. No es seguro llamar a LoadLibrary desde DllMain. Para obtener más información, vea la sección Comentarios en DllMain.

Los identificadores de módulo no son globales ni herederas. Una llamada a LoadLibrary por un proceso no genera un identificador que otro proceso puede usar, por ejemplo, al llamar a GetProcAddress. El otro proceso debe realizar su propia llamada a LoadLibrary para el módulo antes de llamar a GetProcAddress.

Si lpFileName no incluye una ruta de acceso y hay más de un módulo cargado con el mismo nombre base y extensión, la función devuelve un identificador al módulo que se cargó primero.

Si no se especifica ninguna extensión de nombre de archivo en el parámetro lpFileName , se anexará la extensión de biblioteca predeterminada .dll. Sin embargo, la cadena de nombre de archivo puede incluir un carácter de punto final (.) para indicar que el nombre del módulo no tiene extensión. Cuando no se especifica ninguna ruta de acceso, la función busca módulos cargados cuyo nombre base coincida con el nombre base del módulo que se va a cargar. Si el nombre coincide, la carga se realiza correctamente. De lo contrario, la función busca el archivo.

El primer directorio buscado es el directorio que contiene el archivo de imagen usado para crear el proceso de llamada (para obtener más información, consulte la función CreateProcess ). Esto permite encontrar archivos de biblioteca de vínculos dinámicos (DLL) privados asociados a un proceso sin agregar el directorio instalado del proceso a la variable de entorno PATH. Si se especifica una ruta de acceso relativa, toda la ruta de acceso relativa se anexa a cada token de la lista de rutas de búsqueda dll. Para cargar un módulo desde una ruta de acceso relativa sin buscar en ninguna otra ruta de acceso, use GetFullPathName para obtener una ruta de acceso no relacionada y llamar a LoadLibrary con la ruta de acceso no relacionada. Para obtener más información sobre el orden de búsqueda de DLL, consulte Dynamic-Link Library Search Order( Orden de búsqueda de la biblioteca de vínculos dinámicos).

La ruta de acceso de búsqueda se puede modificar mediante la función SetDllDirectory . Esta solución se recomienda en lugar de usar SetCurrentDirectory o codificar de forma rígida la ruta de acceso completa al archivo DLL.

Si se especifica una ruta de acceso y hay un archivo de redireccionamiento para la aplicación, la función busca el módulo en el directorio de la aplicación. Si el módulo existe en el directorio de la aplicación, LoadLibrary omite la ruta de acceso especificada y carga el módulo desde el directorio de la aplicación. Si el módulo no existe en el directorio de la aplicación, LoadLibrary carga el módulo desde el directorio especificado. Para obtener más información, consulte Redirección de la biblioteca de vínculos dinámicos.

Si llama a LoadLibrary con el nombre de un ensamblado sin una especificación de ruta de acceso y el ensamblado aparece en el manifiesto compatible con el sistema, la llamada se redirige automáticamente al ensamblado en paralelo.

El sistema mantiene un recuento de referencias por proceso en todos los módulos cargados. Al llamar a LoadLibrary , se incrementa el recuento de referencias. Al llamar a la función FreeLibrary o FreeLibraryAndExitThread, se reduce el recuento de referencias. El sistema descarga un módulo cuando su recuento de referencias alcanza cero o cuando finaliza el proceso (independientemente del recuento de referencias).

Windows Server 2003 y Windows XP: El compilador de Visual C++ admite una sintaxis que permite declarar variables locales de subproceso: _declspec(thread). Si usa esta sintaxis en un archivo DLL, no podrá cargar el archivo DLL explícitamente mediante LoadLibrary en versiones de Windows anteriores a Windows Vista. Si el archivo DLL se cargará explícitamente, debe usar las funciones de almacenamiento local del subproceso en lugar de _declspec(subproceso). Para obtener un ejemplo, consulte Uso del almacenamiento local de subprocesos en una biblioteca de vínculos dinámicos.

Comentarios de seguridad

No use la función SearchPath para recuperar una ruta de acceso a un archivo DLL para una llamada posterior a LoadLibrary . La función SearchPath usa un orden de búsqueda diferente al de LoadLibrary y no usa el modo de búsqueda de procesos seguros a menos que se habilite explícitamente llamando a SetSearchPathMode con BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE. Por lo tanto, Es probable que SearchPath busque primero el directorio de trabajo actual del usuario para el archivo DLL especificado. Si un atacante ha copiado una versión malintencionada de un archivo DLL en el directorio de trabajo actual, la ruta de acceso recuperada por SearchPath apuntará al archivo DLL malintencionado, que loadLibrary cargará.

No realice suposiciones sobre la versión del sistema operativo basada en una llamada LoadLibrary que busque un archivo DLL. Si la aplicación se ejecuta en un entorno en el que el archivo DLL no está presente legítimamente, pero una versión malintencionada del archivo DLL está en la ruta de búsqueda, se puede cargar la versión malintencionada del archivo DLL. En su lugar, use las técnicas recomendadas descritas en Obtención de la versión del sistema.

Ejemplos

Para obtener un ejemplo, consulte Uso de Run-Time vinculación dinámica.

Nota:

El encabezado libloaderapi.h define LoadLibrary como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos


Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	libloaderapi.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll