VirtualBox

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

Last change on this file since 3251 was 2981, checked in by vboxsync, 17 years ago

InnoTek -> innotek: all the headers and comments.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 9.2 KB
Line 
1/** @file
2 * innotek Portable Runtime - Loader.
3 */
4
5/*
6 * Copyright (C) 2006-2007 innotek GmbH
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 as published by the Free Software Foundation,
12 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13 * distribution. VirtualBox OSE is distributed in the hope that it will
14 * be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * If you received this file as part of a commercial VirtualBox
17 * distribution, then only the terms of your commercial VirtualBox
18 * license agreement apply instead of the previous paragraph.
19 */
20
21#ifndef __iprt_ldr_h__
22#define __iprt_ldr_h__
23
24#include <iprt/cdefs.h>
25#include <iprt/types.h>
26
27
28/** @defgroup grp_ldr RTLdr - Loader
29 * @ingroup grp_rt
30 * @{
31 */
32
33__BEGIN_DECLS
34
35
36/**
37 * Loads a dynamic load library (/shared object) image file using native
38 * OS facilities.
39 *
40 * The filename will be appended the default DLL/SO extension of
41 * the platform if it have been omitted. This means that it's not
42 * possible to load DLLs/SOs with no extension using this interface,
43 * but that's not a bad tradeoff.
44 *
45 * If no path is specified in the filename, the OS will usually search it's library
46 * path to find the image file.
47 *
48 * @returns iprt status code.
49 * @param pszFilename Image filename.
50 * @param phLdrMod Where to store the handle to the loader module.
51 */
52RTDECL(int) RTLdrLoad(const char *pszFilename, PRTLDRMOD phLdrMod);
53
54/**
55 * Open a binary image file.
56 *
57 * @returns iprt status code.
58 * @param pszFilename Image filename.
59 * @param phLdrMod Where to store the handle to the loader module.
60 */
61RTDECL(int) RTLdrOpen(const char *pszFilename, PRTLDRMOD phLdrMod);
62
63/**
64 * Opens a binary image file using kLdr.
65 *
66 * @returns iprt status code.
67 * @param pszFilename Image filename.
68 * @param phLdrMod Where to store the handle to the loaded module.
69 * @remark Primarily for testing the loader.
70 */
71RTDECL(int) RTLdrOpenkLdr(const char *pszFilename, PRTLDRMOD phLdrMod);
72
73/**
74 * What to expect and do with the bits passed to RTLdrOpenBits().
75 */
76typedef enum RTLDROPENBITS
77{
78 /** The usual invalid 0 entry. */
79 RTLDROPENBITS_INVALID = 0,
80 /** The bits are readonly and will never be changed. */
81 RTLDROPENBITS_READONLY,
82 /** The bits are going to be changed and the loader will have to duplicate them
83 * when opening the image. */
84 RTLDROPENBITS_WRITABLE,
85 /** The bits are both the source and destination for the loader operation.
86 * This means that the loader may have to duplicate them prior to changing them. */
87 RTLDROPENBITS_SRC_AND_DST,
88 /** The end of the valid enums. This entry marks the
89 * first invalid entry.. */
90 RTLDROPENBITS_END,
91 RTLDROPENBITS_32BIT_HACK = 0x7fffffff
92} RTLDROPENBITS;
93
94/**
95 * Open a binary image from in-memory bits.
96 *
97 * @returns iprt status code.
98 * @param pvBits The start of the raw-image.
99 * @param cbBits The size of the raw-image.
100 * @param enmBits What to expect from the pvBits.
101 * @param pszLogName What to call the raw-image when logging.
102 * For RTLdrLoad and RTLdrOpen the filename is used for this.
103 * @param phLdrMod Where to store the handle to the loader module.
104 */
105RTDECL(int) RTLdrOpenBits(const void *pvBits, size_t cbBits, RTLDROPENBITS enmBits, const char *pszLogName, PRTLDRMOD phLdrMod);
106
107/**
108 * Closes a loader module handle.
109 *
110 * The handle can be obtained using any of the RTLdrLoad(), RTLdrOpen()
111 * and RTLdrOpenBits() functions.
112 *
113 * @returns iprt status code.
114 * @param hLdrMod The loader module handle.
115 */
116RTDECL(int) RTLdrClose(RTLDRMOD hLdrMod);
117
118/**
119 * Gets the address of a named exported symbol.
120 *
121 * @returns iprt status code.
122 * @param hLdrMod The loader module handle.
123 * @param pszSymbol Symbol name.
124 * @param ppvValue Where to store the symbol value. Note that this is restricted to the
125 * pointer size used on the host!
126 */
127RTDECL(int) RTLdrGetSymbol(RTLDRMOD hLdrMod, const char *pszSymbol, void **ppvValue);
128
129/**
130 * Gets the address of a named exported symbol.
131 *
132 * This function differs from the plain one in that it can deal with
133 * both GC and HC address sizes, and that it can calculate the symbol
134 * value relative to any given base address.
135 *
136 * @returns iprt status code.
137 * @param hLdrMod The loader module handle.
138 * @param pvBits Optional pointer to the loaded image.
139 * Set this to NULL if no RTLdrGetBits() processed image bits are available.
140 * Not supported for RTLdrLoad() images.
141 * @param BaseAddress Image load address.
142 * Not supported for RTLdrLoad() images.
143 * @param pszSymbol Symbol name.
144 * @param pValue Where to store the symbol value.
145 */
146RTDECL(int) RTLdrGetSymbolEx(RTLDRMOD hLdrMod, const void *pvBits, RTUINTPTR BaseAddress, const char *pszSymbol, RTUINTPTR *pValue);
147
148/**
149 * Gets the size of the loaded image.
150 * This is only supported for modules which has been opened using RTLdrOpen() and RTLdrOpenBits().
151 *
152 * @returns image size (in bytes).
153 * @returns ~(size_t)0 on if not opened by RTLdrOpen().
154 * @param hLdrMod Handle to the loader module.
155 * @remark Not supported for RTLdrLoad() images.
156 */
157RTDECL(size_t) RTLdrSize(RTLDRMOD hLdrMod);
158
159/**
160 * Resolve an external symbol during RTLdrGetBits().
161 *
162 * @returns iprt status code.
163 * @param hLdrMod The loader module handle.
164 * @param pszModule Module name.
165 * @param pszSymbol Symbol name, NULL if uSymbol should be used.
166 * @param uSymbol Symbol ordinal, ~0 if pszSymbol should be used.
167 * @param pValue Where to store the symbol value (address).
168 * @param pvUser User argument.
169 */
170typedef DECLCALLBACK(int) RTLDRIMPORT(RTLDRMOD hLdrMod, const char *pszModule, const char *pszSymbol, unsigned uSymbol, RTUINTPTR *pValue, void *pvUser);
171/** Pointer to a FNRTLDRIMPORT() callback function. */
172typedef RTLDRIMPORT *PFNRTLDRIMPORT;
173
174/**
175 * Loads the image into a buffer provided by the user and applies fixups
176 * for the given base address.
177 *
178 * @returns iprt status code.
179 * @param hLdrMod The load module handle.
180 * @param pvBits Where to put the bits.
181 * Must be as large as RTLdrSize() suggests.
182 * @param BaseAddress The base address.
183 * @param pfnGetImport Callback function for resolving imports one by one.
184 * @param pvUser User argument for the callback.
185 * @remark Not supported for RTLdrLoad() images.
186 */
187RTDECL(int) RTLdrGetBits(RTLDRMOD hLdrMod, void *pvBits, RTUINTPTR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void *pvUser);
188
189/**
190 * Relocates bits after getting them.
191 * Useful for code which moves around a bit.
192 *
193 * @returns iprt status code.
194 * @param hLdrMod The loader module handle.
195 * @param pvBits Where the image bits are.
196 * Must've been passed to RTLdrGetBits().
197 * @param NewBaseAddress The new base address.
198 * @param OldBaseAddress The old base address.
199 * @param pfnGetImport Callback function for resolving imports one by one.
200 * @param pvUser User argument for the callback.
201 * @remark Not supported for RTLdrLoad() images.
202 */
203RTDECL(int) RTLdrRelocate(RTLDRMOD hLdrMod, void *pvBits, RTUINTPTR NewBaseAddress, RTUINTPTR OldBaseAddress,
204 PFNRTLDRIMPORT pfnGetImport, void *pvUser);
205
206/**
207 * Enumeration callback function used by RTLdrEnumSymbols().
208 *
209 * @returns iprt status code. Failure will stop the enumeration.
210 * @param hLdrMod The loader module handle.
211 * @param pszSymbol Symbol name. NULL if ordinal only.
212 * @param uSymbol Symbol ordinal, ~0 if not used.
213 * @param Value Symbol value.
214 * @param pvUser The user argument specified to RTLdrEnumSymbols().
215 */
216typedef DECLCALLBACK(int) RTLDRENUMSYMS(RTLDRMOD hLdrMod, const char *pszSymbol, unsigned uSymbol, RTUINTPTR Value, void *pvUser);
217/** Pointer to a RTLDRENUMSYMS() callback function. */
218typedef RTLDRENUMSYMS *PFNRTLDRENUMSYMS;
219
220/**
221 * Enumerates all symbols in a module.
222 *
223 * @returns iprt status code.
224 * @param hLdrMod The loader module handle.
225 * @param fFlags Flags indicating what to return and such.
226 * @param pvBits Optional pointer to the loaded image. (RTLDR_ENUM_SYMBOL_FLAGS_*)
227 * Set this to NULL if no RTLdrGetBits() processed image bits are available.
228 * @param BaseAddress Image load address.
229 * @param pfnCallback Callback function.
230 * @param pvUser User argument for the callback.
231 * @remark Not supported for RTLdrLoad() images.
232 */
233RTDECL(int) RTLdrEnumSymbols(RTLDRMOD hLdrMod, unsigned fFlags, const void *pvBits, RTUINTPTR BaseAddress, PFNRTLDRENUMSYMS pfnCallback, void *pvUser);
234
235/** @name RTLdrEnumSymbols flags.
236 * @{ */
237/** Returns ALL kinds of symbols. The default is to only return public/exported symbols. */
238#define RTLDR_ENUM_SYMBOL_FLAGS_ALL BIT(1)
239/** @} */
240
241__END_DECLS
242
243/** @} */
244
245#endif
246
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