LLVM API Documentation

DynamicLibrary.h

Go to the documentation of this file.
00001 //===-- llvm/System/DynamicLibrary.h - Portable Dynamic Library -*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file is distributed under the University of Illinois Open Source
00006 // License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 // This file declares the sys::DynamicLibrary class.
00011 //
00012 //===----------------------------------------------------------------------===//
00013 
00014 #ifndef LLVM_SYSTEM_DYNAMIC_LIBRARY_H
00015 #define LLVM_SYSTEM_DYNAMIC_LIBRARY_H
00016 
00017 #include <string>
00018 
00019 namespace llvm {
00020 namespace sys {
00021 
00022   /// This class provides a portable interface to dynamic libraries which also
00023   /// might be known as shared libraries, shared objects, dynamic shared
00024   /// objects, or dynamic link libraries. Regardless of the terminology or the
00025   /// operating system interface, this class provides a portable interface that
00026   /// allows dynamic libraries to be loaded and and searched for externally
00027   /// defined symbols. This is typically used to provide "plug-in" support.
00028   /// It also allows for symbols to be defined which don't live in any library,
00029   /// but rather the main program itself, useful on Windows where the main
00030   /// executable cannot be searched.
00031   class DynamicLibrary {
00032     DynamicLibrary(); // DO NOT IMPLEMENT
00033   public:
00034     /// This function allows a library to be loaded without instantiating a
00035     /// DynamicLibrary object. Consequently, it is marked as being permanent
00036     /// and will only be unloaded when the program terminates.  This returns
00037     /// false on success or returns true and fills in *ErrMsg on failure.
00038     /// @brief Open a dynamic library permanently.
00039     ///
00040     /// NOTE: This function is not thread safe.
00041     ///
00042     static bool LoadLibraryPermanently(const char *filename,
00043                                        std::string *ErrMsg = 0);
00044 
00045     /// This function will search through all previously loaded dynamic
00046     /// libraries for the symbol \p symbolName. If it is found, the addressof
00047     /// that symbol is returned. If not, null is returned. Note that this will
00048     /// search permanently loaded libraries (LoadLibraryPermanently) as well
00049     /// as ephemerally loaded libraries (constructors).
00050     /// @throws std::string on error.
00051     /// @brief Search through libraries for address of a symbol
00052     ///
00053     /// NOTE: This function is not thread safe.
00054     ///
00055     static void *SearchForAddressOfSymbol(const char *symbolName);
00056 
00057     /// @brief Convenience function for C++ophiles.
00058     ///
00059     /// NOTE: This function is not thread safe.
00060     ///
00061     static void *SearchForAddressOfSymbol(const std::string &symbolName) {
00062       return SearchForAddressOfSymbol(symbolName.c_str());
00063     }
00064 
00065     /// This functions permanently adds the symbol \p symbolName with the
00066     /// value \p symbolValue.  These symbols are searched before any
00067     /// libraries.
00068     /// @brief Add searchable symbol/value pair.
00069     ///
00070     /// NOTE: This function is not thread safe.
00071     ///
00072     static void AddSymbol(const char *symbolName, void *symbolValue);
00073 
00074     /// @brief Convenience function for C++ophiles.
00075     ///
00076     /// NOTE: This function is not thread safe.
00077     ///
00078     static void AddSymbol(const std::string &symbolName, void *symbolValue) {
00079       AddSymbol(symbolName.c_str(), symbolValue);
00080     }
00081   };
00082 
00083 } // End sys namespace
00084 } // End llvm namespace
00085 
00086 #endif // LLVM_SYSTEM_DYNAMIC_LIBRARY_H