1// Copyright 2014 Renato Tegon Forti, Antony Polukhin.
2// Copyright Antony Polukhin, 2015-2024.
3//
4// Distributed under the Boost Software License, Version 1.0.
5// (See accompanying file LICENSE_1_0.txt
6// or copy at http://www.boost.org/LICENSE_1_0.txt)
7
8#ifndef BOOST_DLL_SHARED_LIBRARY_MODE_HPP
9#define BOOST_DLL_SHARED_LIBRARY_MODE_HPP
10
11#include <boost/dll/config.hpp>
12#include <boost/predef/os.h>
13#include <boost/predef/library/c.h>
14
15#if BOOST_OS_WINDOWS
16# include <boost/winapi/dll.hpp>
17#else
18# include <dlfcn.h>
19#endif
20
21#ifdef BOOST_HAS_PRAGMA_ONCE
22# pragma once
23#endif
24
25/// \file boost/dll/shared_library_load_mode.hpp
26/// \brief Contains only the boost::dll::load_mode::type enum and operators related to it.
27
28namespace boost { namespace dll { namespace load_mode {
29
30/*! Library load modes.
31*
32* Each of system family provides own modes. Flags not supported by a particular platform will be silently ignored.
33*
34* For a detailed description of platform specific options see:
35* <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/ms684179(v=vs.85).aspx">Windows specific options</a>,
36* <a href="http://pubs.opengroup.org/onlinepubs/000095399/functions/dlopen.html">POSIX specific options</a>.
37*
38*/
39
40enum type {
41#ifdef BOOST_DLL_DOXYGEN
42 /*!
43 * Default open mode. See the \b Default: comments below to find out the flags that are enabled by default.
44 */
45 default_mode,
46
47 /*!
48 * \b Platforms: Windows
49 *
50 * \b Default: disabled
51 *
52 * If this value is used, and the executable module is a DLL, the system does
53 * not call DllMain for process and thread initialization and termination.
54 * Also, the system does not load additional executable modules that are
55 * referenced by the specified module.
56 *
57 * Note Do not use this value; it is provided only for backward compatibility.
58 * If you are planning to access only data or resources in the DLL, use
59 * LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE or LOAD_LIBRARY_AS_IMAGE_RESOURCE
60 * or both.
61 */
62 dont_resolve_dll_references,
63
64 /*!
65 * \b Platforms: Windows
66 *
67 * \b Default: disabled
68 *
69 * If this value is used, the system does not check AppLocker rules or
70 * apply Software Restriction Policies for the DLL.
71 */
72 load_ignore_code_authz_level,
73
74 /*!
75 * \b Platforms: Windows
76 *
77 * \b Default: disabled
78 *
79 * If this value is used and lpFileName specifies an absolute path,
80 * the system uses the alternate file search strategy.
81 *
82 * This value cannot be combined with any LOAD_LIBRARY_SEARCH flag.
83 */
84 load_with_altered_search_path,
85
86 /*!
87 * \b Platforms: POSIX
88 *
89 * \b Default: enabled
90 *
91 * Relocations shall be performed at an implementation-defined time, ranging
92 * from the time of the dlopen() call until the first reference to a given
93 * symbol occurs.
94 *
95 * Specifying RTLD_LAZY should improve performance on implementations
96 * supporting dynamic symbol binding as a process may not reference all of
97 * the functions in any given object. And, for systems supporting dynamic
98 * symbol resolution for normal process execution, this behavior mimics
99 * the normal handling of process execution.
100 */
101 rtld_lazy,
102
103 /*!
104 * \b Platforms: POSIX
105 *
106 * \b Default: disabled
107 *
108 * All necessary relocations shall be performed when the object is first
109 * loaded. This may waste some processing if relocations are performed for
110 * functions that are never referenced. This behavior may be useful for
111 * plugins that need to know as soon as an object is loaded that all
112 * symbols referenced during execution are available.
113 */
114 rtld_now,
115
116 /*!
117 * \b Platforms: POSIX
118 *
119 * \b Default: disabled
120 *
121 * The object's symbols shall be made available for the relocation
122 * processing of any other object. In addition, symbol lookup using
123 * dlopen(0, mode) and an associated dlsym() allows objects loaded
124 * with this mode to be searched.
125 */
126 rtld_global,
127
128 /*!
129 * \b Platforms: POSIX
130 *
131 * \b Default: enabled
132 *
133 * The object's symbols shall not be made available for the relocation
134 * processing of any other object.
135 *
136 * This is a default Windows behavior that can not be changed.
137 */
138 rtld_local,
139
140 /*!
141 * \b Platforms: POSIX (requires glibc >= 2.3.4)
142 *
143 * \b Default: disabled
144 *
145 * The object will use its own symbols in preference to global symbols
146 * with the same name contained in libraries that have already been loaded.
147 * This flag is not specified in POSIX.1-2001.
148 */
149 rtld_deepbind,
150
151 /*!
152 * \b Platforms: Windows, POSIX
153 *
154 * \b Default: disabled
155 *
156 * Append a platform specific extension and prefix to shared library filename before trying to load it.
157 * If load attempt fails, try to load with exactly specified name.
158 *
159 * \b Example:
160 * \code
161 * // Opens `./my_plugins/plugin1.dll` on Windows, `./my_plugins/libplugin1.so` on Linux, `./my_plugins/libplugin1.dylib` on MacOS.
162 * // If that fails, loads `./my_plugins/plugin1`
163 * boost::dll::shared_library lib("./my_plugins/plugin1", load_mode::append_decorations);
164 * \endcode
165 */
166 append_decorations,
167 /*!
168 * \b Platforms: Windows, POSIX
169 *
170 * \b Default: disabled
171 *
172 * Allow loading from system folders if path to library contains no parent path.
173 */
174 search_system_folders
175#elif BOOST_OS_WINDOWS
176 default_mode = 0,
177 dont_resolve_dll_references = boost::winapi::DONT_RESOLVE_DLL_REFERENCES_,
178 load_ignore_code_authz_level = boost::winapi::LOAD_IGNORE_CODE_AUTHZ_LEVEL_,
179 load_with_altered_search_path = boost::winapi::LOAD_WITH_ALTERED_SEARCH_PATH_,
180 rtld_lazy = 0,
181 rtld_now = 0,
182 rtld_global = 0,
183 rtld_local = 0,
184 rtld_deepbind = 0,
185 append_decorations = 0x00800000,
186 search_system_folders = (append_decorations << 1)
187#else
188 default_mode = 0,
189 dont_resolve_dll_references = 0,
190 load_ignore_code_authz_level = 0,
191 load_with_altered_search_path = 0,
192 rtld_lazy = RTLD_LAZY,
193 rtld_now = RTLD_NOW,
194 rtld_global = RTLD_GLOBAL,
195 rtld_local = RTLD_LOCAL,
196
197#if BOOST_LIB_C_GNU < BOOST_VERSION_NUMBER(2,3,4)
198 rtld_deepbind = 0,
199#else
200 rtld_deepbind = RTLD_DEEPBIND,
201#endif
202
203 append_decorations = 0x00800000,
204 search_system_folders = (append_decorations << 1)
205#endif
206};
207
208
209/// Free operators for load_mode::type flag manipulation.
210BOOST_CONSTEXPR inline type operator|(type left, type right) BOOST_NOEXCEPT {
211 return static_cast<type>(
212 static_cast<unsigned int>(left) | static_cast<unsigned int>(right)
213 );
214}
215BOOST_CXX14_CONSTEXPR inline type& operator|=(type& left, type right) BOOST_NOEXCEPT {
216 left = left | right;
217 return left;
218}
219
220BOOST_CONSTEXPR inline type operator&(type left, type right) BOOST_NOEXCEPT {
221 return static_cast<type>(
222 static_cast<unsigned int>(left) & static_cast<unsigned int>(right)
223 );
224}
225BOOST_CXX14_CONSTEXPR inline type& operator&=(type& left, type right) BOOST_NOEXCEPT {
226 left = left & right;
227 return left;
228}
229
230BOOST_CONSTEXPR inline type operator^(type left, type right) BOOST_NOEXCEPT {
231 return static_cast<type>(
232 static_cast<unsigned int>(left) ^ static_cast<unsigned int>(right)
233 );
234}
235BOOST_CXX14_CONSTEXPR inline type& operator^=(type& left, type right) BOOST_NOEXCEPT {
236 left = left ^ right;
237 return left;
238}
239
240BOOST_CONSTEXPR inline type operator~(type left) BOOST_NOEXCEPT {
241 return static_cast<type>(
242 ~static_cast<unsigned int>(left)
243 );
244}
245
246}}} // boost::dll::load_mode
247
248#endif // BOOST_DLL_SHARED_LIBRARY_MODE_HPP
249

source code of boost/libs/dll/include/boost/dll/shared_library_load_mode.hpp