vpr::LibraryDYLD

vpr::LibraryDYLD Class Reference

Low-level class for loading symbols dynamically. More...

#include <vpr/DynLoad/Library.h>

List of all members.

Public Member Functions

 LibraryDYLD (const std::string &name)
 Constructs a named library object.
 LibraryDYLD ()
 Default constructor.
 LibraryDYLD (const LibraryDYLD &lib)
 Copy constructor.
 ~LibraryDYLD ()
 Unloads the library if one has been loaded.
LibraryDYLD & operator= (const LibraryDYLD &lib)
 Overlaoded assignment operator.
const std::string & getName () const
 Retrieves the name of the library associated with this object.
vpr::ReturnStatus load ()
 Loads the library named by this object.
vpr::ReturnStatus unload ()
 This function undoes the effect of the load() method.
bool isLoaded () const
 Returns whether this library has been loaded from local storage.
void * findSymbol (const char *symbolName)
 Finds and returns an untyped reference to the specified symbol in this library.
void * findSymbol (const std::string &symbolName)

Static Public Member Functions

static void * findSymbolAndLibrary (const char *symbolName, LibraryDYLD &lib)
 Finds a symbol in one of the currently loaded libraries, and returns both the symbol and the library in which it was found.
static void * findSymbolAndLibrary (const std::string &symbolName, LibraryDYLD &lib)

Protected Member Functions

void copy (const LibraryDYLD &lib)
 Makes a copy of the given vpr::LibraryDYLD into this object.
void * internalDlopen (const char *filename, int flag)
const char * internalDlerror ()
void * internalDlsym (void *dl_restrict handle, const char *dl_restrict symbol)
int internalDlclose (void *handle)

Detailed Description

Low-level class for loading symbols dynamically.

This implementation wraps the Darwin dyld interface, the preferred method for dynamic symbol loading on Mac OS X. The idea of this class is to provide the basic features needed to load a single shared/dynamic library and to get symbols from it. No features for path extension are provided here.

This class is typedef'd to vpr::Library.

Definition at line 73 of file LibraryDYLD.h.

Constructor & Destructor Documentation

vpr::LibraryDYLD::LibraryDYLD ( const std::string &  name  )  [inline]

Constructs a named library object.

This is the only mechanism to name the library to be loaded, and once named, the library's name cannot be changed.

Parameters:
name The name of the library to load. It must include the actual name of the library (e.g., "mylib.dll" or "libmylib.so"). The name may be an absolute path or a relative path.

Definition at line 85 of file LibraryDYLD.h.

00086       : mName(name)
00087       , mLibrary(NULL)
00088    {
00089       ;
00090    }

vpr::LibraryDYLD::LibraryDYLD (  )  [inline]

Default constructor.

Using this constructor will prevent setting a name for the library to be loaded, but the created object may still be useful. For example, it can be used to provide access to all symbols currently loaded, or ir may be used as an argument to findSymbolAndLibrary().

See also:
findSymbolAndLibrary, load

Definition at line 101 of file LibraryDYLD.h.

00102       : mName("")
00103       , mLibrary(NULL)
00104    {
00105       ;
00106    }

vpr::LibraryDYLD::LibraryDYLD ( const LibraryDYLD &  lib  )  [inline]

Copy constructor.

Definition at line 111 of file LibraryDYLD.h.

References copy().

00112       : mName("")
00113       , mLibrary(NULL)
00114    {
00115       copy(lib);
00116    }

vpr::LibraryDYLD::~LibraryDYLD (  )  [inline]

Unloads the library if one has been loaded.

Definition at line 121 of file LibraryDYLD.h.

References unload().

00122    {
00123       if ( NULL != mLibrary )
00124       {
00125          unload();
00126       }
00127    }

Member Function Documentation

LibraryDYLD& vpr::LibraryDYLD::operator= ( const LibraryDYLD &  lib  )  [inline]

Overlaoded assignment operator.

Definition at line 132 of file LibraryDYLD.h.

References copy().

00133    {
00134       copy(lib);
00135       return *this;
00136    }

const std::string& vpr::LibraryDYLD::getName (  )  const [inline]

Retrieves the name of the library associated with this object.

Definition at line 141 of file LibraryDYLD.h.

00142    {
00143       return mName;
00144    }

vpr::ReturnStatus vpr::LibraryDYLD::load (  ) 

Loads the library named by this object.

This function loads and returns a reference to the specified library. The returned reference becomes the library's identity. The function suppresses duplicate loading if the library is already known by the runtime.

Definition at line 159 of file LibraryDYLD.cpp.

References clrOutNORM, clrYELLOW, vpr::ReturnStatus::Fail, internalDlerror(), internalDlopen(), RTLD_GLOBAL, RTLD_NOW, vpr::ReturnStatus::setCode(), vprDBG_ALL(), vprDBG_WARNING_LVL, vprDEBUG, vprDEBUG_CONT, vprDEBUG_FLUSH, and vprDEBUG_NEXT.

Referenced by findSymbol().

00160 {
00161    vpr::ReturnStatus status;
00162 
00163    if ( std::string("") != mName )
00164    {
00165       mLibrary = internalDlopen(mName.c_str(), RTLD_NOW | RTLD_GLOBAL);
00166    }
00167    else
00168    {
00169       mLibrary = internalDlopen(NULL, RTLD_NOW | RTLD_GLOBAL);
00170    }
00171 
00172    if ( NULL == mLibrary )
00173    {
00174       vprDEBUG_CONT(vprDBG_ALL, vprDBG_WARNING_LVL)
00175          << std::endl << vprDEBUG_FLUSH;
00176       vprDEBUG(vprDBG_ALL, vprDBG_WARNING_LVL)
00177          << clrOutNORM(clrYELLOW, "WARNING:") << " Could not load '" << mName
00178          << "'\n" << vprDEBUG_FLUSH;
00179       vprDEBUG_NEXT(vprDBG_ALL, vprDBG_WARNING_LVL)
00180          << internalDlerror() << std::endl << vprDEBUG_FLUSH;
00181       status.setCode(vpr::ReturnStatus::Fail);
00182    }
00183 
00184    return status;
00185 }

vpr::ReturnStatus vpr::LibraryDYLD::unload (  ) 

This function undoes the effect of the load() method.

After calling this method, future references to the library using its identity will be invalid.

Precondition:
A library has previously been loaded with load().
Postcondition:
The library is unloaded.

Definition at line 187 of file LibraryDYLD.cpp.

References vpr::ReturnStatus::Fail, internalDlclose(), vpr::ReturnStatus::setCode(), and vprASSERT.

Referenced by ~LibraryDYLD().

00188 {
00189    vprASSERT(mLibrary != NULL && "No library to unload");
00190    vpr::ReturnStatus status;
00191 
00192    if ( internalDlclose(mLibrary) != 0 )
00193    {
00194       status.setCode(vpr::ReturnStatus::Fail);
00195    }
00196    else
00197    {
00198       mLibrary = NULL;
00199    }
00200 
00201    return status;
00202 }

bool vpr::LibraryDYLD::isLoaded (  )  const [inline]

Returns whether this library has been loaded from local storage.

Returns:
true is returned if this library has been loaded from local storage, false otherwise.

Definition at line 171 of file LibraryDYLD.h.

00172    {
00173       return mLibrary != NULL;
00174    }

void* vpr::LibraryDYLD::findSymbol ( const char *  symbolName  )  [inline]

Finds and returns an untyped reference to the specified symbol in this library.

If no library was loaded previously, all libraries known to the runtime and the main program are searched in an unspecified order.

Use this function to look up functions or data symbols in a shared library. Getting a pointer to a symbol in a library does indicate that the library is available when the search was made. The runtime does nothing to ensure the continued validity of the symbol. If the library is unloaded, for instance, the results of any findSymbol() calls become invalid as well.

Postcondition:
If the library was not loaded, it is loaded before symbol lookup.
Parameters:
symbolName The text representation of the symbol to resolve.
Returns:
An untyped pointer, possibly NULL.

Definition at line 195 of file LibraryDYLD.h.

References internalDlsym(), load(), and vprASSERT.

Referenced by findSymbol().

00196    {
00197       // If no library has been loaded yet, do it now.  This is done to mimic
00198       // the NSPR behavior.
00199       if ( NULL == mLibrary )
00200       {
00201          load();
00202          vprASSERT(NULL != mLibrary && "Could not load any library");
00203       }
00204 
00205       return internalDlsym(mLibrary, symbolName);
00206    }

void* vpr::LibraryDYLD::findSymbol ( const std::string &  symbolName  )  [inline]

Definition at line 208 of file LibraryDYLD.h.

References findSymbol().

00209    {
00210       return findSymbol(symbolName.c_str());
00211    }

void * vpr::LibraryDYLD::findSymbolAndLibrary ( const char *  symbolName,
LibraryDYLD &  lib 
) [static]

Finds a symbol in one of the currently loaded libraries, and returns both the symbol and the library in which it was found.

Definition at line 204 of file LibraryDYLD.cpp.

References vprASSERT.

Referenced by findSymbolAndLibrary().

00206 {
00207    boost::ignore_unused_variable_warning(symbolName);
00208    boost::ignore_unused_variable_warning(lib);
00209    vprASSERT(false && "Not implemented yet");
00210    return NULL;
00211 }

static void* vpr::LibraryDYLD::findSymbolAndLibrary ( const std::string &  symbolName,
LibraryDYLD &  lib 
) [inline, static]

Definition at line 221 of file LibraryDYLD.h.

References findSymbolAndLibrary().

00223    {
00224       return findSymbolAndLibrary(symbolName.c_str(), lib);
00225    }

void vpr::LibraryDYLD::copy ( const LibraryDYLD &  lib  )  [inline, protected]

Makes a copy of the given vpr::LibraryDYLD into this object.

Definition at line 232 of file LibraryDYLD.h.

References mLibrary, and mName.

Referenced by LibraryDYLD(), and operator=().

00233    {
00234       this->mName    = lib.mName;
00235       this->mLibrary = lib.mLibrary;
00236    }

void * vpr::LibraryDYLD::internalDlopen ( const char *  filename,
int  flag 
) [protected]

Definition at line 214 of file LibraryDYLD.cpp.

References error(), RTLD_GLOBAL, and RTLD_LAZY.

Referenced by load().

00215 {
00216    void *module = 0;
00217    NSObjectFileImage ofi = 0;
00218    NSObjectFileImageReturnCode ofirc;
00219    static int (*make_private_module_public) (NSModule module) = 0;
00220    unsigned int flags =  NSLINKMODULE_OPTION_RETURN_ON_ERROR | NSLINKMODULE_OPTION_PRIVATE;
00221 
00222    /* If we got no path, the app wants the global namespace, use -1 as the marker
00223       in this case */
00224    if (!path)
00225       return (void *)-1;
00226 
00227    /* Create the object file image, works for things linked with the -bundle arg to ld */
00228    ofirc = NSCreateObjectFileImageFromFile(path, &ofi);
00229    switch (ofirc)
00230    {
00231       case NSObjectFileImageSuccess:
00232          /* It was okay, so use NSLinkModule to link in the image */
00233          if (!(mode & RTLD_LAZY)) flags += NSLINKMODULE_OPTION_BINDNOW;
00234          module = NSLinkModule(ofi, path,flags);
00235          /* Don't forget to destroy the object file image, unless you like leaks */
00236          NSDestroyObjectFileImage(ofi);
00237          /* If the mode was global, then change the module, this avoids
00238             multiply defined symbol errors to first load private then make
00239             global. Silly, isn't it. */
00240          if ((mode & RTLD_GLOBAL))
00241          {
00242            if (!make_private_module_public)
00243            {
00244              _dyld_func_lookup("__dyld_NSMakePrivateModulePublic", 
00245             (unsigned long *)&make_private_module_public);
00246            }
00247            make_private_module_public(module);
00248          }
00249          break;
00250       case NSObjectFileImageInappropriateFile:
00251          /* It may have been a dynamic library rather than a bundle, try to load it */
00252          module = (void *)NSAddImage(path, NSADDIMAGE_OPTION_RETURN_ON_ERROR);
00253          break;
00254       case NSObjectFileImageFailure:
00255          error(0,"Object file setup failure :  \"%s\"", path);
00256          return 0;
00257       case NSObjectFileImageArch:
00258          error(0,"No object for this architecture :  \"%s\"", path);
00259          return 0;
00260       case NSObjectFileImageFormat:
00261          error(0,"Bad object file format :  \"%s\"", path);
00262          return 0;
00263       case NSObjectFileImageAccess:
00264          error(0,"Can't read object file :  \"%s\"", path);
00265          return 0;      
00266    }
00267    if (!module)
00268       error(0, "Can not open \"%s\"", path);
00269    return module;
00270 }

const char * vpr::LibraryDYLD::internalDlerror (  )  [protected]

Definition at line 273 of file LibraryDYLD.cpp.

References error().

Referenced by load().

00274 {
00275    return error(1, (char *)NULL);
00276 }

void* vpr::LibraryDYLD::internalDlsym ( void *dl_restrict  handle,
const char *dl_restrict  symbol 
) [protected]

Referenced by findSymbol().

int vpr::LibraryDYLD::internalDlclose ( void *  handle  )  [protected]

Definition at line 279 of file LibraryDYLD.cpp.

References error().

Referenced by unload().

00280 {
00281    if ((((struct mach_header *)handle)->magic == MH_MAGIC) ||
00282       (((struct mach_header *)handle)->magic == MH_CIGAM))
00283    {
00284       error(-1, "Can't remove dynamic libraries on darwin");
00285       return 0;
00286    }
00287    if (!NSUnLinkModule(handle, 0))
00288    {
00289       error(0, "unable to unlink module %s", NSNameOfModule(handle));
00290       return 1;
00291    }
00292    return 0;
00293 }

The documentation for this class was generated from the following files:
Generated on Thu Jan 4 10:55:23 2007 for VR Juggler Portable Runtime by  doxygen 1.5.1