VirtualBox

source: vbox/trunk/include/iprt/ldr.h@ 19944

Last change on this file since 19944 was 17019, checked in by vboxsync, 16 years ago

RTLdrIsLoadable: docs, leave validation to RTLdrLoad.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 11.2 KB
Line 
1/** @file
2 * IPRT - Loader.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 *
25 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___iprt_ldr_h
31#define ___iprt_ldr_h
32
33#include <iprt/cdefs.h>
34#include <iprt/types.h>
35
36
37/** @defgroup grp_ldr RTLdr - Loader
38 * @ingroup grp_rt
39 * @{
40 */
41
42__BEGIN_DECLS
43
44
45/**
46 * Gets the default file suffix for DLL/SO/DYLIB/whatever.
47 *
48 * @returns The stuff (readonly).
49 */
50RTDECL(const char *) RTLdrGetSuff(void);
51
52/**
53 * Checks if a library is loadable or not.
54 *
55 * This may attempt load and unload the library.
56 *
57 * @returns true/false accordingly.
58 * @param pszFilename Image filename.
59 */
60RTDECL(bool) RTLdrIsLoadable(const char *pszFilename);
61
62/**
63 * Loads a dynamic load library (/shared object) image file using native
64 * OS facilities.
65 *
66 * The filename will be appended the default DLL/SO extension of
67 * the platform if it have been omitted. This means that it's not
68 * possible to load DLLs/SOs with no extension using this interface,
69 * but that's not a bad tradeoff.
70 *
71 * If no path is specified in the filename, the OS will usually search it's library
72 * path to find the image file.
73 *
74 * @returns iprt status code.
75 * @param pszFilename Image filename.
76 * @param phLdrMod Where to store the handle to the loader module.
77 */
78RTDECL(int) RTLdrLoad(const char *pszFilename, PRTLDRMOD phLdrMod);
79
80/**
81 * Loads a dynamic load library (/shared object) image file residing in the
82 * RTPathAppPrivateArch() directory.
83 *
84 * Suffix is not required.
85 *
86 * @returns iprt status code.
87 * @param pszFilename Image filename. No path.
88 * @param phLdrMod Where to store the handle to the loaded module.
89 */
90RTDECL(int) RTLdrLoadAppPriv(const char *pszFilename, PRTLDRMOD phLdrMod);
91
92/**
93 * Image architecuture specifier for RTLdrOpenEx.
94 */
95typedef enum RTLDRARCH
96{
97 RTLDRARCH_INVALID = 0,
98 /** Whatever. */
99 RTLDRARCH_WHATEVER,
100 /** The host architecture. */
101 RTLDRARCH_HOST,
102 /** 32-bit x86. */
103 RTLDRARCH_X86_32,
104 /** AMD64 (64-bit x86 if you like). */
105 RTLDRARCH_AMD64,
106 /** End of the valid values. */
107 RTLDRARCH_END,
108 /** Make sure the type is a full 32-bit. */
109 RTLDRARCH_32BIT_HACK = 0x7fffffff
110} RTLDRARCH;
111/** Pointer to a RTLDRARCH. */
112typedef RTLDRARCH *PRTLDRARCH;
113
114/**
115 * Open a binary image file, extended version.
116 *
117 * @returns iprt status code.
118 * @param pszFilename Image filename.
119 * @param fFlags Reserved, MBZ.
120 * @param enmArch CPU architecture specifier for the image to be loaded.
121 * @param phLdrMod Where to store the handle to the loader module.
122 */
123RTDECL(int) RTLdrOpen(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
124
125/**
126 * Opens a binary image file using kLdr.
127 *
128 * @returns iprt status code.
129 * @param pszFilename Image filename.
130 * @param phLdrMod Where to store the handle to the loaded module.
131 * @param fFlags Reserved, MBZ.
132 * @param enmArch CPU architecture specifier for the image to be loaded.
133 * @remark Primarily for testing the loader.
134 */
135RTDECL(int) RTLdrOpenkLdr(const char *pszFilename, uint32_t fFlags, RTLDRARCH enmArch, PRTLDRMOD phLdrMod);
136
137/**
138 * What to expect and do with the bits passed to RTLdrOpenBits().
139 */
140typedef enum RTLDROPENBITS
141{
142 /** The usual invalid 0 entry. */
143 RTLDROPENBITS_INVALID = 0,
144 /** The bits are readonly and will never be changed. */
145 RTLDROPENBITS_READONLY,
146 /** The bits are going to be changed and the loader will have to duplicate them
147 * when opening the image. */
148 RTLDROPENBITS_WRITABLE,
149 /** The bits are both the source and destination for the loader operation.
150 * This means that the loader may have to duplicate them prior to changing them. */
151 RTLDROPENBITS_SRC_AND_DST,
152 /** The end of the valid enums. This entry marks the
153 * first invalid entry.. */
154 RTLDROPENBITS_END,
155 RTLDROPENBITS_32BIT_HACK = 0x7fffffff
156} RTLDROPENBITS;
157
158/**
159 * Open a binary image from in-memory bits.
160 *
161 * @returns iprt status code.
162 * @param pvBits The start of the raw-image.
163 * @param cbBits The size of the raw-image.
164 * @param enmBits What to expect from the pvBits.
165 * @param pszLogName What to call the raw-image when logging.
166 * For RTLdrLoad and RTLdrOpen the filename is used for this.
167 * @param phLdrMod Where to store the handle to the loader module.
168 */
169RTDECL(int) RTLdrOpenBits(const void *pvBits, size_t cbBits, RTLDROPENBITS enmBits, const char *pszLogName, PRTLDRMOD phLdrMod);
170
171/**
172 * Closes a loader module handle.
173 *
174 * The handle can be obtained using any of the RTLdrLoad(), RTLdrOpen()
175 * and RTLdrOpenBits() functions.
176 *
177 * @returns iprt status code.
178 * @param hLdrMod The loader module handle.
179 */
180RTDECL(int) RTLdrClose(RTLDRMOD hLdrMod);
181
182/**
183 * Gets the address of a named exported symbol.
184 *
185 * @returns iprt status code.
186 * @param hLdrMod The loader module handle.
187 * @param pszSymbol Symbol name.
188 * @param ppvValue Where to store the symbol value. Note that this is restricted to the
189 * pointer size used on the host!
190 */
191RTDECL(int) RTLdrGetSymbol(RTLDRMOD hLdrMod, const char *pszSymbol, void **ppvValue);
192
193/**
194 * Gets the address of a named exported symbol.
195 *
196 * This function differs from the plain one in that it can deal with
197 * both GC and HC address sizes, and that it can calculate the symbol
198 * value relative to any given base address.
199 *
200 * @returns iprt status code.
201 * @param hLdrMod The loader module handle.
202 * @param pvBits Optional pointer to the loaded image.
203 * Set this to NULL if no RTLdrGetBits() processed image bits are available.
204 * Not supported for RTLdrLoad() images.
205 * @param BaseAddress Image load address.
206 * Not supported for RTLdrLoad() images.
207 * @param pszSymbol Symbol name.
208 * @param pValue Where to store the symbol value.
209 */
210RTDECL(int) RTLdrGetSymbolEx(RTLDRMOD hLdrMod, const void *pvBits, RTUINTPTR BaseAddress, const char *pszSymbol, RTUINTPTR *pValue);
211
212/**
213 * Gets the size of the loaded image.
214 * This is only supported for modules which has been opened using RTLdrOpen() and RTLdrOpenBits().
215 *
216 * @returns image size (in bytes).
217 * @returns ~(size_t)0 on if not opened by RTLdrOpen().
218 * @param hLdrMod Handle to the loader module.
219 * @remark Not supported for RTLdrLoad() images.
220 */
221RTDECL(size_t) RTLdrSize(RTLDRMOD hLdrMod);
222
223/**
224 * Resolve an external symbol during RTLdrGetBits().
225 *
226 * @returns iprt status code.
227 * @param hLdrMod The loader module handle.
228 * @param pszModule Module name.
229 * @param pszSymbol Symbol name, NULL if uSymbol should be used.
230 * @param uSymbol Symbol ordinal, ~0 if pszSymbol should be used.
231 * @param pValue Where to store the symbol value (address).
232 * @param pvUser User argument.
233 */
234typedef DECLCALLBACK(int) RTLDRIMPORT(RTLDRMOD hLdrMod, const char *pszModule, const char *pszSymbol, unsigned uSymbol, RTUINTPTR *pValue, void *pvUser);
235/** Pointer to a FNRTLDRIMPORT() callback function. */
236typedef RTLDRIMPORT *PFNRTLDRIMPORT;
237
238/**
239 * Loads the image into a buffer provided by the user and applies fixups
240 * for the given base address.
241 *
242 * @returns iprt status code.
243 * @param hLdrMod The load module handle.
244 * @param pvBits Where to put the bits.
245 * Must be as large as RTLdrSize() suggests.
246 * @param BaseAddress The base address.
247 * @param pfnGetImport Callback function for resolving imports one by one.
248 * @param pvUser User argument for the callback.
249 * @remark Not supported for RTLdrLoad() images.
250 */
251RTDECL(int) RTLdrGetBits(RTLDRMOD hLdrMod, void *pvBits, RTUINTPTR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void *pvUser);
252
253/**
254 * Relocates bits after getting them.
255 * Useful for code which moves around a bit.
256 *
257 * @returns iprt status code.
258 * @param hLdrMod The loader module handle.
259 * @param pvBits Where the image bits are.
260 * Must've been passed to RTLdrGetBits().
261 * @param NewBaseAddress The new base address.
262 * @param OldBaseAddress The old base address.
263 * @param pfnGetImport Callback function for resolving imports one by one.
264 * @param pvUser User argument for the callback.
265 * @remark Not supported for RTLdrLoad() images.
266 */
267RTDECL(int) RTLdrRelocate(RTLDRMOD hLdrMod, void *pvBits, RTUINTPTR NewBaseAddress, RTUINTPTR OldBaseAddress,
268 PFNRTLDRIMPORT pfnGetImport, void *pvUser);
269
270/**
271 * Enumeration callback function used by RTLdrEnumSymbols().
272 *
273 * @returns iprt status code. Failure will stop the enumeration.
274 * @param hLdrMod The loader module handle.
275 * @param pszSymbol Symbol name. NULL if ordinal only.
276 * @param uSymbol Symbol ordinal, ~0 if not used.
277 * @param Value Symbol value.
278 * @param pvUser The user argument specified to RTLdrEnumSymbols().
279 */
280typedef DECLCALLBACK(int) RTLDRENUMSYMS(RTLDRMOD hLdrMod, const char *pszSymbol, unsigned uSymbol, RTUINTPTR Value, void *pvUser);
281/** Pointer to a RTLDRENUMSYMS() callback function. */
282typedef RTLDRENUMSYMS *PFNRTLDRENUMSYMS;
283
284/**
285 * Enumerates all symbols in a module.
286 *
287 * @returns iprt status code.
288 * @param hLdrMod The loader module handle.
289 * @param fFlags Flags indicating what to return and such.
290 * @param pvBits Optional pointer to the loaded image. (RTLDR_ENUM_SYMBOL_FLAGS_*)
291 * Set this to NULL if no RTLdrGetBits() processed image bits are available.
292 * @param BaseAddress Image load address.
293 * @param pfnCallback Callback function.
294 * @param pvUser User argument for the callback.
295 * @remark Not supported for RTLdrLoad() images.
296 */
297RTDECL(int) RTLdrEnumSymbols(RTLDRMOD hLdrMod, unsigned fFlags, const void *pvBits, RTUINTPTR BaseAddress, PFNRTLDRENUMSYMS pfnCallback, void *pvUser);
298
299/** @name RTLdrEnumSymbols flags.
300 * @{ */
301/** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
302#define RTLDR_ENUM_SYMBOL_FLAGS_ALL RT_BIT(1)
303/** @} */
304
305__END_DECLS
306
307/** @} */
308
309#endif
310
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette