Loading...
Searching...
No Matches
XrdSysPlugin Class Reference

`#include <XrdSysPlugin.hh>`

Collaboration diagram for XrdSysPlugin:

## Public Member Functions

| XrdSysPlugin (char *ebuff, int eblen, const char *path, const char *lname, XrdVersionInfo *vinf=0, int msgNum=-1)
| XrdSysPlugin (XrdSysError *erp, const char *path)
| XrdSysPlugin (XrdSysError *erp, const char *path, const char *lname, XrdVersionInfo *vinf=0, int msgNum=-1)
| ~XrdSysPlugin ()
| Destructor.
void * | getLibrary (bool allMsgs=true, bool global=false)
void * | getPlugin (const char *pname, int optional, bool global)
void * | getPlugin (const char *pname, int optional=0)
void * | Persist ()

## Static Public Member Functions

static bool | Preload (const char *path, char *ebuff=0, int eblen=0)
static bool | VerCmp (XrdVersionInfo &vInf1, XrdVersionInfo &vInf2, bool noMsg=false)

## Detailed Description

Handy class to load run-time plugins and optionally check if the version is compatible with the caller's version number. Version numbers are defined as "aaa.bb.cc" where aaa is a decimnal major version, bb is a decimal minor version, and cc is the decimal patch version number. Only the major and, optionally, minor version numbers are checked. The checking rules are defined in XrdVersion.hh and are rather liberal in nature. In order to check versions, the plugin versioning rule must be defined in XrdVersion.hh and constructor #2 or #3 must be used. The symbolic name of the plugin's version information is the plugin symbol being looked up appended with "Version" and must be defined as an XrdVersionInfo structure.

Definition at line 52 of file XrdSysPlugin.hh.

## Constructor & Destructor Documentation

## XrdSysPlugin() [1/3]

XrdSysPlugin::XrdSysPlugin | ( | XrdSysError * | erp,
|  | const char * | path )

inline

Constructor #1 (version number checking is not to be performed)

Parameters

  erp | -> error message object to display error messages.
  path | -> path to the shared library containing a plug-in. If NULL the the executable image is searched for the plug-in. Storage must persist while this object is alive.

Definition at line 165 of file XrdSysPlugin.hh.

: eDest(erp), libName(0), libPath(path ? strdup(path) : 0),
libHandle(0), myInfo(0), eBuff(0), eBLen(0), msgCnt(-1) {}
eDest
static XrdSysError eDest(0,"crypto_")

## XrdSysPlugin() [2/3]

XrdSysPlugin::XrdSysPlugin | ( | XrdSysError * | erp,
|  | const char * | path,
|  | const char * | lname,
|  | XrdVersionInfo * | vinf = 0,
|  | int | msgNum = -1 )

inline

Constructor #2 (version number checking may be performed)

Parameters

  erp | -> error message object to display error messages.
  path | -> path to the shared library containing a plug-in. If NULL the the executable image is searched for the plug-in. Storage must persist while this object is alive.
  lname | -> logical name of the plugin library (e.g. osslib) to be used in any error messages. Storage must persist while this object is alive.
  vinf | -> permanent version information of the plug-in loader. If zero, then no version checking is performed.
  msgNum | -> Number of times getPlugin() is to produce a version message for a loaded plugin. The default is always.

Definition at line 185 of file XrdSysPlugin.hh.

: eDest(erp), libName(lname),
libPath(path ? strdup(path) : 0), libHandle(0),
myInfo(vinf), eBuff(0), eBLen(0), msgCnt(msgNum) {}

## XrdSysPlugin() [3/3]

XrdSysPlugin::XrdSysPlugin | ( | char * | ebuff,
|  | int | eblen,
|  | const char * | path,
|  | const char * | lname,
|  | XrdVersionInfo * | vinf = 0,
|  | int | msgNum = -1 )

inline

Constructor #3 (version number checking may be performed and any error is returned in a supplied buffer)

Parameters

  ebuff | -> buffer where eror message is to be placed. The message will always end with a null byte.
  eblen | -> length of the supplied buffer, eBuff.
  path | -> path to the shared library containing a plug-in. If NULL the the executable image is searched for the plug-in. Storage must persist while this object is alive.
  lname | -> logical name of the plugin library (e.g. osslib) to be used in any error messages. Storage must persist while this object is alive.
  vinf | -> permanent version information of the plug-in loader. If Zero, then no version checking is performed.
  msgNum | -> Number of times getPlugin() is to produce a version message for a loaded plugin. The default is always.

Definition at line 210 of file XrdSysPlugin.hh.

: eDest(0), libName(lname),
libPath(path ? strdup(path) : 0), libHandle(0),
myInfo(vinf), eBuff(ebuff), eBLen(eblen), msgCnt(msgNum) {}

## ~XrdSysPlugin()

XrdSysPlugin::~XrdSysPlugin | ( |  | ) |

Destructor.

Definition at line 72 of file XrdSysPlugin.cc.

{
if (libHandle) dlclose(libHandle);
if (libPath) free(libPath);
}

## Member Function Documentation

## getLibrary()

void * XrdSysPlugin::getLibrary | ( | bool | allMsgs = true,
|  | bool | global = false )

Prepare shared library for use (optional call).

Parameters

  allMsgs | When true messages all messages are handled as directed by the constructor. Otherwise, only messages regarding ENOENT (file not found ) are suppressed.
  global | when true then the symbols defined in the plug-in shared library are made available for symbol resolution of subsequently loaded libraries.

Returns
  !0 Library successfully prepared. =0 Library cannot be prepared; if mBuff is supplied, it contains the error message. If the file was not found, errno is set to ENOENT; otherwise to ENOEXEC.

Note
  This method is implicitly called when calling getPlugin().

Definition at line 255 of file XrdSysPlugin.cc.

{
void *myHandle;
int flags;
// Check if we should use the preload list
//
if (!(myHandle = libHandle) && plList) myHandle = Find(libPath);
// If already open, return the handle
//
if (myHandle) return myHandle;
// If no path is given then we want to just search the executable. This is easy
// for some platforms and more difficult for others. So, we do the best we can.
//
if (libPath) flags = DLflags();
else { flags = RTLD_NOW;
#ifndef WIN32
flags|= global ? RTLD_GLOBAL : RTLD_LOCAL;
#else
if (global && eDest) eDest->Emsg("getPlugin",
"request for global symbols unsupported under Windows - ignored");
#endif
}
// Try to open this library or the executable image
//
if ((myHandle = dlopen(libPath, flags))) libHandle = myHandle;
else {const char *eTxt = dlerror();
if (strcasestr(eTxt, "no such file")) errno = ENOENT;
else errno = ENOEXEC;
if (allMsgs || errno != ENOENT) libMsg(eTxt, " loading ");
}
// All done
//
return myHandle;
}

Referenced by getPlugin().

Here is the caller graph for this function:

## getPlugin() [1/2]

void * XrdSysPlugin::getPlugin | ( | const char * | pname,
|  | int | optional,
|  | bool | global )

Get the address of a plugin from a shared library, opening the plug-in shared library if not already open and optionally make the symbols global.

Parameters

  pname | the plug-in extern "C" symbolic name
  optional | when 0 then issue error message when symbol isn't found. Otherwise, the mising symbol is treated as an error. When optional is greater than 1, the load message is suppressed.
  global | when true then the symbols defined in the plug-in shared library are made available for symbol resolution of subsequently loaded libraries.

Returns
  Success: the address of the symbol in the shared library/executable. The address becomes invalid when this object is deleted unless Persist() is called prior to deletion. Failure: Null

Definition at line 304 of file XrdSysPlugin.cc.

{
XrdVERSIONINFODEF(urInfo, unknown, XrdVNUMUNK, "");
void *ep, *myHandle;
cvResult cvRC;
// Open whatever it is we need to open
//
if (!(myHandle = getLibrary(optional < 2, global))) return 0;
// Get the symbol. In the environment we have defined, null values are not
// allowed and we will issue an error.
//
if (!(ep = dlsym(myHandle, pname)))
{if (optional < 2) libMsg(dlerror(), " symbol %s in ", pname);
return 0;
}
// Check if we need to verify version compatibility
//
if ((cvRC = chkVersion(urInfo, pname, myHandle)) == cvBad) return 0;
// Print the loaded version unless message is suppressed or not needed
//
if (libPath && optional < 2 && msgCnt
&& (cvRC == cvClean || cvRC == cvMissing))
{char buff[128];
msgSuffix(" from ", buff, sizeof(buff));
msgCnt--;
if (cvRC == cvClean)
{const char *wTxt=(urInfo.vNum == XrdVNUMUNK ? "unreleased ":"");
Inform("loaded ", wTxt, urInfo.vStr, buff, libPath);
}
else if (cvRC == cvMissing)
{Inform("loaded unversioned ", pname, buff, libPath);}
}
// All done
//
return ep;
}
XrdVERSIONINFODEF
static XrdVERSIONINFODEF(compiledVer, XrdHttpProtocolTest, XrdVNUMBER, XrdVERSION)
XrdSysPlugin::getLibrary
void * getLibrary(bool allMsgs=true, bool global=false)
Definition XrdSysPlugin.cc:255

References getLibrary(), and XrdVERSIONINFODEF().

Here is the call graph for this function:

## getPlugin() [2/2]

void * XrdSysPlugin::getPlugin | ( | const char * | pname,
|  | int | optional = 0 )

Get the address of a plugin from a shared library, opening the plug-in shared library if not already open. Symbols in the library are local.

Parameters

  pname | the plug-in extern "C" symbolic name
  optional | when 0 then issue error message when symbol isn't found. Otherwise, the mising symbol is treated as an error.

Returns
  Success: the address of the symbol in the shared library/executable. The address becomes invalid when this object is deleted unless Persist() is called prior to deletion. Failure: Null

Definition at line 299 of file XrdSysPlugin.cc.

{
return getPlugin(pname, optional, false);
}
XrdSysPlugin::getPlugin
void * getPlugin(const char *pname, int optional=0)
Definition XrdSysPlugin.cc:299

References getPlugin().

Referenced by getPlugin(), and LoadFS().

Here is the call graph for this function:
Here is the caller graph for this function:

## Persist()

void * XrdSysPlugin::Persist | ( |  | ) |

inline

Make library persistent even when the plugin object is deleted. Note that if getPlugin() is called afterwards, the library will be re-opened!

Returns
  pointer to the opened shared library.

Definition at line 118 of file XrdSysPlugin.hh.

{void *lHan = libHandle; libHandle = 0; return lHan;}

Referenced by LoadFS().

Here is the caller graph for this function:

## Preload()

bool XrdSysPlugin::Preload | ( | const char * | path,
|  | char * | ebuff = 0,
|  | int | eblen = 0 )

static

Preload a shared library. This method is meant for those threading models that require libraries to be opened in the main thread (e.g. MacOS). This method is meant to be called before therads start and is not thread-safe.

Parameters

  path | -> to the library path, typically this should just be the library filename so that LD_LIBRARY_PATH is used to discover the directory path. This allows getPlugin() to properly match preloaded libraries.
  ebuff | -> buffer where eror message is to be placed. The message will always end with a null byte. If no error buffer is supplied, any error messages are discarded.
  eblen | -> length of the supplied buffer, eBuff.

Returns
  True The library was preloaded. False The library could not be preloaded, ebuff, if supplied, contains the error message text.

Definition at line 435 of file XrdSysPlugin.cc.

{
struct PLlist *plP;
void *myHandle;
// First see if this is already in the preload list
//
if (Find(path)) return true;
// Try to open the library
//
if (!(myHandle = dlopen(path, DLflags())))
{if (ebuff && eblen > 0)
{const char *dlMsg = dlerror();
snprintf(ebuff, eblen, "Plugin unable to load %s; %s", path,
(dlMsg ? dlMsg : "unknown system error"));
}
return false;
}
// Add the library handle
//
plP = new PLlist;
plP->libHandle = myHandle;
plP->libPath = strdup(path);
plP->next = plList;
plList = plP;
// All done
//
return true;
}

Referenced by XrdOucPreload().

Here is the caller graph for this function:

## VerCmp()

bool XrdSysPlugin::VerCmp | ( | XrdVersionInfo & | vInf1,
|  | XrdVersionInfo & | vInf2,
|  | bool | noMsg = false )

static

Compare two versions for compatibility, optionally printing a warning.

Parameters

  vInf1 | -> Version information for source.
  vInf2 | -> Version information for target.
  noMsg | -> If true, no error messages are written to stderr.

Returns
  True if versions are compatible (i.e. major and minor versions are identical as required for locally linked code); false otherwise.

Definition at line 472 of file XrdSysPlugin.cc.

{
const char *mTxt;
char v1buff[128], v2buff[128];
int unRel;
// Do a quick return if the version need not be checked or are equal
//
if (vInfo1.vNum <= 0 || vInfo1.vNum == vInfo2.vNum) return true;
// As it works out, many times two modules wind up in different shared
// libraries. For consistency we require that both major.minor version be the
// same unless either is unreleased (i.e. test). Issue warning if need be.
//
mTxt = (vInfo1.vNum == XrdVNUMUNK ? "unreleased " : "");
sprintf(v1buff, " %sversion %s", mTxt, vInfo1.vStr);
unRel = *mTxt;
mTxt = (vInfo2.vNum == XrdVNUMUNK ? "unreleased " : "");
sprintf(v2buff, " %sversion %s", mTxt, vInfo2.vStr);
unRel |= *mTxt;
if (unRel || vInfo1.vNum/100 == vInfo2.vNum/100) mTxt = "";
else mTxt = " which is incompatible!";
if (!noMsg)
std::cerr <<"Plugin: " <<v1buff <<" is using " <<v2buff <<mTxt <<std::endl;
return (*mTxt == 0);
}

Referenced by XrdCksConfig::XrdCksConfig(), XrdCksLoader::XrdCksLoader(), XrdOucN2NLoader::Load(), XrdOfsConfigPI::New(), XrdCmsFinderRMT::VCheck(), XrdCmsFinderTRG::VCheck(), XrdAccDefaultAuthorizeObject(), and XrdOssGetSS().

Here is the caller graph for this function:

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

- XrdSysPlugin.hh
- XrdSysPlugin.cc