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 1437ed9c199ca639565f6ce88105f9e39e898d82d0Stephen Hines#ifndef LLVM_SUPPORT_DYNAMICLIBRARY_H 1537ed9c199ca639565f6ce88105f9e39e898d82d0Stephen Hines#define LLVM_SUPPORT_DYNAMICLIBRARY_H 160de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer 170de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer#include <string> 180de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer 190de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencernamespace llvm { 2073a1ad8f0560f01830fd206e84d4a21e5b3b7f59Eli Friedman 2173a1ad8f0560f01830fd206e84d4a21e5b3b7f59Eli Friedmanclass StringRef; 2273a1ad8f0560f01830fd206e84d4a21e5b3b7f59Eli 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 4672501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner public: 4737ed9c199ca639565f6ce88105f9e39e898d82d0Stephen Hines explicit DynamicLibrary(void *data = &Invalid) : Data(data) {} 4837ed9c199ca639565f6ce88105f9e39e898d82d0Stephen Hines 490bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Returns true if the object refers to a valid library. 5037ed9c199ca639565f6ce88105f9e39e898d82d0Stephen Hines bool isValid() const { return Data != &Invalid; } 510bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose 520bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Searches through the library for the symbol \p symbolName. If it is 530bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// found, the address of that symbol is returned. If not, NULL is returned. 540bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Note that NULL will also be returned if the library failed to load. 550bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Use isValid() to distinguish these cases if it is important. 560bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Note that this will \e not search symbols explicitly registered by 570bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// AddSymbol(). 580bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose void *getAddressOfSymbol(const char *symbolName); 590bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose 600bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// This function permanently loads the dynamic library at the given path. 610bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// The library will only be unloaded when the program terminates. 620bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// This returns a valid DynamicLibrary instance on success and an invalid 630bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// instance on failure (see isValid()). \p *errMsg will only be modified 640bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// if the library fails to load. 65a9b7d60d67b054541cb8507d697eb94beee32f18Chris Lattner /// 660bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// It is safe to call this function multiple times for the same library. 670bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// @brief Open a dynamic library permanently. 680bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose static DynamicLibrary getPermanentLibrary(const char *filename, 69dce4a407a24b04eebc6a376f8e62b41aaa7b071fStephen Hines std::string *errMsg = nullptr); 700bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose 710bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// This function permanently loads the dynamic library at the given path. 720bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// Use this instead of getPermanentLibrary() when you won't need to get 730bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// symbols from the library itself. 74a9b7d60d67b054541cb8507d697eb94beee32f18Chris Lattner /// 750bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// It is safe to call this function multiple times for the same library. 760bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose static bool LoadLibraryPermanently(const char *Filename, 77dce4a407a24b04eebc6a376f8e62b41aaa7b071fStephen Hines std::string *ErrMsg = nullptr) { 780bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose return !getPermanentLibrary(Filename, ErrMsg).isValid(); 790bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose } 807a9369065d1ab22e32af65bd505ce5bc45a2216cReid Spencer 8172501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// This function will search through all previously loaded dynamic 820bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// libraries for the symbol \p symbolName. If it is found, the address of 8372501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// that symbol is returned. If not, null is returned. Note that this will 840bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// search permanently loaded libraries (getPermanentLibrary()) as well 850bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose /// as explicitly registered symbols (AddSymbol()). 8672501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// @throws std::string on error. 8772501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// @brief Search through libraries for address of a symbol 8872501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner static void *SearchForAddressOfSymbol(const char *symbolName); 890de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer 9072501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// @brief Convenience function for C++ophiles. 9172501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner static void *SearchForAddressOfSymbol(const std::string &symbolName) { 9272501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner return SearchForAddressOfSymbol(symbolName.c_str()); 9372501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner } 94b0b0ea07bb3a24aa336e0145482f37df358918d6Reid Spencer 9572501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// This functions permanently adds the symbol \p symbolName with the 9672501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// value \p symbolValue. These symbols are searched before any 9772501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// libraries. 9872501b4a2138fcb32f8a6d71054bb1139d8b04b5Chris Lattner /// @brief Add searchable symbol/value pair. 990bce85fbfacec97255337d12fc0ab193f03f21c3Jordy Rose static void AddSymbol(StringRef symbolName, void *symbolValue); 1000de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer }; 1010de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer 1020de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer} // End sys namespace 1030de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer} // End llvm namespace 1040de02a6ba9d9da6aac3c787ec4047068d8250aa9Reid Spencer 10537ed9c199ca639565f6ce88105f9e39e898d82d0Stephen Hines#endif 106