boost/dll/shared_library_load_mode.hpp

0001 // Copyright 2014 Renato Tegon Forti, Antony Polukhin.
0002 // Copyright Antony Polukhin, 2015-2023.
0003 //
0004 // Distributed under the Boost Software License, Version 1.0.
0005 // (See accompanying file LICENSE_1_0.txt
0006 // or copy at http://www.boost.org/LICENSE_1_0.txt)
0007
0008 #ifndef BOOST_DLL_SHARED_LIBRARY_MODE_HPP
0009 #define BOOST_DLL_SHARED_LIBRARY_MODE_HPP
0010
0011 #include <boost/dll/config.hpp>
0012 #include <boost/predef/os.h>
0013 #include <boost/predef/library/c.h>
0014
0015 #if BOOST_OS_WINDOWS
0016 #   include <boost/winapi/dll.hpp>
0017 #else
0018 #   include <dlfcn.h>
0019 #endif
0020
0021 #ifdef BOOST_HAS_PRAGMA_ONCE
0022 # pragma once
0023 #endif
0024
0025 /// \file boost/dll/shared_library_load_mode.hpp
0026 /// \brief Contains only the boost::dll::load_mode::type enum and operators related to it.
0027
0028 namespace boost { namespace dll { namespace load_mode {
0029
0030 /*! Library load modes.
0031 *
0032 * Each of system family provides own modes. Flags not supported by a particular platform will be silently ignored.
0033 *
0034 * For a detailed description of platform specific options see:
0035 * <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/ms684179(v=vs.85).aspx">Windows specific options</a>,
0036 * <a href="http://pubs.opengroup.org/onlinepubs/000095399/functions/dlopen.html">POSIX specific options</a>.
0037 *
0038 */
0039
0040 enum type {
0041 #ifdef BOOST_DLL_DOXYGEN
0042     /*!
0043     * Default open mode. See the \b Default: comments below to find out the flags that are enabled by default.
0044     */
0045     default_mode,
0046
0047     /*!
0048     * \b Platforms: Windows
0049     *
0050     * \b Default: disabled
0051     *
0052     * If this value is used, and the executable module is a DLL, the system does
0053     * not call DllMain for process and thread initialization and termination.
0054     * Also, the system does not load additional executable modules that are
0055     * referenced by the specified module.
0056     *
0057     * Note Do not use this value; it is provided only for backward compatibility.
0058     * If you are planning to access only data or resources in the DLL, use
0059     * LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE or LOAD_LIBRARY_AS_IMAGE_RESOURCE
0060     * or both.
0061     */
0062     dont_resolve_dll_references,
0063
0064     /*!
0065     * \b Platforms: Windows
0066     *
0067     * \b Default: disabled
0068     *
0069     * If this value is used, the system does not check AppLocker rules or
0070     * apply Software Restriction Policies for the DLL.
0071     */
0072     load_ignore_code_authz_level,
0073
0074     /*!
0075     * \b Platforms: Windows
0076     *
0077     * \b Default: disabled
0078     *
0079     * If this value is used and lpFileName specifies an absolute path,
0080     * the system uses the alternate file search strategy.
0081     *
0082     * This value cannot be combined with any LOAD_LIBRARY_SEARCH flag.
0083     */
0084     load_with_altered_search_path,
0085
0086     /*!
0087     * \b Platforms: POSIX
0088     *
0089     * \b Default: enabled
0090     *
0091     * Relocations shall be performed at an implementation-defined time, ranging
0092     * from the time of the dlopen() call until the first reference to a given
0093     * symbol occurs.
0094     *
0095     * Specifying RTLD_LAZY should improve performance on implementations
0096     * supporting dynamic symbol binding as a process may not reference all of
0097     * the functions in any given object. And, for systems supporting dynamic
0098     * symbol resolution for normal process execution, this behavior mimics
0099     * the normal handling of process execution.
0100     */
0101     rtld_lazy,
0102
0103     /*!
0104     * \b Platforms: POSIX
0105     *
0106     * \b Default: disabled
0107     *
0108     * All necessary relocations shall be performed when the object is first
0109     * loaded. This may waste some processing if relocations are performed for
0110     * functions that are never referenced. This behavior may be useful for
0111     * plugins that need to know as soon as an object is loaded that all
0112     * symbols referenced during execution are available.
0113     */
0114     rtld_now,
0115
0116     /*!
0117     * \b Platforms: POSIX
0118     *
0119     * \b Default: disabled
0120     *
0121     * The object's symbols shall be made available for the relocation
0122     * processing of any other object. In addition, symbol lookup using
0123     * dlopen(0, mode) and an associated dlsym() allows objects loaded
0124     * with this mode to be searched.
0125     */
0126     rtld_global,
0127
0128     /*!
0129     * \b Platforms: POSIX
0130     *
0131     * \b Default: enabled
0132     *
0133     * The object's symbols shall not be made available for the relocation
0134     * processing of any other object.
0135     *
0136     * This is a default Windows behavior that can not be changed.
0137     */
0138     rtld_local,
0139
0140     /*!
0141     * \b Platforms: POSIX (requires glibc >= 2.3.4)
0142     *
0143     * \b Default: disabled
0144     *
0145     * The object will use its own symbols in preference to global symbols
0146     * with the same name contained in libraries that have already been loaded.
0147     * This flag is not specified in POSIX.1-2001.
0148     */
0149     rtld_deepbind,
0150
0151     /*!
0152     * \b Platforms: Windows, POSIX
0153     *
0154     * \b Default: disabled
0155     *
0156     * Append a platform specific extension and prefix to shared library filename before trying to load it.
0157     * If load attempt fails, try to load with exactly specified name.
0158     *
0159     * \b Example:
0160     * \code
0161     * // Opens `./my_plugins/plugin1.dll` on Windows, `./my_plugins/libplugin1.so` on Linux, `./my_plugins/libplugin1.dylib` on MacOS.
0162     * // If that fails, loads `./my_plugins/plugin1`
0163     * boost::dll::shared_library lib("./my_plugins/plugin1", load_mode::append_decorations);
0164     * \endcode
0165     */
0166     append_decorations,
0167     /*!
0168     * \b Platforms: Windows, POSIX
0169     *
0170     * \b Default: disabled
0171     *
0172     * Allow loading from system folders if path to library contains no parent path.
0173     */
0174     search_system_folders
0175 #elif BOOST_OS_WINDOWS
0176     default_mode                          = 0,
0177     dont_resolve_dll_references           = boost::winapi::DONT_RESOLVE_DLL_REFERENCES_,
0178     load_ignore_code_authz_level          = boost::winapi::LOAD_IGNORE_CODE_AUTHZ_LEVEL_,
0179     load_with_altered_search_path         = boost::winapi::LOAD_WITH_ALTERED_SEARCH_PATH_,
0180     rtld_lazy                             = 0,
0181     rtld_now                              = 0,
0182     rtld_global                           = 0,
0183     rtld_local                            = 0,
0184     rtld_deepbind                         = 0,
0185     append_decorations                    = 0x00800000,
0186     search_system_folders                 = (append_decorations << 1)
0187 #else
0188     default_mode                          = 0,
0189     dont_resolve_dll_references           = 0,
0190     load_ignore_code_authz_level          = 0,
0191     load_with_altered_search_path         = 0,
0192     rtld_lazy                             = RTLD_LAZY,
0193     rtld_now                              = RTLD_NOW,
0194     rtld_global                           = RTLD_GLOBAL,
0195     rtld_local                            = RTLD_LOCAL,
0196
0197 #if BOOST_LIB_C_GNU < BOOST_VERSION_NUMBER(2,3,4)
0198     rtld_deepbind                         = 0,
0199 #else
0200     rtld_deepbind                         = RTLD_DEEPBIND,
0201 #endif
0202
0203     append_decorations                    = 0x00800000,
0204     search_system_folders                 = (append_decorations << 1)
0205 #endif
0206 };
0207
0208
0209 /// Free operators for load_mode::type flag manipulation.
0210 BOOST_CONSTEXPR inline type operator|(type left, type right) BOOST_NOEXCEPT {
0211     return static_cast<type>(
0212         static_cast<unsigned int>(left) | static_cast<unsigned int>(right)
0213     );
0214 }
0215 BOOST_CXX14_CONSTEXPR inline type& operator|=(type& left, type right) BOOST_NOEXCEPT {
0216     left = left | right;
0217     return left;
0218 }
0219
0220 BOOST_CONSTEXPR inline type operator&(type left, type right) BOOST_NOEXCEPT {
0221     return static_cast<type>(
0222         static_cast<unsigned int>(left) & static_cast<unsigned int>(right)
0223     );
0224 }
0225 BOOST_CXX14_CONSTEXPR inline type& operator&=(type& left, type right) BOOST_NOEXCEPT {
0226     left = left & right;
0227     return left;
0228 }
0229
0230 BOOST_CONSTEXPR inline type operator^(type left, type right) BOOST_NOEXCEPT {
0231     return static_cast<type>(
0232         static_cast<unsigned int>(left) ^ static_cast<unsigned int>(right)
0233     );
0234 }
0235 BOOST_CXX14_CONSTEXPR inline type& operator^=(type& left, type right) BOOST_NOEXCEPT {
0236     left = left ^ right;
0237     return left;
0238 }
0239
0240 BOOST_CONSTEXPR inline type operator~(type left) BOOST_NOEXCEPT {
0241     return static_cast<type>(
0242         ~static_cast<unsigned int>(left)
0243     );
0244 }
0245
0246 }}} // boost::dll::load_mode
0247
0248 #endif // BOOST_DLL_SHARED_LIBRARY_MODE_HPP