XrdSysPlugin Class Reference

#include <XrdSysPlugin.hh>

Collaboration diagram for XrdSysPlugin:

Classes
struct	PLlist

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

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)

Private Types
enum	cvResult {   cvBad = 0 , cvNone , cvMissing , cvClean ,   cvDirty }

Private Member Functions
cvResult	badVersion (XrdVersionInfo &urInfo, char mmv, int majv, int minv)
cvResult	chkVersion (XrdVersionInfo &urInfo, const char *pname, void *lh)
void	Inform (const char *txt1, const char *txt2=0, const char *txt3=0, const char *txt4=0, const char *txt5=0, int noHush=0)
cvResult	libMsg (const char *txt1, const char *txt2, const char *mSym=0)
const char *	msgSuffix (const char *Word, char *buff, int bsz)

Static Private Member Functions
static int	DLflags ()
static void *	Find (const char *libname)

Private Attributes
XrdSysError *	eDest
const char *	libName
char *	libPath
void *	libHandle
XrdVersionInfo *	myInfo
char *	eBuff
int	eBLen
int	msgCnt

Static Private Attributes
static PLlist *	plList

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.

Member Enumeration Documentation

cvResult

enum XrdSysPlugin::cvResult

private

Enumerator
cvBad
cvNone
cvMissing
cvClean
cvDirty

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.

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.

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.

~XrdSysPlugin()

XrdSysPlugin::~XrdSysPlugin

(

)

Destructor.

Member Function Documentation

badVersion()

cvResult XrdSysPlugin::badVersion ( XrdVersionInfo &  urInfo, char  mmv, int  majv, int  minv  )

private

chkVersion()

cvResult XrdSysPlugin::chkVersion ( XrdVersionInfo &  urInfo, const char *  pname, void *  lh  )

private

DLflags()

static int XrdSysPlugin::DLflags ( )

staticprivate

Find()

static void * XrdSysPlugin::Find ( const char *  libname )

staticprivate

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().

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

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

Inform()

void XrdSysPlugin::Inform ( const char *  txt1, const char *  txt2 = 0, const char *  txt3 = 0, const char *  txt4 = 0, const char *  txt5 = 0, int  noHush = 0  )

private

libMsg()

cvResult XrdSysPlugin::libMsg ( const char *  txt1, const char *  txt2, const char *  mSym = 0  )

private

msgSuffix()

const char * XrdSysPlugin::msgSuffix ( const char *  Word, char *  buff, int  bsz  )

private

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.

References libHandle.

Preload()

static 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.

VerCmp()

static 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.

Member Data Documentation

eBLen

int XrdSysPlugin::eBLen

private

eBuff

char* XrdSysPlugin::eBuff

private

eDest

XrdSysError* XrdSysPlugin::eDest

private

libHandle

void* XrdSysPlugin::libHandle

private

Referenced by Persist().

libName

const char* XrdSysPlugin::libName

private

libPath

char* XrdSysPlugin::libPath

private

msgCnt

int XrdSysPlugin::msgCnt

private

myInfo

XrdVersionInfo* XrdSysPlugin::myInfo

private

plList

PLlist* XrdSysPlugin::plList

staticprivate

---

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

• XrdSysPlugin.hh