Función LoadLibraryW (libloaderapi.h)

Artículo
11/20/2024

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 LoadLibraryW(
  [in] LPCWSTR lpLibFileName
);

Parámetros

[in] lpLibFileName

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, el módulo se carga como si LoadLibraryEx con la marca DONT_RESOLVE_DLL_REFERENCES.

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 como se especifica en 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 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, vea Asignar nombre a 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 se ejecuta correctamente, el valor devuelto es un identificador del módulo.

Si se produce un error en la función, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Observaciones

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 de .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 dll DllMain con el valor de 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 de DllMain.

Los identificadores de módulo no son globales o heredables. 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 anexa 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 privados de biblioteca de vínculos dinámicos (DLL) 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, la ruta de acceso relativa completa se anexa a todos los tokens de la lista de rutas de búsqueda de 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 norelative y llamar a LoadLibrary con la ruta de acceso no rerelative. Para obtener más información sobre el orden de búsqueda de DLL, vea Dynamic-Link Library Search Order.

La ruta de acceso de búsqueda se puede modificar mediante la función setDllDirectory de . 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. Llamar a LoadLibrary incrementa el recuento de referencias. Al llamar al FreeLibrary o freeLibraryAndExitThread función disminuye 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 le permite declarar variables locales de subprocesos: _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(thread). Para obtener un ejemplo, vea Uso del almacenamiento local de subprocesos en una biblioteca de vínculos dinámicos.

Comentarios de seguridad de

No use la función searchPath de para recuperar una ruta de acceso a un archivo DLL para una llamada posterior LoadLibrary. La función SearchPath de usa un orden de búsqueda diferente al LoadLibrary y no usa el modo de búsqueda de procesos seguros a menos que se habilite explícitamente mediante una llamada 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 se cargará.

No realice suposiciones sobre la versión del sistema operativo basada en una llamada de 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 se encuentra 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 Obtener la versión del sistema.

Ejemplos

Para obtener un ejemplo, vea Using Run-Time Dynamic Linking.

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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	libloaderapi.h (incluya Windows.h)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll