Athena::SharedLibrary Class Reference

Shared library services. More...

#include <SealSharedLib.h>

Collaboration diagram for Athena::SharedLibrary:

Classes
struct	LibraryInfo
	Information about a currently loaded shared library. More...

Public Types
typedef void *	Data
typedef void(*	Function) (void)
typedef Callback1< const LibraryInfo & >	InfoHandler

Public Member Functions
void	release (void)
	Release a shared library.
void	abandon (void)
	Abandon a library.
Data	data (const std::string &name, bool mangle=true) const
	Locate and return a reference to a data symbol called name.
Function	function (const std::string &name, bool mangle=true) const
	Locate and return a reference to a function symbol called name.

Static Public Member Functions
static std::string	path (void)
static void path	ATLAS_NOT_THREAD_SAFE (const std::string &path)
static std::string	libname (const std::string &name)
	Return a shared library name that follows the system conventions for naming shared library.
static std::string	symname (const std::string &name)
	Transform 'extern "C"' symbol name into a name suitable for lookup in a shared library, e.g.
static SharedLibrary *	self (void)
	Return a shared library object representing the application itself.
static SharedLibrary *	load (const std::string &name)
	Load a shared library and return an object representing it.
static void	loaded (InfoHandler &handler)
	Iterate and provide information about all currently loaded shared libraries.

Protected Member Functions
	SharedLibrary (void *handle)
	Protected constructor for initialising a library object.
	~SharedLibrary (void)
	Protected destructor for cleaning up a library object.

Private Member Functions
	SharedLibrary (const SharedLibrary &)
SharedLibrary &	operator= (const SharedLibrary &)

Private Attributes
void *	m_handle

Detailed Description

Shared library services.

Definition at line 157 of file SealSharedLib.h.

Member Typedef Documentation

Data

typedef void* Athena::SharedLibrary::Data

Definition at line 160 of file SealSharedLib.h.

Function

typedef void(* Athena::SharedLibrary::Function) (void)

Definition at line 161 of file SealSharedLib.h.

InfoHandler

typedef Callback1<const LibraryInfo &> Athena::SharedLibrary::InfoHandler

Definition at line 175 of file SealSharedLib.h.

Constructor & Destructor Documentation

SharedLibrary() [1/2]

Athena::SharedLibrary::SharedLibrary ( void * handle )

protected

Protected constructor for initialising a library object.

The real initialisation happens in load() or self().

Definition at line 587 of file SealSharedLib.cxx.

    : m_handle (handle)
{ assert (m_handle); }

~SharedLibrary()

Athena::SharedLibrary::~SharedLibrary ( void )

protected

Protected destructor for cleaning up a library object.

The real destruction happens in release() or #abadon().

Definition at line 593 of file SealSharedLib.cxx.

{ assert (! m_handle); }

SharedLibrary() [2/2]

Athena::SharedLibrary::SharedLibrary ( const SharedLibrary & )

private

Member Function Documentation

abandon()

void Athena::SharedLibrary::abandon

(

void

)

Abandon a library.

This simply destroys the shared library object (this) without releasing the underlying dynamic object.

Definition at line 625 of file SealSharedLib.cxx.

{
    assert (m_handle);
    m_handle = 0;
    delete this;
}

ATLAS_NOT_THREAD_SAFE()

void path Athena::SharedLibrary::ATLAS_NOT_THREAD_SAFE ( const std::string & path )

static

data()

SharedLibrary::Data Athena::SharedLibrary::data	(	const std::string &	name,
		bool	mangle = true ) const

Locate and return a reference to a data symbol called name.

If no such symbol exists, returns a null pointer. If mangle is the default true, the symbol is mangled to the platform convention, typically prepending an underscore if required. The mangling does not refer to C++ name mangling, but to the mangling required to convert C identifiers to run-time symbol names; see symname() for details.

Definition at line 640 of file SealSharedLib.cxx.

{
    assert (! name.empty ());
    assert (m_handle);
    std::string mangled = mangle ? symname (name) : name;
    Data    symbol = 0;
 
#if HAVE_DLOPEN || HAVE_LOAD
    // See comments in "self()" about crashes in dlerror().
    const char *error = 0;
    symbol = ::dlsym (m_handle, mangled.c_str ());
    if (! symbol && (error = ::dlerror ()) != 0)
    throw SharedLibraryError ("dlsym()", error);
 
#elif HAVE_SHL_LOAD
    shl_t handle = (shl_t) m_handle;
    if (::shl_findsym (&handle, mangled.c_str (), TYPE_DATA, &symbol) != 0)
    throw SharedLibraryError ("shl_findsym()", errno);
    assert (handle == (shl_t) m_handle);
 
#elif defined _WIN32
    if (! (symbol = (Data)::GetProcAddress((HINSTANCE)m_handle, mangled.c_str())))
    throw SharedLibraryError ("GetProcAddress()", GetLastError ());
#else
    // cannot get here---`load' and `self' should take care of it.
    assert (false);
#endif
    return symbol;
}

function()

SharedLibrary::Function Athena::SharedLibrary::function	(	const std::string &	name,
		bool	mangle = true ) const

Locate and return a reference to a function symbol called name.

If no such symbol exists, returns a null pointer. If mangle is the default true, the symbol is mangled to the platform convention, typically prepending an underscore if required. The mangling does not refer to C++ name mangling, but to the mangling required to convert C identifiers to run-time symbol names; see symname() for details.

Definition at line 678 of file SealSharedLib.cxx.

{
    assert (! name.empty ());
    assert (m_handle);
    std::string mangled = mangle ? symname (name) : name;
    Function    symbol = 0;
 
#if HAVE_DLOPEN || HAVE_LOAD
    // See comments in "self()" about crashes in dlerror().
    const char *error = 0;
    union { Function func; Data data; } sym;
    sym.data = ::dlsym (m_handle, mangled.c_str ());
    if (! sym.data && (error = ::dlerror ()) != 0)
    throw SharedLibraryError ("dlsym()", error);
    symbol = sym.func;
 
#elif HAVE_SHL_LOAD
    shl_t handle = (shl_t) m_handle;
    if (::shl_findsym (&handle, mangled.c_str (), TYPE_PROCEDURE, &symbol) != 0)
    throw SharedLibraryError ("shl_findsym()", errno);
    assert (handle == (shl_t) m_handle);
 
#elif defined _WIN32
    if (! (symbol = (Function) ::GetProcAddress ((HINSTANCE) m_handle,
                         mangled.c_str ())))
    throw SharedLibraryError ("GetProcAddress()", GetLastError ());
#else
    // cannot get here---`load' and `self' should take care of it.
    assert (false);
#endif
    return symbol;
}

libname()

std::string Athena::SharedLibrary::libname ( const std::string & name )

static

Return a shared library name that follows the system conventions for naming shared library.

name is the basic name of the shared library, without the name prefix ("lib" on unix) or the extension (".so", ".sl", ".dylib" or ".dll"). name must not have any directory components.

Definition at line 178 of file SealSharedLib.cxx.

{
#ifdef _WIN32
    return name + ".dll";
#elif defined __hpux
    return "lib" + name + ".sl";
#else
    return "lib" + name + ".so";
#endif
}

load()

SharedLibrary * Athena::SharedLibrary::load ( const std::string & name )

static

Load a shared library and return an object representing it.

The returned object is allocated with new. The caller must release the object with either release() or abandon(). The method throws a SharedLibraryError if the operation is not supported or some failure occurs. Please note that on several systems failure to properly load a library, e.g. due to missing symbols, is effectively fatal.

Definition at line 241 of file SealSharedLib.cxx.

{
    assert(! name.empty ());
 
    void *handle = 0;
 
#if HAVE_DLOPEN || HAVE_LOAD
# ifndef RTLD_GLOBAL
#  define RTLD_GLOBAL 0
# endif
    // See comments in "self()" about crashes in dlerror().
    if (! (handle = ::dlopen (name.c_str (), RTLD_LAZY | RTLD_GLOBAL)))
    {
    const char *msg = ::dlerror ();
    msg = msg ? msg : "dynamic linker error message lost!";
    throw SharedLibraryError ("dlopen()", msg);
    }
 
#elif HAVE_SHL_LOAD
    if (! (handle = ::shl_load (name.c_str (), BIND_DEFERRED, 0L)))
    throw SharedLibraryError ("shl_load()", errno);
 
#elif defined _WIN32
    if (! (handle = ::LoadLibrary (name.c_str ())))
    throw SharedLibraryError ("LoadLibrary()", GetLastError ());
#else
    SHLIB_UNSUPPORTED;
#endif
 
    return new SharedLibrary (handle);
}

loaded()

void Athena::SharedLibrary::loaded ( InfoHandler & handler )

static

Iterate and provide information about all currently loaded shared libraries.

Definition at line 276 of file SealSharedLib.cxx.

{
    // Dynamic linker characteristics:
    //   AIX, Windows, SVR4 (DG/UX, DRS/NX, DYNIX/ptx, Linux, SINIX,
    //   Solaris, UnixWare, {Free,Open,Net}BSD if __ELF__), BSD,
    //   HP-UX, IRIX, Tru64
 
    // Object file formats:
    //   XCOFF (AIX), ELF32/64 (DG/UX, DRS/NX, DYNIX/ptx, IRIX, SINIX,
    //   Solaris, UnixWare, {Free,Open,Net}BSD: if __ELF__), a.out
    //   ({Free,Open,Net}BSD if ! __ELF__, SunOS), BFD (Cygwin, HP-UX,
    //   Linux, LynxOS, Tru64, Windows if GCC), PE (Windows), COFF (?)
 
#if HAVE_SHL_LOAD                   // hp-ux
    shl_descriptor desc;
 
    for (int index = -1; shl_get_r (index, &desc) == 0; ++index)
    {
    LibraryInfo info;
    info.m_filename   = desc.filename;
    info.m_text_start = desc.tstart;
    info.m_text_end   = desc.tend;
    info.m_data_start = desc.dstart;
    info.m_data_end   = desc.dend;
    info.m_bss_start  = 0;
    info.m_bss_end    = 0;
 
    handler (info);
    }
 
#elif HAVE_LINK_H                   // bsd/svr4/elf
# if !HAVE_LINK_MAP_L_MAP_START
#  define l_map_start l_addr
#  define l_map_end   l_addr
# endif
# if !HAVE_PROGRAM_INVOCATION_NAME
    static const char *program_invocation_name = "(unknown program name)";
# endif
# if HAVE_R_DEBUG                   // linux/glibc
    link_map *p = _r_debug.r_map;
# else
    // Dynamic linker root:
    //   BSD (SunOS):
    //     #include <sys/types.h>
    //     #include <link.h>
    //     extern struct link_dynamic _DYNAMIC;
    //     link_dynamic *d = &_DYNAMIC;
    //     if ((d->ld_version > 1) && (d->ld_version <= 3) && (d->ld_un.ld_1 != 0))
    //       --> link_map *l = d->ld_un.ld_1->ld_loaded
    //          l->lm_name, l->lm_addr, l->lm_next
    //
    //   BSD ({Free,Open,Net}BSD):
    //     #include <sys/types.h>
    //     #include <link.h>
    //     extern struct _dynamic _DYNAMIC
    //     _dynamic *d = &_DYNAMIC;
    //     if ((d->version == LD_VERSION_BSD) && d->d_un.d_sdt != 0))
    //       --> so_map *l = d->d_un.d_sdt->sdt_loaded
    //           l->som_path, l->som_addr, l->som_next
    //
    //   SVR4 (DG/UX, DRS/NX, DYNIX/ptx, SINIX, UnixWare)
    //     ElfW(Dyn) _DYNAMIC[]  // Linux
    //     void _DYNAMIC (void)  // weak, really is data, but not
    //                           // all compilers allow weak data
    //
    //   Solaris:
    //     dlinfo (self, RTLD_DI_LINKMAP, &p);
 
 //    extern ElfW(Dyn) _DYNAMIC []; // #pragma weak?  // wlav
    link_map *p = 0;
    for (ElfW(Dyn) *dyn = _DYNAMIC; dyn->d_tag != DT_NULL; ++dyn)
    if (dyn->d_tag == DT_DEBUG && dyn->d_un.d_ptr)
        // linux: p = ((r_debug *) dyn->d_un_d.ptr)->r_map;
        p = (link_map *) *((unsigned long *) dyn->d_un.d_ptr + 1);
# endif
 
    if (! p)
       throw SharedLibraryError ("loaded", "no shared library load map");
 
    // Get executable name; linux has a symlink in /proc/self/exe.
    // Linux path names are arbitrarily long, so we just have create
    // some random-sized buffer.  We allocate this on stack to avoid
    // dynamic memory allocation.  If this is a problem, report a bug.
    struct stat sbuf;
    char    exe [4096];
 
    memset (exe, 0, sizeof (exe));
    if (::stat ("/proc/self/exe", &sbuf) == 0)
    ::readlink ("/proc/self/exe", exe, sizeof (exe)-1);
    else
       STDC::strncpy (exe, program_invocation_name, sizeof (exe)-1);
 
    // Get shared libraries
    for ( ; p; p = p->l_next)
    {
    LibraryInfo info;
 
    /* FIXME: Does this work with prelinked shared libraries?
       From a mail to GCC mailing list ("fde-glibc.c bug"):
 
         There is a bug in gcc/config/ia64/fde-glibc.c:
         ret = find_fde_for_dso ((Elf64_Addr)pc, (Elf64_Ehdr *)map->l_addr,
                                       ^^^^^^^^^^^
                     segment_base, gp);
 
         this will work only as long as the shared library in
         question has first PT_LOAD segment's p_vaddr == 0.
         E.g. with ELF prelinking this is almost never true
         though, so what you really want is map->l_map_start
         (map->l_addr will be almost always 0) or even better
         map->l_phdr/map->l_phnum pair.  */
 
    // FIXME: use the map address (= ElfW(Ehdr)) to scan over
    // the different ElfW(Phdr)s to find the various sections.
    info.m_filename   = (p->l_name && p->l_name[0] ? p->l_name : exe);
    info.m_text_start = p->l_addr ? p->l_addr : p->l_map_start;
    info.m_text_end   = p->l_addr ? p->l_addr : p->l_map_end;
    info.m_data_start = 0;
    info.m_data_end   = 0;
    info.m_bss_start  = 0;
    info.m_bss_end    = 0;
 
    handler (info);
    }
 
#elif HAVE_SGIDEFS_H                    // irix
    /* From rld(1) man page:
 
       rld keeps a doubly linked list of structures and crt1.o
       contains a pointer to the head of the list of obj structures
       called __rld_obj_head. In an o32 executable, this points to a
       linked list of objList structures (/usr/include/obj_list.h),
       each of which has a `data' element which is a pointer to a
       `struct obj' (/usr/include/obj.h) (even though the field is not
       declared as a pointer). In an n32 executable, __rld_obj_head
       points to a linked list of Elf32_Obj_Info structures
       (/usr/include/objlist.h).  In a 64-bit executable,
       __rld_obj_head points to a linked list of Elf64_Obj_Info
       structures (/usr/include/objlist.h).  The `oi_magic' element of
       each Elf32_Obj_Info or Elf64_Obj_Info is all-bits-on
       (0xffffffff) to make it easier to determine which list type is
       in use a 32-bit executable.  */
 
    // To get more details by reading the ELF files:
    // http://reality.sgi.com/davea/software.html
    extern ElfW(Obj_Info)   *__rld_obj_head;
    ElfW(Obj_Info)      *p = __rld_obj_head;
 
    for ( ; p; p = (ElfW(Obj_Info) *) p->oi_next)
    {
    LibraryInfo info;
 
# if defined _MIPS_SIM_ABI32 && _MIPS_SIM == _MIPS_SIM_ABI32
    info.m_filename   = (const char *) p->o_path;
    info.m_text_start = p->o_praw;  // base address: o_base_address
    info.m_text_end   = p->o_praw;
# elif (defined _MIPS_SIM_NABI32 && _MIPS_SIM == _MIPS_SIM_NABI32) \
    || (defined _MIPS_SIM_ABI64  && _MIPS_SIM == _MIPS_SIM_ABI64)
    info.m_filename   = (const char *) p->oi_pathname;
    info.m_text_start = p->oi_ehdr; // base address: oi_orig_ehdr
    info.m_text_end   = p->oi_ehdr;
# else
#  error "Unsupported ABI: not o32, n32 or 64"
# endif
    info.m_data_start = 0;
    info.m_data_end   = 0;
    info.m_bss_start  = 0;
    info.m_bss_end    = 0;
 
    handler (info);
    }
 
#elif HAVE_LOADER_H && HAVE_LDR_NEXT_MODULE_DECL    // tru64
    ldr_process_t   proc = ldr_my_process ();
    ldr_module_t    mod  = LDR_NULL_MODULE;
    int         ret  = ldr_next_module (proc, &mod);
 
    for (; ret == 0 && mod != LDR_NULL_MODULE; ret = ldr_next_module (proc, &mod))
    {
    ldr_module_info_t   info;
    size_t          size = 0;
    LibraryInfo      libinfo;
 
    if (ldr_inq_module(proc, mod, &info, sizeof(info), &size) < 0)
        throw SharedLibraryError ("ldr_inq_module()", errno);
 
    libinfo.m_filename   = info.lmi_name;
    libinfo.m_text_start = 0;
    libinfo.m_text_end   = 0;
    libinfo.m_data_start = 0;
    libinfo.m_data_end   = 0;
    libinfo.m_bss_start  = 0;
    libinfo.m_bss_end    = 0;
 
    for (int i = 0; i < info.lmi_nregion; ++i)
    {
        ldr_region_info_t   rinfo;
        unsigned long   low;
        unsigned long   high;
 
        if (ldr_inq_region(proc, mod, i, &rinfo, sizeof(rinfo), &size) < 0)
            throw SharedLibraryError ("ldr_inq_region()", errno);
 
        low  = (unsigned long) rinfo.lri_mapaddr;
        high = ((unsigned long) rinfo.lri_mapaddr) + rinfo.lri_size;
 
        if (!strcmp(rinfo.lri_name, ".text")) {
        libinfo.m_text_start = low;
        libinfo.m_text_end   = high;
        } else if (!strcmp(rinfo.lri_name, ".data")) {
        libinfo.m_data_start = low;
        libinfo.m_data_end   = high;
        } else if (!strcmp(rinfo.lri_name, ".bss")) {
        libinfo.m_bss_start  = low;
        libinfo.m_bss_end    = high;
        }
    }
 
    handler (libinfo);
    }
 
    if (ret < 0)
    throw SharedLibraryError ("ldr_next_module()", errno);
 
#elif HAVE_LOAD && HAVE_LOAD_DECL           // aix
    int     size = 16;
    void    *buffer = new ld_info [size];
    int     error = ::loadquery (L_GETINFO, buffer, size);
    int     offset = 0;
 
    while (error == -1 && errno == ENOMEM)
    {
    delete [] (ld_info *) buffer;
    buffer = new ld_info [size *= 2];
    error = ::loadquery (L_GETINFO, buffer, size);
    }
 
    if (error == -1)
    throw SharedLibraryError ("loadquery()", errno);
 
    while (true)
    {
    LibraryInfo  info;
    ld_info     *ld = (ld_info *) ((char *) buffer + offset);
    const char  *path = ld->ldinfo_filename;
    const char  *member = path + strlen (path) + 1;
    std::string filename;   // FIXME: Use alloca instead?
 
    filename = path;
    if (*member)
    {
        filename += '(';
        filename += member;
        filename += ')';
    }
 
    info.m_filename   = filename.c_str ();
    info.m_text_start = (unsigned long) ld->ldinfo_textorg;
    info.m_text_end   = info.m_text_start + ld->ldinfo_textsize;
    info.m_data_start = (unsigned long) ld->ldinfo_dataorg;
    info.m_data_end   = info.m_data_start + ld->ldinfo_datasize;
    info.m_bss_start  = 0;
    info.m_bss_end    = 0;
 
    handler (info);
 
    if (ld->ldinfo_next)
        offset += ld->ldinfo_next;
    else
        break;
    }
 
    delete [] (ld_info *) buffer;
 
#elif HAVE_MACH_O_DYLD_H                // darwin
    unsigned long images = _dyld_image_count ();
    for (unsigned long i = 0; i < images; ++i)
    {
    const mach_header *hdr = _dyld_get_image_header (i);
    unsigned long    slide = _dyld_get_image_vmaddr_slide (i);
    unsigned int    size;
    char        *sect;
    LibraryInfo  info;
 
    info.m_filename   = _dyld_get_image_name (i);
 
    sect = getsectdatafromheader (hdr, SEG_TEXT, SECT_TEXT, &size);
    info.m_text_start = sect ? (unsigned long) sect + slide : 0;
    info.m_text_end   = sect ? (unsigned long) sect + slide + size : 0;
    sect = getsectdatafromheader (hdr, SEG_DATA, SECT_DATA, &size);
    info.m_data_start = sect ? (unsigned long) sect + slide : 0;
    info.m_data_end   = sect ? (unsigned long) sect + slide + size : 0;
    sect = getsectdatafromheader (hdr, SEG_DATA, SECT_BSS, &size);
    info.m_bss_start  = sect ? (unsigned long) sect + slide : 0;
    info.m_bss_end    = sect ? (unsigned long) sect + slide + size : 0;
 
    handler (info);
    }
 
#elif defined _WIN32                    // windows
    if (! SymInitialize (GetCurrentProcess (), NULL, TRUE)
    || ! SymEnumerateModules (GetCurrentProcess (), &enumModules, (void *) &handler)
    || ! SymCleanup (GetCurrentProcess ()))
    throw SharedLibraryError ("SymEnumerateModules()", GetLastError());
#else
    SHLIB_UNSUPPORTED;
#endif
}

operator=()

SharedLibrary & Athena::SharedLibrary::operator= ( const SharedLibrary & )

private

path()

std::string Athena::SharedLibrary::path ( void )

static

Definition at line 148 of file SealSharedLib.cxx.

{
    const char *pathvar = PATH;
    const char *path = pathvar ? getenv (pathvar) : 0;
    return path ? path : "";
}

release()

void Athena::SharedLibrary::release

(

void

)

Release a shared library.

This unloads any library the object currently refers to, then deletes this. Note that releasing the library does not guarantee that it will actually be unloaded. If there are outstanding references to the library, explicit or implicit, the library will remain in memory.

Definition at line 602 of file SealSharedLib.cxx.

{
    assert (m_handle);
 
#if HAVE_DLOPEN || HAVE_LOAD
    ::dlclose (m_handle);
#elif HAVE_SHL_LOAD
    ::shl_unload ((shl_t) m_handle);
#elif defined _WIN32
    ::FreeLibrary ((HINSTANCE) m_handle);
#else
    // cannot get here---`load' and `self' should take care of it.
    assert (false);
#endif
 
    m_handle = 0;
    delete this;
}

self()

SharedLibrary * Athena::SharedLibrary::self ( void )

static

Return a shared library object representing the application itself.

The returned object is allocated with new. The caller must release the object with either release() or abandon(). The method throws a SharedLibraryError if the operation is not supported or some failure occurs.

Definition at line 206 of file SealSharedLib.cxx.

{
#if HAVE_DLOPEN || HAVE_LOAD
    // NB: Linux (at least RH 7.x) dynamic loader is severely broken
    // when it comes to reporting error messages.  The error messages
    // are frequently garbled or null.  If you see a crash in a call
    // to dlerror(), sorry, there's nothing we can do about that.
    // Our attempts have only produced even more undesirable crashes.
    // Waiting for a better version of the linux dynamic loader.
    void *handle = ::dlopen (0, RTLD_LAZY);
    if (! handle)
    {
    const char *msg = ::dlerror ();
    msg = msg ? msg : "dynamic linker error message lost!";
    throw SharedLibraryError ("dlopen()", msg);
    }
 
    return new SharedLibrary (handle);
#elif HAVE_SHL_LOAD
    return new SharedLibrary (PROG_HANDLE);
#elif defined _WIN32
    return new SharedLibrary (::GetModuleHandle (0));
#else
    SHLIB_UNSUPPORTED;
#endif
}

symname()

std::string Athena::SharedLibrary::symname ( const std::string & name )

static

Transform 'extern "C"' symbol name into a name suitable for lookup in a shared library, e.g.

with data() or function(). Normally the latter two automatically perform the necessary mangling by calling this function, but the clients can also do the mangling themselves. The name should be in the form it is spelled in C source code.

Definition at line 196 of file SealSharedLib.cxx.

{ return name; }

Member Data Documentation

m_handle

void* Athena::SharedLibrary::m_handle

private

Definition at line 197 of file SealSharedLib.h.

---

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

• SealSharedLib.h
• SealSharedLib.cxx