150 lines
4.6 KiB
C
150 lines
4.6 KiB
C
|
|
/*
|
|
* Copyright(c) 2006 to 2022 ZettaScale Technology and others
|
|
*
|
|
* This program and the accompanying materials are made available under the
|
|
* terms of the Eclipse Public License v. 2.0 which is available at
|
|
* http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
|
|
* v. 1.0 which is available at
|
|
* http://www.eclipse.org/org/documents/edl-v10.php.
|
|
*
|
|
* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
|
|
*/
|
|
#ifndef DDSRT_DYNLIB_H
|
|
#define DDSRT_DYNLIB_H
|
|
|
|
#include "dds/export.h"
|
|
#include "dds/config.h"
|
|
#include "dds/ddsrt/types.h"
|
|
#include "dds/ddsrt/retcode.h"
|
|
#include "dds/ddsrt/attributes.h"
|
|
|
|
#if DDSRT_HAVE_DYNLIB
|
|
|
|
#if defined (__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
|
|
//typedef void *ddsrt_dynlib_t;
|
|
typedef struct ddsrt_dynlib *ddsrt_dynlib_t;
|
|
|
|
|
|
/**
|
|
* @brief Load a dynamic shared library.
|
|
*
|
|
* The function ddsrt_dlopen() loads the dynamic shared object (shared library)
|
|
* file, identified by 'name', sets the handle parameter for the loaded library and
|
|
* returns the result with dds return code.
|
|
*
|
|
* If the 'translate' boolean is true, this function will first try to open the
|
|
* library with a translated 'name'. Translated in this context means that if
|
|
* "mylibrary" is provided, it will be translated into libmylibrary.so,
|
|
* libmylibrary.dylib or mylibrary.dll depending on the platform.
|
|
* This translation only happens when the given name does not contain
|
|
* a directory.
|
|
* If the function isn't able to load the library with the translated name, it
|
|
* will still try the given name.
|
|
*
|
|
* @param[in] name Library file name.
|
|
* @param[in] translate Automatic name translation on/off.
|
|
* @param[out] handle Library handle that will be assigned after successfull operation. It is assigned to NULL if loading fails.
|
|
*
|
|
* @returns A dds_return_t indicating success or failure.
|
|
*
|
|
* @retval DDS_RETCODE_OK
|
|
* Library handle was successfully loaded.
|
|
* @retval DDS_RETCODE_BAD_PARAM
|
|
* There is an invalid input in the parameter list
|
|
* @retval DDS_RETCODE_ERROR
|
|
* Loading failed.
|
|
* Use ddsrt_dlerror() to diagnose the failure.
|
|
*/
|
|
DDS_EXPORT dds_return_t
|
|
ddsrt_dlopen(
|
|
const char *name,
|
|
bool translate,
|
|
ddsrt_dynlib_t *handle) ddsrt_nonnull_all;
|
|
|
|
/**
|
|
* @brief Close the library.
|
|
*
|
|
* The function ddsrt_dlclose() informs the system that the
|
|
* library, identified by 'handle', is no longer needed.
|
|
* will get the memory address of a symbol,
|
|
* identified by 'symbol', from a loaded library 'handle'.
|
|
*
|
|
* @param[in] handle Library handle.
|
|
*
|
|
* @returns A dds_return_t indicating success or failure.
|
|
*
|
|
* @retval DDS_RETCODE_OK
|
|
* Library handle was successfully closed.
|
|
* @retval DDS_RETCODE_ERROR
|
|
* Library closing failed.
|
|
* Use ddsrt_dlerror() to diagnose the failure.
|
|
*/
|
|
DDS_EXPORT dds_return_t
|
|
ddsrt_dlclose(
|
|
ddsrt_dynlib_t handle);
|
|
|
|
/**
|
|
* @brief Get the memory address of a symbol.
|
|
*
|
|
* The function ddsrt_dlsym() will get the memory address of a symbol,
|
|
* identified by 'symbol', from a loaded library 'handle'.
|
|
*
|
|
* @param[in] handle Library handle.
|
|
* @param[in] symbol Symbol name.
|
|
* @param[out] address The memory address of the loaded symbol (void*).
|
|
*
|
|
* @returns A dds_return_t indicating success or failure.
|
|
*
|
|
* @retval DDS_RETCODE_OK
|
|
* Symbol was found in the loaded library.
|
|
* Address parameter is ready to use.
|
|
* @retval DDS_RETCODE_ERROR
|
|
* Symbol was not found.
|
|
* Use ddsrt_dlerror() to diagnose the failure.
|
|
*/
|
|
DDS_EXPORT dds_return_t
|
|
ddsrt_dlsym(
|
|
ddsrt_dynlib_t handle,
|
|
const char *symbol,
|
|
void **address);
|
|
|
|
/**
|
|
* @brief Get the most recent library related error.
|
|
*
|
|
* The function ddsrt_dlerror() will return the most recent error of a
|
|
* call to ddsrt_dlopen, ddsrt_dlclose, ddsrt_dlsym in human readable form.
|
|
*
|
|
* If no error was found, it's either due to the fact that there
|
|
* actually was no error since init or last ddsrt_dlerror() call,
|
|
* or due to an unknown unrelated error.
|
|
*
|
|
* @param[out] buf Buffer to store the error message
|
|
* @param[in] buflen The length of the provided buffer (must be > 0).
|
|
*
|
|
* @returns A dds_return_t indicating success (>0) or failure.
|
|
*
|
|
* @retval >0
|
|
* The length of the returned error message
|
|
* @retval 0
|
|
* No dynamic library loading related error present
|
|
* @retval DDS_RETCODE_NOT_ENOUGH_SPACE
|
|
* Buffer is not large enough to hold the error message
|
|
*/
|
|
DDS_EXPORT dds_return_t
|
|
ddsrt_dlerror(
|
|
char *buf,
|
|
size_t buflen);
|
|
|
|
#if defined (__cplusplus)
|
|
}
|
|
#endif
|
|
|
|
#endif /* DDSRT_HAVE_DYNLIB */
|
|
|
|
#endif /* DDSRT_DYNLIB_H */
|