LLVM  10.0.0svn
Object.h
Go to the documentation of this file.
1 /*===-- llvm-c/Object.h - Object Lib C Iface --------------------*- C++ -*-===*/
2 /* */
3 /* Part of the LLVM Project, under the Apache License v2.0 with LLVM */
4 /* Exceptions. */
5 /* See https://llvm.org/LICENSE.txt for license information. */
6 /* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception */
7 /* */
8 /*===----------------------------------------------------------------------===*/
9 /* */
10 /* This header declares the C interface to libLLVMObject.a, which */
11 /* implements object file reading and writing. */
12 /* */
13 /* Many exotic languages can interoperate with C code but have a harder time */
14 /* with C++ due to name mangling. So in addition to C, this interface enables */
15 /* tools written in such languages. */
16 /* */
17 /*===----------------------------------------------------------------------===*/
18 
19 #ifndef LLVM_C_OBJECT_H
20 #define LLVM_C_OBJECT_H
21 
22 #include "llvm-c/Types.h"
23 #include "llvm/Config/llvm-config.h"
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 /**
30  * @defgroup LLVMCObject Object file reading and writing
31  * @ingroup LLVMC
32  *
33  * @{
34  */
35 
36 // Opaque type wrappers
37 typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef;
38 typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef;
39 typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef;
40 
41 typedef enum {
42  LLVMBinaryTypeArchive, /**< Archive file. */
43  LLVMBinaryTypeMachOUniversalBinary, /**< Mach-O Universal Binary file. */
44  LLVMBinaryTypeCOFFImportFile, /**< COFF Import file. */
45  LLVMBinaryTypeIR, /**< LLVM IR. */
46  LLVMBinaryTypeWinRes, /**< Windows resource (.res) file. */
47  LLVMBinaryTypeCOFF, /**< COFF Object file. */
48  LLVMBinaryTypeELF32L, /**< ELF 32-bit, little endian. */
49  LLVMBinaryTypeELF32B, /**< ELF 32-bit, big endian. */
50  LLVMBinaryTypeELF64L, /**< ELF 64-bit, little endian. */
51  LLVMBinaryTypeELF64B, /**< ELF 64-bit, big endian. */
52  LLVMBinaryTypeMachO32L, /**< MachO 32-bit, little endian. */
53  LLVMBinaryTypeMachO32B, /**< MachO 32-bit, big endian. */
54  LLVMBinaryTypeMachO64L, /**< MachO 64-bit, little endian. */
55  LLVMBinaryTypeMachO64B, /**< MachO 64-bit, big endian. */
56  LLVMBinaryTypeWasm, /**< Web Assembly. */
58 
59 /**
60  * Create a binary file from the given memory buffer.
61  *
62  * The exact type of the binary file will be inferred automatically, and the
63  * appropriate implementation selected. The context may be NULL except if
64  * the resulting file is an LLVM IR file.
65  *
66  * The memory buffer is not consumed by this function. It is the responsibilty
67  * of the caller to free it with \c LLVMDisposeMemoryBuffer.
68  *
69  * If NULL is returned, the \p ErrorMessage parameter is populated with the
70  * error's description. It is then the caller's responsibility to free this
71  * message by calling \c LLVMDisposeMessage.
72  *
73  * @see llvm::object::createBinary
74  */
77  char **ErrorMessage);
78 
79 /**
80  * Dispose of a binary file.
81  *
82  * The binary file does not own its backing buffer. It is the responsibilty
83  * of the caller to free it with \c LLVMDisposeMemoryBuffer.
84  */
86 
87 /**
88  * Retrieves a copy of the memory buffer associated with this object file.
89  *
90  * The returned buffer is merely a shallow copy and does not own the actual
91  * backing buffer of the binary. Nevertheless, it is the responsibility of the
92  * caller to free it with \c LLVMDisposeMemoryBuffer.
93  *
94  * @see llvm::object::getMemoryBufferRef
95  */
97 
98 /**
99  * Retrieve the specific type of a binary.
100  *
101  * @see llvm::object::Binary::getType
102  */
103 LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR);
104 
105 /*
106  * For a Mach-O universal binary file, retrieves the object file corresponding
107  * to the given architecture if it is present as a slice.
108  *
109  * If NULL is returned, the \p ErrorMessage parameter is populated with the
110  * error's description. It is then the caller's responsibility to free this
111  * message by calling \c LLVMDisposeMessage.
112  *
113  * It is the responsiblity of the caller to free the returned object file by
114  * calling \c LLVMDisposeBinary.
115  */
117  const char *Arch,
118  size_t ArchLen,
119  char **ErrorMessage);
120 
121 /**
122  * Retrieve a copy of the section iterator for this object file.
123  *
124  * If there are no sections, the result is NULL.
125  *
126  * The returned iterator is merely a shallow copy. Nevertheless, it is
127  * the responsibility of the caller to free it with
128  * \c LLVMDisposeSectionIterator.
129  *
130  * @see llvm::object::sections()
131  */
132 LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR);
133 
134 /**
135  * Returns whether the given section iterator is at the end.
136  *
137  * @see llvm::object::section_end
138  */
140  LLVMSectionIteratorRef SI);
141 
142 /**
143  * Retrieve a copy of the symbol iterator for this object file.
144  *
145  * If there are no symbols, the result is NULL.
146  *
147  * The returned iterator is merely a shallow copy. Nevertheless, it is
148  * the responsibility of the caller to free it with
149  * \c LLVMDisposeSymbolIterator.
150  *
151  * @see llvm::object::symbols()
152  */
153 LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR);
154 
155 /**
156  * Returns whether the given symbol iterator is at the end.
157  *
158  * @see llvm::object::symbol_end
159  */
161  LLVMSymbolIteratorRef SI);
162 
163 void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI);
164 
165 void LLVMMoveToNextSection(LLVMSectionIteratorRef SI);
166 void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect,
167  LLVMSymbolIteratorRef Sym);
168 
169 // ObjectFile Symbol iterators
170 void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI);
171 void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI);
172 
173 // SectionRef accessors
174 const char *LLVMGetSectionName(LLVMSectionIteratorRef SI);
175 uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI);
176 const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI);
177 uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI);
178 LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI,
179  LLVMSymbolIteratorRef Sym);
180 
181 // Section Relocation iterators
182 LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section);
183 void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI);
184 LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section,
185  LLVMRelocationIteratorRef RI);
186 void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI);
187 
188 
189 // SymbolRef accessors
190 const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI);
191 uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI);
192 uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI);
193 
194 // RelocationRef accessors
195 uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI);
196 LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI);
197 uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI);
198 // NOTE: Caller takes ownership of returned string of the two
199 // following functions.
200 const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI);
201 const char *LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI);
202 
203 /** Deprecated: Use LLVMBinaryRef instead. */
204 typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef;
205 
206 /** Deprecated: Use LLVMCreateBinary instead. */
207 LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf);
208 
209 /** Deprecated: Use LLVMDisposeBinary instead. */
210 void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile);
211 
212 /** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */
213 LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile);
214 
215 /** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */
216 LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile,
217  LLVMSectionIteratorRef SI);
218 
219 /** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */
220 LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile);
221 
222 /** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */
223 LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile,
224  LLVMSymbolIteratorRef SI);
225 /**
226  * @}
227  */
228 
229 #ifdef __cplusplus
230 }
231 #endif /* defined(__cplusplus) */
232 
233 #endif
LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR)
Retrieve the specific type of a binary.
Definition: Object.cpp:89
LLVMBinaryRef LLVMMachOUniversalBinaryCopyObjectForArch(LLVMBinaryRef BR, const char *Arch, size_t ArchLen, char **ErrorMessage)
Definition: Object.cpp:135
LLVMContext & Context
uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI)
Definition: Object.cpp:271
MachO 64-bit, big endian.
Definition: Object.h:55
ELF 64-bit, little endian.
Definition: Object.h:50
Web Assembly.
Definition: Object.h:56
struct LLVMOpaqueMemoryBuffer * LLVMMemoryBufferRef
LLVM uses a polymorphic type hierarchy which C cannot represent, therefore parameters must be passed ...
Definition: Types.h:49
LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI, LLVMSymbolIteratorRef Sym)
Definition: Object.cpp:275
LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR, LLVMSectionIteratorRef SI)
Returns whether the given section iterator is at the end.
Definition: Object.cpp:157
COFF Import file.
Definition: Object.h:44
LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf)
Deprecated: Use LLVMCreateBinary instead.
Definition: Object.cpp:178
ELF 32-bit, big endian.
Definition: Object.h:49
MachO 32-bit, little endian.
Definition: Object.h:52
const char * LLVMGetSectionContents(LLVMSectionIteratorRef SI)
Definition: Object.cpp:264
LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section, LLVMRelocationIteratorRef RI)
Definition: Object.cpp:290
void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:238
void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect, LLVMSymbolIteratorRef Sym)
Definition: Object.cpp:218
LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf, LLVMContextRef Context, char **ErrorMessage)
Create a binary file from the given memory buffer.
Definition: Object.cpp:64
struct LLVMOpaqueSectionIterator * LLVMSectionIteratorRef
Definition: Object.h:37
struct LLVMOpaqueContext * LLVMContextRef
The top-level container for all LLVM global data.
Definition: Types.h:54
void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI)
Definition: Object.cpp:204
struct LLVMOpaqueBinary * LLVMBinaryRef
Definition: Types.h:169
void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:295
LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:334
Control flow instructions. These all have token chains.
Definition: ISDOpcodes.h:657
void LLVMDisposeBinary(LLVMBinaryRef BR)
Dispose of a binary file.
Definition: Object.cpp:85
uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI)
Definition: Object.cpp:260
struct LLVMOpaqueSymbolIterator * LLVMSymbolIteratorRef
Definition: Object.h:38
LLVMBinaryType
Definition: Object.h:41
LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR, LLVMSymbolIteratorRef SI)
Returns whether the given symbol iterator is at the end.
Definition: Object.cpp:171
struct LLVMOpaqueObjectFile * LLVMObjectFileRef
Deprecated: Use LLVMBinaryRef instead.
Definition: Object.h:204
COFF Object file.
Definition: Object.h:47
Windows resource (.res) file.
Definition: Object.h:46
LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile, LLVMSectionIteratorRef SI)
Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead.
Definition: Object.cpp:208
int LLVMBool
Definition: Types.h:29
LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile)
Deprecated: Use LLVMObjectFileCopySymbolIterator instead.
Definition: Object.cpp:232
ELF 64-bit, big endian.
Definition: Object.h:51
ELF 32-bit, little endian.
Definition: Object.h:48
LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section)
Definition: Object.cpp:281
const char * LLVMGetSectionName(LLVMSectionIteratorRef SI)
Definition: Object.cpp:253
LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR)
Retrieve a copy of the symbol iterator for this object file.
Definition: Object.cpp:163
const char * LLVMGetSymbolName(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:301
MachO 64-bit, little endian.
Definition: Object.h:54
void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:286
LLVM IR.
Definition: Object.h:45
LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile)
Deprecated: Use LLVMObjectFileCopySectionIterator instead.
Definition: Object.cpp:198
Mach-O Universal Binary file.
Definition: Object.h:43
void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:248
uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:313
const char * LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:344
struct LLVMOpaqueRelocationIterator * LLVMRelocationIteratorRef
Definition: Object.h:39
uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:330
LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR)
Retrieves a copy of the memory buffer associated with this object file.
Definition: Object.cpp:78
uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:339
void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile)
Deprecated: Use LLVMDisposeBinary instead.
Definition: Object.cpp:193
MachO 32-bit, big endian.
Definition: Object.h:53
LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile, LLVMSymbolIteratorRef SI)
Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead.
Definition: Object.cpp:242
uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:325
const char * LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:353
Archive file.
Definition: Object.h:42
LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR)
Retrieve a copy of the section iterator for this object file.
Definition: Object.cpp:149
void LLVMMoveToNextSection(LLVMSectionIteratorRef SI)
Definition: Object.cpp:214