QLibrary Class
The QLibrary class loads shared libraries at runtime. More…
| Header | #include <QLibrary> |
|---|---|
| CMake | target_link_libraries(app PRIVATE Nt::Core) |
| Module | Nt Core C++ Classes |
| Inherits | QObject |
List of all members, including inherited members
Public Types
Public Functions
| QLibrary(QObject *parent = nullptr) | |
| QLibrary(const QString &fileName, QObject *parent = nullptr) | |
| QLibrary(const QString &fileName, int verNum, QObject *parent = nullptr) | |
| QLibrary(const QString &fileName, const QString &version, QObject *parent = nullptr) | |
| ~QLibrary() | |
| QFunctionPointer | resolve(const char *symbol) |
| bool | load() |
| bool | unload() |
| bool | isLoaded() const |
| void | setFileName(const QString &fileName) |
| QString | fileName() const |
| void | setFileNameAndVersion(const QString &fileName, int verNum) |
| void | setFileNameAndVersion(const QString &fileName, const QString &version) |
| QString | errorString() const |
| void | setLoadHints(LoadHints hints) |
| LoadHints | loadHints() const |
Static Public Members
| QFunctionPointer | resolve(const QString &fileName, const char *symbol) |
| QFunctionPointer | resolve(const QString &fileName, int verNum, const char *symbol) |
| QFunctionPointer | resolve(const QString &fileName, const QString &version, const char *symbol) |
| bool | isLibrary(const QString &fileName) |
Detailed Description
A QLibrary names a shared library, loads it into the process, and finds the functions that the library exports by their names:
QLibrary library(u"mylib"_s);
using Average = int (*)(int, int);
if (auto average = reinterpret_cast<Average>(library.resolve("average")))
qDebug() << average(4, 8);
else
qWarning() << library.errorString();
The file name may leave out what differs between platforms: for mylib, libmylib.so is tried as well, and with a version libmylib.so.2. A name without a directory is looked for where the system looks for libraries. resolve() loads the library if needed.
A function can be resolved by name only if the library exports it with C linkage:
extern "C" Q_DECL_EXPORT int average(int a, int b) { return (a + b) / 2; }
Every QLibrary for the same file shares one loaded library, which stays in memory until each of them has called unload(), or the program ends. Destroying a QLibrary does not unload.
See also QObject.
Differences from Qt
Libraries are loaded with dlopen(), so the class works on Linux, Android and macOS; on macOS the suffixes .dylib and .bundle are not added to a name. LoadArchiveMemberHint is ignored: it is for AIX. There is no QPluginLoader yet.
The class is not built for Zephyr, where QT_NO_LIBRARY is defined instead. See Nt on Zephyr.
Member Type Documentation
enum QLibrary::LoadHint
The hints change how load() loads the library.
| Constant | Description |
|---|---|
QLibrary::ResolveAllSymbolsHint | Resolve every symbol of the library when it is loaded, and not when a function is first called. Loading fails at once if a symbol is missing. |
QLibrary::ExportExternalSymbolsHint | Make the symbols of the library available to libraries that are loaded later. |
QLibrary::LoadArchiveMemberHint | Allow the file name to name a member of an archive. Ignored. |
QLibrary::PreventUnloadHint | Keep the library in memory when unload() is called, so that its static variables stay. |
QLibrary::DeepBindHint | Let the library prefer its own symbols to those of the program and of libraries loaded before it. Only where the C library supports it. |
typedef QLibrary::LoadHints
The LoadHints type is a typedef for QFlags<LoadHint>. It stores an OR combination of LoadHint values.
Member Function Documentation
QLibrary::QLibrary(QObject *parent = nullptr)
Constructs a library object with the given parent and no file name.
See also setFileName().
QLibrary::QLibrary(const QString &fileName, QObject *parent = nullptr)
Constructs a library object with the given parent that will load the library fileName. Nothing is loaded yet.
QLibrary::QLibrary(const QString &fileName, int verNum, QObject *parent = nullptr)
Constructs a library object with the given parent that will load the major version verNum of the library fileName. A negative verNum means no version.
QLibrary::QLibrary(const QString &fileName, const QString &version, QObject *parent = nullptr)
Constructs a library object with the given parent that will load the version version, such as 1.2, of the library fileName.
QLibrary::~QLibrary()
Destroys the library object. The library stays loaded: call unload() first to release it.
QString QLibrary::errorString() const
Returns a text that says why the last call of load(), resolve() or unload() failed, or an empty string if it succeeded.
QString QLibrary::fileName() const
Returns the file name of the library: the name that was set or, once the library is loaded, the path of the file that was found.
See also setFileName().
bool QLibrary::isLibrary(const QString &fileName)
Returns true if fileName has the suffix of a shared library: .so, also when a version follows it, as in libz.so.1.3.
bool QLibrary::isLoaded() const
Returns true if load() succeeded on this object and unload() has not been called since.
See also load().
bool QLibrary::load()
Loads the library and returns true if it is loaded, also when it was loaded before. If it cannot be loaded, returns false and errorString() says why. resolve() calls this, so a program rarely needs to.
See also unload() and isLoaded().
LoadHints QLibrary::loadHints() const
Returns the hints that load() uses.
See also setLoadHints().
QFunctionPointer QLibrary::resolve(const char *symbol)
Returns the address of the function symbol that the library exports, loading the library first if needed. Returns nullptr if the library cannot be loaded or has no such symbol; errorString() then says why. Cast the result to the type of the function.
See also load().
QFunctionPointer QLibrary::resolve(const QString &fileName, const char *symbol)
This is an overloaded function.
Loads the library fileName and returns the address of its function symbol, or nullptr. The library stays loaded.
QFunctionPointer QLibrary::resolve(const QString &fileName, int verNum, const char *symbol)
This is an overloaded function.
Loads the major version verNum of the library fileName and returns the address of its function symbol, or nullptr.
QFunctionPointer QLibrary::resolve(const QString &fileName, const QString &version, const char *symbol)
This is an overloaded function.
Loads the version version of the library fileName and returns the address of its function symbol, or nullptr.
void QLibrary::setFileName(const QString &fileName)
Sets the file name of the library to fileName, without a version. Leave out the prefix and suffix of the platform to stay portable. A QLibrary that is loaded then stands for the other library; the one that was loaded stays loaded.
See also fileName() and setFileNameAndVersion().
void QLibrary::setFileNameAndVersion(const QString &fileName, int verNum)
Sets the file name to fileName and the version to load to the major version verNum. A negative verNum means no version.
See also setFileName().
void QLibrary::setFileNameAndVersion(const QString &fileName, const QString &version)
This is an overloaded function.
Sets the file name to fileName and the version to load to version, such as 1.2.
void QLibrary::setLoadHints(LoadHints hints)
Sets the hints that load() uses to hints. The default is no hint: symbols are resolved when they are first used and are not exported to other libraries. Hints that are set after the library is loaded have no effect.
See also loadHints().
bool QLibrary::unload()
Releases the library. Returns true if that removed it from memory, and false if this object had not loaded it or another QLibrary still uses it.
See also load().