Loading...
Searching...
No Matches
casacore::DynLib Class Reference
casa package (libcasa_casa) » OS_module

More...

`#include <DynLib.h>`

## Public Member Functions

| DynLib (const std::string &library, const std::string &prefix=std::string(), const std::string &funcName=std::string(), bool closeOnDestruction=True)
| Load the dynamic library.
| DynLib (const std::string &library, const std::string &prefix, const std::string &version, const std::string &funcName, bool closeOnDestruction=True)
| The same as above, but it is tried with and without the given version (in that order).
| DynLib (const std::string &library, Bool closeOnDestruction, const std::string &prefix="lib", const std::string &suffix=".so")
| Load the dynamic library with the given name, prefix, and suffix.
| ~DynLib ()
| Close the dynamic library if told so in the constructor.
void * | getFunc (const std::string &funcName)
| Get a pointer to a function in the dynamic library.
void * | getHandle () const
| Get the dynamic library handle.
const std::string & | getError () const
| Get the possible error.

## Private Member Functions

void | attach (const std::string &name, const std::string &prefix, const std::string &version, const std::string &funcName)
| Try to open the library with some prefixes, suffixes and versions and to execute the initialization function.
std::string | tryOpen (const std::string &name, const std::string &libdir, const std::string &prefix, const std::string &version)
| Try to open the library with some prefixes, suffixes and versions If successful, itsHandle is filled and the full library name is returned.
void | open (const std::string &name)
| Open (load) the dynamic library.
void | close ()
| Close (unload) the dynamic library (if opened).
std::string | tryCasacorePath (const std::string &library, const std::string &prefix, const std::string &version)
| Try if the library can be opened using CASACORE_LDPATH.

## Private Attributes

void * | itsHandle
Bool | itsDoClose
std::string | itsError

## Detailed Description

Class to handle loading of dynamic libraries

### Review Status

Reviewed By:
  UNKNOWN
Date Reviewed:
  before2004/08/25

### Intended use:

Public interface

### Prerequisite

- Basic knowledge of the dlopen function family

### Synopsis

This class makes it possible to load a dynamic library and execute an initialization function. Furthermore, one can get a pointer to any function in the dynamic library and close the library.

The search path of the shared library is as follows:

- If the environment library CASACORE_LDPATH is defined, it is tried to find the library using that path.
- If not defined or not found, the system's (DY)LD_LIBRARY_PATH is used.
- The library looked for has the name 'prefix'libname'suffix'.
  As prefix first "lib" is used, thereafter the given one (e.g., "libcasa_").
  As suffix first ".so" is used, thereafter ".dylib" (for OS-X).

It is a wrapper around functions dlopen, dlsym, and dlclose. If dlopen and so are not supported on a platform, the class acts as if the shared library could not be found.

### Example

DynLib dl("derivedmscal", "libcasa_", "register_derivedmscal");
AlwaysAssert (dl.getHandle());
AlwaysAssert
#define AlwaysAssert(expr, exception)
These marcos are provided for use instead of simply using the constructors of assert_ to allow additi...
Definition Assert.h:155
casacore::DynLib::DynLib
DynLib(const std::string &library, const std::string &prefix=std::string(), const std::string &funcName=std::string(), bool closeOnDestruction=True)
Load the dynamic library.

Using this loads the shared library libcasa_derivedmscal.so and executes the given register initialization function.

### Motivation

dlopen is a standard UNIX system call, but some operating systems do not support it or have different function names (notably Windows). In this way use of dynamic libraries is centralized and can easily b tailored as needed.

Definition at line 85 of file DynLib.h.

## Constructor & Destructor Documentation

## DynLib() [1/3]

casacore::DynLib::DynLib | ( | const std::string & | library,
|  | const std::string & | prefix = std::string(),
|  | const std::string & | funcName = std::string(),
|  | bool | closeOnDestruction = True )

Load the dynamic library.

It is tried with prefixes prefix and "lib" (in that order) and with suffix ".so" or ".dylib" (for Apple). No library version number is used. If not loaded successfully, an exception is thrown.
If a non-empty funcName is given, that function is looked up and executed for initialization purposes. Its signature must be void func(). Note that the function name should not be mangled, thus declared extern "C". An exception is thrown if the library is loaded successfully, but funcName could not be found.
If closeOnDestruction=True, the dynamic library is closed on destruction of the DynLib object.

References casacore::True.

## DynLib() [2/3]

casacore::DynLib::DynLib | ( | const std::string & | library,
|  | const std::string & | prefix,
|  | const std::string & | version,
|  | const std::string & | funcName,
|  | bool | closeOnDestruction = True )

The same as above, but it is tried with and without the given version (in that order).

References casacore::True.

## DynLib() [3/3]

casacore::DynLib::DynLib | ( | const std::string & | library,
|  | Bool | closeOnDestruction,
|  | const std::string & | prefix = "lib",
|  | const std::string & | suffix = ".so" )

Load the dynamic library with the given name, prefix, and suffix.

If not loaded successfully, the internal handle is NULL.
If closeOnDestruction=True, the dynamic library is closed when the DynLib object is destructed.

## ~DynLib()

casacore::DynLib::~DynLib | ( |  | ) |

Close the dynamic library if told so in the constructor.

## Member Function Documentation

## attach()

void casacore::DynLib::attach | ( | const std::string & | name,
|  | const std::string & | prefix,
|  | const std::string & | version,
|  | const std::string & | funcName )

private

Try to open the library with some prefixes, suffixes and versions and to execute the initialization function.

If successful, itsHandle is filled. Otherwise an exception is thrown.

References casacore::name().

## close()

void casacore::DynLib::close | ( |  | ) |

private

Close (unload) the dynamic library (if opened).

## getError()

const std::string & casacore::DynLib::getError | ( |  | ) | const

inline

Get the possible error.

Definition at line 155 of file DynLib.h.

References itsError.

## getFunc()

void * casacore::DynLib::getFunc | ( | const std::string & | funcName | ) |

Get a pointer to a function in the dynamic library.

The pointer has to be casted with a reinterpret_cast to a function pointer with the correct signature. When compiling with -pedantic the compiler will give a warning for such a cast, because on some systems (in particular some micro-controllers) a data pointer differs from a function pointer. However, that problem cannot be solved. For example:

typedef Int MyFunc(Int, Int);
void* initfunc = DynLib::getFunc (mod, ("register_"+name).c_str());
if (initFunc) {
MyFunc* func = reinterpret_cast<MyFunc*>(initfunc);
Int result = func(1,2);
}
casacore::DynLib::getFunc
void * getFunc(const std::string &funcName)
Get a pointer to a function in the dynamic library.
casacore::name
String name() const
Return the name of the field.
Definition RecordField.h:163
casacore::Int
int Int
Definition aipstype.h:48

casts to a function returning Int and taking two Ints.
A null pointer is returned if the function could not be found.

## getHandle()

void * casacore::DynLib::getHandle | ( |  | ) | const

inline

Get the dynamic library handle.

Definition at line 151 of file DynLib.h.

References itsHandle.

## open()

void casacore::DynLib::open | ( | const std::string & | name | ) |

private

Open (load) the dynamic library.

References casacore::name().

## tryCasacorePath()

std::string casacore::DynLib::tryCasacorePath | ( | const std::string & | library,
|  | const std::string & | prefix,
|  | const std::string & | version )

private

Try if the library can be opened using CASACORE_LDPATH.

## tryOpen()

std::string casacore::DynLib::tryOpen | ( | const std::string & | name,
|  | const std::string & | libdir,
|  | const std::string & | prefix,
|  | const std::string & | version )

private

Try to open the library with some prefixes, suffixes and versions If successful, itsHandle is filled and the full library name is returned.

Otherwise an empty name is returned.

References casacore::name().

## Member Data Documentation

## itsDoClose

Bool casacore::DynLib::itsDoClose

private

Definition at line 189 of file DynLib.h.

## itsError

std::string casacore::DynLib::itsError

private

Definition at line 190 of file DynLib.h.

Referenced by getError().

## itsHandle

void* casacore::DynLib::itsHandle

private

Definition at line 188 of file DynLib.h.

Referenced by getHandle().

The documentation for this class was generated from the following file:

- casa/OS/DynLib.h