VirtualBox

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

Last change on this file since 14050 was 12423, checked in by vboxsync, 16 years ago

IPRT/SUP: Renamed RTLdrOpenAppSharedLib to RTLdrOpenAppPriv. Hardend versions of RTLdrOpen and RTLdrOpenAppPriv. Use the hardend versions where appropriate.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.1 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 * Loads a dynamic load library (/shared object) image file using native
54 * OS facilities.
55 *
56 * The filename will be appended the default DLL/SO extension of
57 * the platform if it have been omitted. This means that it's not
58 * possible to load DLLs/SOs with no extension using this interface,
59 * but that's not a bad tradeoff.
60 *
61 * If no path is specified in the filename, the OS will usually search it's library
62 * path to find the image file.
63 *
64 * @returns iprt status code.
65 * @param pszFilename Image filename.
66 * @param phLdrMod Where to store the handle to the loader module.
67 */
68RTDECL(int) RTLdrLoad(const char *pszFilename, PRTLDRMOD phLdrMod);
69
70/**
71 * Loads a dynamic load library (/shared object) image file residing in the
72 * RTPathAppPrivateArch() directory.
73 *
74 * Suffix is not required.
75 *
76 * @returns iprt status code.
77 * @param pszFilename Image filename. No path.
78 * @param phLdrMod Where to store the handle to the loaded module.
79 */
80RTDECL(int) RTLdrLoadAppPriv(const char *pszFilename, PRTLDRMOD phLdrMod);
81
82/**
83 * Open a binary image file.
84 *
85 * @returns iprt status code.
86 * @param pszFilename Image filename.
87 * @param phLdrMod Where to store the handle to the loader module.
88 */
89RTDECL(int) RTLdrOpen(const char *pszFilename, PRTLDRMOD phLdrMod);
90
91/**
92 * Opens a binary image file using kLdr.
93 *
94 * @returns iprt status code.
95 * @param pszFilename Image filename.
96 * @param phLdrMod Where to store the handle to the loaded module.
97 * @remark Primarily for testing the loader.
98 */
99RTDECL(int) RTLdrOpenkLdr(const char *pszFilename, PRTLDRMOD phLdrMod);
100
101/**
102 * What to expect and do with the bits passed to RTLdrOpenBits().
103 */
104typedef enum RTLDROPENBITS
105{
106 /** The usual invalid 0 entry. */
107 RTLDROPENBITS_INVALID = 0,
108 /** The bits are readonly and will never be changed. */
109 RTLDROPENBITS_READONLY,
110 /** The bits are going to be changed and the loader will have to duplicate them
111 * when opening the image. */
112 RTLDROPENBITS_WRITABLE,
113 /** The bits are both the source and destination for the loader operation.
114 * This means that the loader may have to duplicate them prior to changing them. */
115 RTLDROPENBITS_SRC_AND_DST,
116 /** The end of the valid enums. This entry marks the
117 * first invalid entry.. */
118 RTLDROPENBITS_END,
119 RTLDROPENBITS_32BIT_HACK = 0x7fffffff
120} RTLDROPENBITS;
121
122/**
123 * Open a binary image from in-memory bits.
124 *
125 * @returns iprt status code.
126 * @param pvBits The start of the raw-image.
127 * @param cbBits The size of the raw-image.
128 * @param enmBits What to expect from the pvBits.
129 * @param pszLogName What to call the raw-image when logging.
130 * For RTLdrLoad and RTLdrOpen the filename is used for this.
131 * @param phLdrMod Where to store the handle to the loader module.
132 */
133RTDECL(int) RTLdrOpenBits(const void *pvBits, size_t cbBits, RTLDROPENBITS enmBits, const char *pszLogName, PRTLDRMOD phLdrMod);
134
135/**
136 * Closes a loader module handle.
137 *
138 * The handle can be obtained using any of the RTLdrLoad(), RTLdrOpen()
139 * and RTLdrOpenBits() functions.
140 *
141 * @returns iprt status code.
142 * @param hLdrMod The loader module handle.
143 */
144RTDECL(int) RTLdrClose(RTLDRMOD hLdrMod);
145
146/**
147 * Gets the address of a named exported symbol.
148 *
149 * @returns iprt status code.
150 * @param hLdrMod The loader module handle.
151 * @param pszSymbol Symbol name.
152 * @param ppvValue Where to store the symbol value. Note that this is restricted to the
153 * pointer size used on the host!
154 */
155RTDECL(int) RTLdrGetSymbol(RTLDRMOD hLdrMod, const char *pszSymbol, void **ppvValue);
156
157/**
158 * Gets the address of a named exported symbol.
159 *
160 * This function differs from the plain one in that it can deal with
161 * both GC and HC address sizes, and that it can calculate the symbol
162 * value relative to any given base address.
163 *
164 * @returns iprt status code.
165 * @param hLdrMod The loader module handle.
166 * @param pvBits Optional pointer to the loaded image.
167 * Set this to NULL if no RTLdrGetBits() processed image bits are available.
168 * Not supported for RTLdrLoad() images.
169 * @param BaseAddress Image load address.
170 * Not supported for RTLdrLoad() images.
171 * @param pszSymbol Symbol name.
172 * @param pValue Where to store the symbol value.
173 */
174RTDECL(int) RTLdrGetSymbolEx(RTLDRMOD hLdrMod, const void *pvBits, RTUINTPTR BaseAddress, const char *pszSymbol, RTUINTPTR *pValue);
175
176/**
177 * Gets the size of the loaded image.
178 * This is only supported for modules which has been opened using RTLdrOpen() and RTLdrOpenBits().
179 *
180 * @returns image size (in bytes).
181 * @returns ~(size_t)0 on if not opened by RTLdrOpen().
182 * @param hLdrMod Handle to the loader module.
183 * @remark Not supported for RTLdrLoad() images.
184 */
185RTDECL(size_t) RTLdrSize(RTLDRMOD hLdrMod);
186
187/**
188 * Resolve an external symbol during RTLdrGetBits().
189 *
190 * @returns iprt status code.
191 * @param hLdrMod The loader module handle.
192 * @param pszModule Module name.
193 * @param pszSymbol Symbol name, NULL if uSymbol should be used.
194 * @param uSymbol Symbol ordinal, ~0 if pszSymbol should be used.
195 * @param pValue Where to store the symbol value (address).
196 * @param pvUser User argument.
197 */
198typedef DECLCALLBACK(int) RTLDRIMPORT(RTLDRMOD hLdrMod, const char *pszModule, const char *pszSymbol, unsigned uSymbol, RTUINTPTR *pValue, void *pvUser);
199/** Pointer to a FNRTLDRIMPORT() callback function. */
200typedef RTLDRIMPORT *PFNRTLDRIMPORT;
201
202/**
203 * Loads the image into a buffer provided by the user and applies fixups
204 * for the given base address.
205 *
206 * @returns iprt status code.
207 * @param hLdrMod The load module handle.
208 * @param pvBits Where to put the bits.
209 * Must be as large as RTLdrSize() suggests.
210 * @param BaseAddress The base address.
211 * @param pfnGetImport Callback function for resolving imports one by one.
212 * @param pvUser User argument for the callback.
213 * @remark Not supported for RTLdrLoad() images.
214 */
215RTDECL(int) RTLdrGetBits(RTLDRMOD hLdrMod, void *pvBits, RTUINTPTR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void *pvUser);
216
217/**
218 * Relocates bits after getting them.
219 * Useful for code which moves around a bit.
220 *
221 * @returns iprt status code.
222 * @param hLdrMod The loader module handle.
223 * @param pvBits Where the image bits are.
224 * Must've been passed to RTLdrGetBits().
225 * @param NewBaseAddress The new base address.
226 * @param OldBaseAddress The old base address.
227 * @param pfnGetImport Callback function for resolving imports one by one.
228 * @param pvUser User argument for the callback.
229 * @remark Not supported for RTLdrLoad() images.
230 */
231RTDECL(int) RTLdrRelocate(RTLDRMOD hLdrMod, void *pvBits, RTUINTPTR NewBaseAddress, RTUINTPTR OldBaseAddress,
232 PFNRTLDRIMPORT pfnGetImport, void *pvUser);
233
234/**
235 * Enumeration callback function used by RTLdrEnumSymbols().
236 *
237 * @returns iprt status code. Failure will stop the enumeration.
238 * @param hLdrMod The loader module handle.
239 * @param pszSymbol Symbol name. NULL if ordinal only.
240 * @param uSymbol Symbol ordinal, ~0 if not used.
241 * @param Value Symbol value.
242 * @param pvUser The user argument specified to RTLdrEnumSymbols().
243 */
244typedef DECLCALLBACK(int) RTLDRENUMSYMS(RTLDRMOD hLdrMod, const char *pszSymbol, unsigned uSymbol, RTUINTPTR Value, void *pvUser);
245/** Pointer to a RTLDRENUMSYMS() callback function. */
246typedef RTLDRENUMSYMS *PFNRTLDRENUMSYMS;
247
248/**
249 * Enumerates all symbols in a module.
250 *
251 * @returns iprt status code.
252 * @param hLdrMod The loader module handle.
253 * @param fFlags Flags indicating what to return and such.
254 * @param pvBits Optional pointer to the loaded image. (RTLDR_ENUM_SYMBOL_FLAGS_*)
255 * Set this to NULL if no RTLdrGetBits() processed image bits are available.
256 * @param BaseAddress Image load address.
257 * @param pfnCallback Callback function.
258 * @param pvUser User argument for the callback.
259 * @remark Not supported for RTLdrLoad() images.
260 */
261RTDECL(int) RTLdrEnumSymbols(RTLDRMOD hLdrMod, unsigned fFlags, const void *pvBits, RTUINTPTR BaseAddress, PFNRTLDRENUMSYMS pfnCallback, void *pvUser);
262
263/** @name RTLdrEnumSymbols flags.
264 * @{ */
265/** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
266#define RTLDR_ENUM_SYMBOL_FLAGS_ALL RT_BIT(1)
267/** @} */
268
269__END_DECLS
270
271/** @} */
272
273#endif
274
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