shared_library.h File Reference

#include <string.h>
#include "rcutils/allocator.h"
#include "rcutils/types/rcutils_ret.h"
#include "rcutils/macros.h"
#include "rcutils/visibility_control.h"

Include dependency graph for shared_library.h:

Go to the source code of this file.

Classes
struct	rcutils_shared_library_t
	Handle to a loaded shared library. More...

Typedefs
typedef struct rcutils_shared_library_t	rcutils_shared_library_t
	Handle to a loaded shared library. More...

Functions
rcutils_shared_library_t	rcutils_get_zero_initialized_shared_library (void)
	Return an empty shared library struct. More...
rcutils_ret_t	rcutils_load_shared_library (rcutils_shared_library_t *lib, const char *library_path, rcutils_allocator_t allocator)
	Return shared library pointer. More...
void *	rcutils_get_symbol (const rcutils_shared_library_t *lib, const char *symbol_name)
	Return shared library symbol pointer. More...
bool	rcutils_has_symbol (const rcutils_shared_library_t *lib, const char *symbol_name)
	Return true if the shared library contains a specific symbol name otherwise returns false. More...
rcutils_ret_t	rcutils_unload_shared_library (rcutils_shared_library_t *lib)
	Unload the shared library. More...
bool	rcutils_is_shared_library_loaded (rcutils_shared_library_t *lib)
	Check if the library is loaded. More...
rcutils_ret_t	rcutils_get_platform_library_name (const char *library_name, char *library_name_platform, unsigned int buffer_size, bool debug)
	Get the library name for the compiled platform. More...

Typedef Documentation

rcutils_shared_library_t

typedef struct rcutils_shared_library_t rcutils_shared_library_t

Handle to a loaded shared library.

Function Documentation

rcutils_get_zero_initialized_shared_library()

rcutils_shared_library_t rcutils_get_zero_initialized_shared_library

(

void

)

Return an empty shared library struct.

This function returns an empty and zero initialized shared library struct.

Example:

// Do not do this:
// rcutils_shared_library_t foo;
// rcutils_ret_t ret = rcutils_load_shared_library(
//     &foo,
//    "library_name",
//    rcutils_get_default_allocator()); // undefined behavior!
// or
// rcutils_ret_t ret = rcutils_unload_shared_library(&foo); // undefined behavior!
 
// Do this instead:
rcutils_shared_library_t bar = rcutils_get_zero_initialized_shared_library();
rcutils_load_shared_library(&bar, "library_name", rcutils_get_default_allocator()); // ok
void * symbol = rcutils_get_symbol(&bar, "bazinga"); // ok
bool is_bazinga_symbol = rcutils_has_symbol(&bar, "bazinga"); // ok
rcutils_ret_t ret = rcutils_unload_shared_library(&bar); // ok
if (ret != RCUTILS_RET_ERROR) {
  // error handling
}

rcutils_load_shared_library()

rcutils_ret_t rcutils_load_shared_library	(	rcutils_shared_library_t *	lib,
		const char *	library_path,
		rcutils_allocator_t	allocator
	)

Return shared library pointer.

Parameters

[in,out]	lib	struct with the shared library pointer and shared library path name
[in]	library_path	string with the path of the library
[in]	allocator	to be used to allocate and deallocate memory

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_BAD_ALLOC if memory allocation fails, or

RCUTILS_RET_ERROR if an unknown error occurs, or

RCUTILS_RET_INVALID_ARGUMENT for invalid arguments.

rcutils_get_symbol()

void* rcutils_get_symbol	(	const rcutils_shared_library_t *	lib,
		const char *	symbol_name
	)

Return shared library symbol pointer.

Parameters

[in]	lib	struct with the shared library pointer and shared library path name
[in]	symbol_name	name of the symbol inside the shared library

Returns

shared library symbol pointer, or

NULL if the symbol doesn't exist.

rcutils_has_symbol()

bool rcutils_has_symbol	(	const rcutils_shared_library_t *	lib,
		const char *	symbol_name
	)

Return true if the shared library contains a specific symbol name otherwise returns false.

Parameters

[in]	lib	struct with the shared library pointer and shared library path name
[in]	symbol_name	name of the symbol inside the shared library

Returns

true if the symbol exists, or

false otherwise.

rcutils_unload_shared_library()

rcutils_ret_t rcutils_unload_shared_library

(

rcutils_shared_library_t *

lib

)

Unload the shared library.

Parameters

[in]

lib

rcutils_shared_library_t to be finalized

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or

RCUTILS_RET_ERROR if an unknown error occurs

rcutils_is_shared_library_loaded()

bool rcutils_is_shared_library_loaded

(

rcutils_shared_library_t *

lib

)

Check if the library is loaded.

This function only determines if "unload" has been called on the current shared library handle. It could very well be that a second shared library handle is still open and therefore the library being loaded.

Parameters

[in]

lib

rcutils_shared_library_t to check

Returns

true if library is loaded, or

false otherwise.

rcutils_get_platform_library_name()

rcutils_ret_t rcutils_get_platform_library_name	(	const char *	library_name,
		char *	library_name_platform,
		unsigned int	buffer_size,
		bool	debug
	)

Get the library name for the compiled platform.

Parameters

[in]	library_name	library base name (without prefix and extension)
[out]	library_name_platform	library name for the compiled platform
[in]	buffer_size	size of library_name_platform buffer
[in]	debug	if true the library will return a debug library name, otherwise it returns a normal library path

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_ERROR if an unknown error occurs