En esta página

QLibrary Class

La clase QLibrary carga bibliotecas compartidas en tiempo de ejecución. Más información...

Encabezado: #include <QLibrary>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Heredan: QObject

Nota: Todas las funciones de esta clase son reentrantes.

Tipos públicos

enum LoadHint { ResolveAllSymbolsHint, ExportExternalSymbolsHint, LoadArchiveMemberHint, PreventUnloadHint, DeepBindHint }
flags LoadHints

Propiedades

Funciones públicas

QLibrary(QObject *parent = nullptr)
QLibrary(const QString &fileName, QObject *parent = nullptr)
QLibrary(const QString &fileName, const QString &version, QObject *parent = nullptr)
QLibrary(const QString &fileName, int verNum, QObject *parent = nullptr)
virtual ~QLibrary()
QString errorString() const
QString fileName() const
bool isLoaded() const
bool load()
QLibrary::LoadHints loadHints() const
QFunctionPointer resolve(const char *symbol)
void setFileName(const QString &fileName)
void setFileNameAndVersion(const QString &fileName, const QString &version)
void setFileNameAndVersion(const QString &fileName, int versionNumber)
void setLoadHints(QLibrary::LoadHints hints)
bool unload()

Miembros públicos estáticos

bool isLibrary(const QString &fileName)
QFunctionPointer resolve(const QString &fileName, const char *symbol)
QFunctionPointer resolve(const QString &fileName, const QString &version, const char *symbol)
QFunctionPointer resolve(const QString &fileName, int verNum, const char *symbol)

Descripción detallada

Una instancia de un objeto QLibrary opera sobre un único archivo de objeto compartido (al que llamamos «biblioteca», aunque también se conoce como «DLL»). QLibrary proporciona acceso a la funcionalidad de la biblioteca de forma independiente de la plataforma. Se puede pasar un nombre de archivo en el constructor o establecerlo explícitamente con ` setFileName()`. Al cargar la biblioteca, `QLibrary` busca en todas las ubicaciones de bibliotecas específicas del sistema (por ejemplo, ` LD_LIBRARY_PATH ` en Unix), a menos que el nombre del archivo tenga una ruta absoluta.

Si el nombre del archivo es una ruta absoluta, se intenta cargar primero esa ruta. Si no se encuentra el archivo, QLibrary prueba el nombre con diferentes prefijos específicos de la plataforma, como «lib» en Unix y Mac, y sufijos, como «.so» en Unix, «.dylib» en Mac o «.dll» en Windows.

Si la ruta del archivo no es absoluta, QLibrary modifica el orden de búsqueda para probar primero los prefijos y sufijos específicos del sistema, seguidos de la ruta del archivo especificada.

Esto permite especificar bibliotecas compartidas que solo se identifican por su nombre base (es decir, sin su sufijo), de modo que el mismo código funcionará en diferentes sistemas operativos y, al mismo tiempo, se minimiza el número de intentos para encontrar la biblioteca.

Las funciones más importantes son « load()» para cargar dinámicamente el archivo de la biblioteca, « isLoaded()» para comprobar si la carga se ha realizado correctamente y « resolve()» para resolver un símbolo en la biblioteca. La función « resolve()» intenta implícitamente cargar la biblioteca si aún no se ha cargado. Se pueden utilizar varias instancias de QLibrary para acceder a la misma biblioteca física. Una vez cargadas, las bibliotecas permanecen en memoria hasta que la aplicación finaliza. Se puede intentar descargar una biblioteca utilizando unload(), pero si otras instancias de QLibrary están utilizando la misma biblioteca, la llamada fallará, y la descarga solo se producirá cuando todas las instancias hayan llamado a unload().

Un uso habitual de QLibrary es resolver un símbolo exportado en una biblioteca y llamar a la función C que representa dicho símbolo. Esto se denomina «enlace explícito», en contraposición al «enlace implícito», que se realiza durante la fase de enlace del proceso de compilación al vincular un ejecutable con una biblioteca.

El siguiente fragmento de código carga una biblioteca, resuelve el símbolo «mysymbol» y llama a la función si todo ha salido bien. Si surge algún error, por ejemplo, si el archivo de la biblioteca no existe o el símbolo no está definido, el puntero a la función será ` nullptr ` y no se llamará a la función.

QLibrary myLib("mylib");
typedef void (*MyPrototype)();
MyPrototype myFunction = (MyPrototype) myLib.resolve("mysymbol");
if (myFunction)
    myFunction();

Para que ` resolve()` funcione, el símbolo debe exportarse como una función C desde la biblioteca. Esto significa que la función debe estar envuelta en un bloque ` extern "C" ` si la biblioteca se compila con un compilador de C++. En Windows, esto también requiere el uso de la macro « dllexport »; consulta « resolve()» para obtener más detalles sobre cómo hacerlo. Para mayor comodidad, existe una función estática « resolve()» que puedes utilizar si solo deseas llamar a una función de una biblioteca sin tener que cargarla explícitamente primero:

typedef void (*MyPrototype)();
MyPrototype myFunction =
        (MyPrototype) QLibrary::resolve("mylib", "mysymbol");
if (myFunction)
    myFunction();

Véase también QPluginLoader.

Documentación sobre los tipos de miembro

enum QLibrary::LoadHint
flags QLibrary::LoadHints

Esta enumeración describe las posibles opciones que se pueden utilizar para modificar la forma en que se gestionan las bibliotecas al cargarlas. Estos valores indican cómo se resuelven los símbolos al cargar las bibliotecas y se especifican mediante la función ` setLoadHints()`.

ConstanteValorDescripción
QLibrary::ResolveAllSymbolsHint0x01Hace que todos los símbolos de una biblioteca se resuelvan al cargarla, y no solo cuando se llama a resolve().
QLibrary::ExportExternalSymbolsHint0x02Exporta los símbolos no resueltos y externos de la biblioteca para que puedan resolverse en otras bibliotecas cargadas dinámicamente posteriormente.
QLibrary::LoadArchiveMemberHint0x04Permite que el nombre de archivo de la biblioteca especifique un archivo objeto concreto dentro de un archivo de archivo. Si se proporciona esta indicación, el nombre de archivo de la biblioteca consta de una ruta, que es una referencia a un archivo de archivo, seguida de una referencia al miembro del archivo.
QLibrary::PreventUnloadHint0x08Evita que la biblioteca se descargue del espacio de direcciones si se llama a close(). Las variables estáticas de la biblioteca no se reinicializan si se llama a open() posteriormente.
QLibrary::DeepBindHint0x10Indica al enlazador que, al resolver símbolos externos en la biblioteca cargada, dé prioridad a las definiciones de la biblioteca cargada frente a las definiciones exportadas por la aplicación que la carga. Esta opción solo es compatible con Linux.

El tipo LoadHints es un typedef para QFlags<LoadHint>. Almacena una combinación OR de valores LoadHint.

Véase también loadHints.

Documentación de propiedades

fileName : QString

Esta propiedad contiene el nombre del archivo de la biblioteca

Recomendamos omitir la extensión del archivo en el nombre, ya que QLibrary buscará automáticamente el archivo con la extensión adecuada (véase isLibrary()).

Al cargar la biblioteca, QLibrary busca en todas las ubicaciones de bibliotecas específicas del sistema (por ejemplo, LD_LIBRARY_PATH en Unix), a menos que el nombre del archivo tenga una ruta absoluta. Tras cargar la biblioteca correctamente, fileName() devuelve el nombre completo de la biblioteca, incluida la ruta completa a la misma si se ha especificado en el constructor o se ha pasado a setFileName().

Por ejemplo, tras cargar correctamente la biblioteca «GL» en plataformas Unix, fileName() devolverá «libGL.so». Si el nombre del archivo se pasó originalmente como «/usr/lib/libGL», fileName() devolverá «/usr/lib/libGL.so».

Funciones de acceso:

QString fileName() const
void setFileName(const QString &fileName)

loadHints : LoadHints

Proporciona a la función ` load()` algunas indicaciones sobre cómo debe comportarse.

Puedes proporcionar algunas indicaciones sobre cómo se resuelven los símbolos. Normalmente, los símbolos no se resuelven en el momento de la carga, sino de forma diferida (es decir, cuando se llama a resolve()). Si estableces loadHints en ResolveAllSymbolsHint, todos los símbolos se resolverán en el momento de la carga si la plataforma lo admite.

Al establecer ` ExportExternalSymbolsHint `, los símbolos externos de la biblioteca estarán disponibles para su resolución en las bibliotecas que se carguen posteriormente.

Si se establece LoadArchiveMemberHint, el nombre del archivo se compone de dos componentes: una ruta que hace referencia a un archivo comprimido, seguida del segundo componente, que es la referencia al elemento del archivo comprimido. Por ejemplo, el fileName libGL.a(shr_64.o) hará referencia a la biblioteca shr_64.o en el archivo comprimido denominado libGL.a. Esto solo es compatible con la plataforma AIX.

La interpretación de las indicaciones de carga depende de la plataforma, y si las utilizas probablemente estés haciendo algunas suposiciones sobre la plataforma para la que estás compilando, así que utilízalas solo si comprendes sus consecuencias.

Por defecto, ninguna de estas opciones está activada, por lo que las bibliotecas se cargarán con resolución de símbolos diferida y no exportarán símbolos externos para su resolución en otras bibliotecas cargadas dinámicamente.

Nota: Las sugerencias solo se pueden borrar cuando este objeto no está asociado a ningún archivo. Las sugerencias solo se pueden añadir una vez que se haya establecido el nombre del archivo (hints se combinará con las sugerencias anteriores mediante la operación OR).

Nota: Establecer esta propiedad después de que la biblioteca se haya cargado no tiene ningún efecto y loadHints() no reflejará dichos cambios.

Nota: Esta propiedad es compartida por todas las instancias de QLibrary que hacen referencia a la misma biblioteca.

Funciones de acceso:

QLibrary::LoadHints loadHints() const
void setLoadHints(QLibrary::LoadHints hints)

Documentación de las funciones de miembro

[explicit] QLibrary::QLibrary(QObject *parent = nullptr)

Crea una biblioteca con el archivo « parent » proporcionado.

[explicit] QLibrary::QLibrary(const QString &fileName, QObject *parent = nullptr)

Crea un objeto de biblioteca con el nombre de archivo dado ( parent ) que cargará la biblioteca especificada por fileName.

Recomendamos omitir la extensión del archivo en fileName, ya que QLibrary buscará automáticamente el archivo con la extensión adecuada según la plataforma, por ejemplo, «.so» en Unix, «.dylib» en macOS e iOS, y «.dll» en Windows. (Véase fileName.)

[explicit] QLibrary::QLibrary(const QString &fileName, const QString &version, QObject *parent = nullptr)

Crea un objeto de biblioteca con el « parent » proporcionado, que cargará la biblioteca especificada por « fileName » y el número de versión completo « version ». Actualmente, el número de versión se ignora en Windows.

Recomendamos omitir la extensión del archivo en fileName, ya que QLibrary buscará automáticamente el archivo con la extensión adecuada según la plataforma, por ejemplo, «.so» en Unix, «.dylib» en macOS e iOS, y «.dll» en Windows. (Véase fileName.)

[explicit] QLibrary::QLibrary(const QString &fileName, int verNum, QObject *parent = nullptr)

Crea un objeto de biblioteca con el ` parent ` proporcionado, que cargará la biblioteca especificada por ` fileName ` y el número de versión principal ` verNum`. Actualmente, en Windows se ignora el número de versión.

Recomendamos omitir la extensión del archivo en fileName, ya que QLibrary buscará automáticamente el archivo con la extensión adecuada según la plataforma, por ejemplo, «.so» en Unix, «.dylib» en macOS e iOS, y «.dll» en Windows. (Véase fileName.)

[virtual noexcept] QLibrary::~QLibrary()

Destruye el objeto ` QLibrary `.

A menos que se haya llamado explícitamente a unload(), la biblioteca permanece en memoria hasta que la aplicación finaliza.

Véanse también isLoaded() y unload().

QString QLibrary::errorString() const

Devuelve una cadena de texto con la descripción del último error que se ha producido. Actualmente, la variable «errorString» solo se establecerá si, por algún motivo, fallan las funciones « load()», « unload()» o « resolve()».

[static] bool QLibrary::isLibrary(const QString &fileName)

Devuelve « true » si « fileName » tiene un sufijo válido para una biblioteca cargable; en caso contrario, devuelve « false ».

PlataformaSufijos válidos
Windows.dll, .DLL
Unix/Linux.so
AIX.a
HP-UX.sl, .so (HP-UXi)
macOS e iOS.dylib, .bundle, .so

En Unix se ignoran los números de versión finales.

bool QLibrary::isLoaded() const

Devuelve ` true ` si la llamada a ` load()` se ha realizado correctamente; en caso contrario, devuelve ` false`.

Nota: Antes de Qt 6.6, esta función devolvía true incluso sin haber llamado a load() si otro objeto QLibrary de la misma biblioteca había provocado su carga.

Véase también load().

bool QLibrary::load()

Carga la biblioteca y devuelve « true » si la biblioteca se ha cargado correctamente; en caso contrario, devuelve « false ». Dado que « resolve()» siempre llama a esta función antes de resolver cualquier símbolo, no es necesario llamarla explícitamente. En algunas situaciones, es posible que desees que la biblioteca se cargue por adelantado, en cuyo caso deberías utilizar esta función.

Véase también unload().

QFunctionPointer QLibrary::resolve(const char *symbol)

Devuelve la dirección del símbolo exportado symbol. La biblioteca se carga si es necesario. La función devuelve nullptr si no se ha podido resolver el símbolo o si no se ha podido cargar la biblioteca.

Ejemplo:

typedef int (*AvgFunction)(int, int);

AvgFunction avg = (AvgFunction) library->resolve("avg");
if (avg)
    return avg(5, 8);
else
    return -1;

El símbolo debe exportarse como una función C desde la biblioteca. Esto significa que la función debe envolverse en un ` extern "C" ` si la biblioteca se compila con un compilador de C++. En Windows, también debes exportar explícitamente la función desde la DLL utilizando la directiva del compilador ` __declspec(dllexport) `, por ejemplo:

extern "C" MY_EXPORT int avg(int a, int b)
{
    return (a + b) / 2;
}

con ` MY_EXPORT ` definido como

#ifdef Q_OS_WIN
#define MY_EXPORT __declspec(dllexport)
#else
#define MY_EXPORT
#endif

[static] QFunctionPointer QLibrary::resolve(const QString &fileName, const char *symbol)

Carga la biblioteca fileName y devuelve la dirección del símbolo exportado symbol. Ten en cuenta que fileName no debe incluir la extensión específica de la plataforma; (véase fileName). La biblioteca permanece cargada hasta que la aplicación se cierre.

La función devuelve nullptr si no se ha podido resolver el símbolo o si no se ha podido cargar la biblioteca.

Esta es una función sobrecargada.

Véase también resolve().

[static] QFunctionPointer QLibrary::resolve(const QString &fileName, const QString &version, const char *symbol)

Carga la biblioteca fileName con el número de versión completo version y devuelve la dirección del símbolo exportado symbol. Ten en cuenta que fileName no debe incluir la extensión específica de la plataforma; (véase fileName). La biblioteca permanece cargada hasta que la aplicación se cierre. version se ignora en Windows.

La función devuelve nullptr si no se ha podido resolver el símbolo o si no se ha podido cargar la biblioteca.

Esta es una función sobrecargada.

Véase también resolve().

[static] QFunctionPointer QLibrary::resolve(const QString &fileName, int verNum, const char *symbol)

Carga la biblioteca fileName con el número de versión principal verNum y devuelve la dirección del símbolo exportado symbol. Ten en cuenta que fileName no debe incluir la extensión de archivo específica de la plataforma; (véase fileName). La biblioteca permanece cargada hasta que la aplicación se cierre. verNum se ignora en Windows.

La función devuelve nullptr si no se ha podido resolver el símbolo o si no se ha podido cargar la biblioteca.

Esta es una función sobrecargada.

Véase también resolve().

void QLibrary::setFileNameAndVersion(const QString &fileName, const QString &version)

Establece la propiedad « fileName » y el número de versión completo en fileName y version, respectivamente. El parámetro « version » se ignora en Windows.

Véase también setFileName().

void QLibrary::setFileNameAndVersion(const QString &fileName, int versionNumber)

Establece la propiedad « fileName » y el número de versión principal en « fileName » y « versionNumber », respectivamente. En Windows se ignora la propiedad « versionNumber ».

Véase también setFileName().

bool QLibrary::unload()

Descarga la biblioteca y devuelve ` true ` si se ha podido descargar; en caso contrario, devuelve ` false`.

Esto ocurre automáticamente al cerrarse la aplicación, por lo que normalmente no debería ser necesario llamar a esta función.

Si hay otras instancias de ` QLibrary ` que estén utilizando la misma biblioteca, la llamada fallará, y la descarga solo se producirá cuando todas las instancias hayan llamado a `unload()`.

Ten en cuenta que, en macOS, las bibliotecas dinámicas no se pueden descargar. QLibrary::unload() devolverá ` true`, pero la biblioteca seguirá cargada en el proceso.

Véase también ` resolve()` y ` load()`.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.