LLVM  11.0.0git
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/ExternC.h"
23 #include "llvm-c/Types.h"
24 #include "llvm/Config/llvm-config.h"
25 
27 
28 /**
29  * @defgroup LLVMCObject Object file reading and writing
30  * @ingroup LLVMC
31  *
32  * @{
33  */
34 
35 // Opaque type wrappers
36 typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef;
37 typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef;
38 typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef;
39 
40 typedef enum {
41  LLVMBinaryTypeArchive, /**< Archive file. */
42  LLVMBinaryTypeMachOUniversalBinary, /**< Mach-O Universal Binary file. */
43  LLVMBinaryTypeCOFFImportFile, /**< COFF Import file. */
44  LLVMBinaryTypeIR, /**< LLVM IR. */
45  LLVMBinaryTypeWinRes, /**< Windows resource (.res) file. */
46  LLVMBinaryTypeCOFF, /**< COFF Object file. */
47  LLVMBinaryTypeELF32L, /**< ELF 32-bit, little endian. */
48  LLVMBinaryTypeELF32B, /**< ELF 32-bit, big endian. */
49  LLVMBinaryTypeELF64L, /**< ELF 64-bit, little endian. */
50  LLVMBinaryTypeELF64B, /**< ELF 64-bit, big endian. */
51  LLVMBinaryTypeMachO32L, /**< MachO 32-bit, little endian. */
52  LLVMBinaryTypeMachO32B, /**< MachO 32-bit, big endian. */
53  LLVMBinaryTypeMachO64L, /**< MachO 64-bit, little endian. */
54  LLVMBinaryTypeMachO64B, /**< MachO 64-bit, big endian. */
55  LLVMBinaryTypeWasm, /**< Web Assembly. */
57 
58 /**
59  * Create a binary file from the given memory buffer.
60  *
61  * The exact type of the binary file will be inferred automatically, and the
62  * appropriate implementation selected. The context may be NULL except if
63  * the resulting file is an LLVM IR file.
64  *
65  * The memory buffer is not consumed by this function. It is the responsibilty
66  * of the caller to free it with \c LLVMDisposeMemoryBuffer.
67  *
68  * If NULL is returned, the \p ErrorMessage parameter is populated with the
69  * error's description. It is then the caller's responsibility to free this
70  * message by calling \c LLVMDisposeMessage.
71  *
72  * @see llvm::object::createBinary
73  */
76  char **ErrorMessage);
77 
78 /**
79  * Dispose of a binary file.
80  *
81  * The binary file does not own its backing buffer. It is the responsibilty
82  * of the caller to free it with \c LLVMDisposeMemoryBuffer.
83  */
85 
86 /**
87  * Retrieves a copy of the memory buffer associated with this object file.
88  *
89  * The returned buffer is merely a shallow copy and does not own the actual
90  * backing buffer of the binary. Nevertheless, it is the responsibility of the
91  * caller to free it with \c LLVMDisposeMemoryBuffer.
92  *
93  * @see llvm::object::getMemoryBufferRef
94  */
96 
97 /**
98  * Retrieve the specific type of a binary.
99  *
100  * @see llvm::object::Binary::getType
101  */
103 
104 /*
105  * For a Mach-O universal binary file, retrieves the object file corresponding
106  * to the given architecture if it is present as a slice.
107  *
108  * If NULL is returned, the \p ErrorMessage parameter is populated with the
109  * error's description. It is then the caller's responsibility to free this
110  * message by calling \c LLVMDisposeMessage.
111  *
112  * It is the responsiblity of the caller to free the returned object file by
113  * calling \c LLVMDisposeBinary.
114  */
116  const char *Arch,
117  size_t ArchLen,
118  char **ErrorMessage);
119 
120 /**
121  * Retrieve a copy of the section iterator for this object file.
122  *
123  * If there are no sections, the result is NULL.
124  *
125  * The returned iterator is merely a shallow copy. Nevertheless, it is
126  * the responsibility of the caller to free it with
127  * \c LLVMDisposeSectionIterator.
128  *
129  * @see llvm::object::sections()
130  */
132 
133 /**
134  * Returns whether the given section iterator is at the end.
135  *
136  * @see llvm::object::section_end
137  */
140 
141 /**
142  * Retrieve a copy of the symbol iterator for this object file.
143  *
144  * If there are no symbols, the result is NULL.
145  *
146  * The returned iterator is merely a shallow copy. Nevertheless, it is
147  * the responsibility of the caller to free it with
148  * \c LLVMDisposeSymbolIterator.
149  *
150  * @see llvm::object::symbols()
151  */
153 
154 /**
155  * Returns whether the given symbol iterator is at the end.
156  *
157  * @see llvm::object::symbol_end
158  */
161 
163 
167 
168 // ObjectFile Symbol iterators
171 
172 // SectionRef accessors
179 
180 // Section Relocation iterators
186 
187 
188 // SymbolRef accessors
192 
193 // RelocationRef accessors
197 // NOTE: Caller takes ownership of returned string of the two
198 // following functions.
201 
202 /** Deprecated: Use LLVMBinaryRef instead. */
203 typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef;
204 
205 /** Deprecated: Use LLVMCreateBinary instead. */
207 
208 /** Deprecated: Use LLVMDisposeBinary instead. */
210 
211 /** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */
213 
214 /** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */
217 
218 /** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */
220 
221 /** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */
224 /**
225  * @}
226  */
227 
229 
230 #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:54
ELF 64-bit, little endian.
Definition: Object.h:49
Web Assembly.
Definition: Object.h:55
struct LLVMOpaqueMemoryBuffer * LLVMMemoryBufferRef
LLVM uses a polymorphic type hierarchy which C cannot represent, therefore parameters must be passed ...
Definition: Types.h:48
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:43
LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf)
Deprecated: Use LLVMCreateBinary instead.
Definition: Object.cpp:178
ELF 32-bit, big endian.
Definition: Object.h:48
MachO 32-bit, little endian.
Definition: Object.h:51
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:36
struct LLVMOpaqueContext * LLVMContextRef
The top-level container for all LLVM global data.
Definition: Types.h:53
void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI)
Definition: Object.cpp:204
struct LLVMOpaqueBinary * LLVMBinaryRef
Definition: Types.h:168
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:833
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:37
LLVMBinaryType
Definition: Object.h:40
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:203
COFF Object file.
Definition: Object.h:46
Windows resource (.res) file.
Definition: Object.h:45
LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile, LLVMSectionIteratorRef SI)
Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead.
Definition: Object.cpp:208
int LLVMBool
Definition: Types.h:28
LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile)
Deprecated: Use LLVMObjectFileCopySymbolIterator instead.
Definition: Object.cpp:232
ELF 64-bit, big endian.
Definition: Object.h:50
ELF 32-bit, little endian.
Definition: Object.h:47
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:53
void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:286
LLVM IR.
Definition: Object.h:44
LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile)
Deprecated: Use LLVMObjectFileCopySectionIterator instead.
Definition: Object.cpp:198
Mach-O Universal Binary file.
Definition: Object.h:42
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:38
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
#define LLVM_C_EXTERN_C_END
Definition: ExternC.h:36
#define LLVM_C_EXTERN_C_BEGIN
Definition: ExternC.h:35
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:52
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:41
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