153ca1f3190680f3e86aebe0f72f7918d63f71e0dCharles Davis//===-- llvm/Support/DynamicLibrary.h - Portable Dynamic Library -*- C++ -*-===// 263b3afa98460ce38a1c48d3c44ef6edfdaf37b77Misha Brukman// 30de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer// The LLVM Compiler Infrastructure 40de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer// 57ed47a13356daed2a34cd2209a31f92552e3bdd8Chris Lattner// This file is distributed under the University of Illinois Open Source 67ed47a13356daed2a34cd2209a31f92552e3bdd8Chris Lattner// License. See LICENSE.TXT for details. 763b3afa98460ce38a1c48d3c44ef6edfdaf37b77Misha Brukman// 80de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer//===----------------------------------------------------------------------===// 90de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer// 100de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer// This file declares the sys::DynamicLibrary class. 110de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer// 120de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer//===----------------------------------------------------------------------===// 130de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer 140de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer#ifndef LLVM_SYSTEM_DYNAMIC_LIBRARY_H 150de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer#define LLVM_SYSTEM_DYNAMIC_LIBRARY_H 160de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer 170de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer#include <string> 180de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer 190de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencernamespace llvm { 20c667fadfbc2b70fd5d8e733fe2287c5704839b7aEli Friedman 21c667fadfbc2b70fd5d8e733fe2287c5704839b7aEli Friedmanclass StringRef; 22c667fadfbc2b70fd5d8e733fe2287c5704839b7aEli Friedman 230de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencernamespace sys { 240de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer 250de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer /// This class provides a portable interface to dynamic libraries which also 2663b3afa98460ce38a1c48d3c44ef6edfdaf37b77Misha Brukman /// might be known as shared libraries, shared objects, dynamic shared 270de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer /// objects, or dynamic link libraries. Regardless of the terminology or the 280de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer /// operating system interface, this class provides a portable interface that 29f451cb870efcf9e0302d25ed05f4cac6bb494e42Dan Gohman /// allows dynamic libraries to be loaded and searched for externally 300de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer /// defined symbols. This is typically used to provide "plug-in" support. 3185046901b8ab3c447889338f03a1fd2805198ad7Jeff Cohen /// It also allows for symbols to be defined which don't live in any library, 3285046901b8ab3c447889338f03a1fd2805198ad7Jeff Cohen /// but rather the main program itself, useful on Windows where the main 3385046901b8ab3c447889338f03a1fd2805198ad7Jeff Cohen /// executable cannot be searched. 340bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// 350bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Note: there is currently no interface for temporarily loading a library, 360bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// or for unloading libraries when the LLVM library is unloaded. 370de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer class DynamicLibrary { 3877b6f2fd22bd9e0b8c0f1a4b0b007971e7b84d35Jordy Rose // Placeholder whose address represents an invalid library. 3977b6f2fd22bd9e0b8c0f1a4b0b007971e7b84d35Jordy Rose // We use this instead of NULL or a pointer-int pair because the OS library 4077b6f2fd22bd9e0b8c0f1a4b0b007971e7b84d35Jordy Rose // might define 0 or 1 to be "special" handles, such as "search all". 41c68c8623d01140af0f165888a1bfd3d6d937aee8Jordy Rose static char Invalid; 4277b6f2fd22bd9e0b8c0f1a4b0b007971e7b84d35Jordy Rose 430bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose // Opaque data used to interface with OS-specific dynamic library handling. 440bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose void *Data; 450bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose 4677b6f2fd22bd9e0b8c0f1a4b0b007971e7b84d35Jordy Rose explicit DynamicLibrary(void *data = &Invalid) : Data(data) {} 4772501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner public: 480bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Returns true if the object refers to a valid library. 4977b6f2fd22bd9e0b8c0f1a4b0b007971e7b84d35Jordy Rose bool isValid() { return Data != &Invalid; } 500bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose 510bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Searches through the library for the symbol \p symbolName. If it is 520bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// found, the address of that symbol is returned. If not, NULL is returned. 530bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Note that NULL will also be returned if the library failed to load. 540bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Use isValid() to distinguish these cases if it is important. 550bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Note that this will \e not search symbols explicitly registered by 560bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// AddSymbol(). 570bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose void *getAddressOfSymbol(const char *symbolName); 580bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose 590bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// This function permanently loads the dynamic library at the given path. 600bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// The library will only be unloaded when the program terminates. 610bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// This returns a valid DynamicLibrary instance on success and an invalid 620bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// instance on failure (see isValid()). \p *errMsg will only be modified 630bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// if the library fails to load. 64a9b7d60d67b054541cb8507d697eb94beee32f18Chris Lattner /// 650bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// It is safe to call this function multiple times for the same library. 660bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// @brief Open a dynamic library permanently. 670bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose static DynamicLibrary getPermanentLibrary(const char *filename, 680bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose std::string *errMsg = 0); 690bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose 700bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// This function permanently loads the dynamic library at the given path. 710bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Use this instead of getPermanentLibrary() when you won't need to get 720bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// symbols from the library itself. 73a9b7d60d67b054541cb8507d697eb94beee32f18Chris Lattner /// 740bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// It is safe to call this function multiple times for the same library. 750bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose static bool LoadLibraryPermanently(const char *Filename, 760bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose std::string *ErrMsg = 0) { 770bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose return !getPermanentLibrary(Filename, ErrMsg).isValid(); 780bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose } 797a9369065d1ab22e32af65bd505ce5bc45a2216cReid Spencer 8072501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// This function will search through all previously loaded dynamic 810bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// libraries for the symbol \p symbolName. If it is found, the address of 8272501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// that symbol is returned. If not, null is returned. Note that this will 830bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// search permanently loaded libraries (getPermanentLibrary()) as well 840bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// as explicitly registered symbols (AddSymbol()). 8572501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// @throws std::string on error. 8672501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// @brief Search through libraries for address of a symbol 8772501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner static void *SearchForAddressOfSymbol(const char *symbolName); 880de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer 8972501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// @brief Convenience function for C++ophiles. 9072501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner static void *SearchForAddressOfSymbol(const std::string &symbolName) { 9172501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner return SearchForAddressOfSymbol(symbolName.c_str()); 9272501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner } 93b0b0ea07bb3a24aa336e0145482f37df358918d6Reid Spencer 9472501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// This functions permanently adds the symbol \p symbolName with the 9572501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// value \p symbolValue. These symbols are searched before any 9672501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// libraries. 9772501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// @brief Add searchable symbol/value pair. 980bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose static void AddSymbol(StringRef symbolName, void *symbolValue); 990de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer }; 1000de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer 1010de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer} // End sys namespace 1020de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer} // End llvm namespace 1030de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer 1040de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer#endif // LLVM_SYSTEM_DYNAMIC_LIBRARY_H 105