LLVM  16.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. */
56  LLVMBinaryTypeOffload, /**< Offloading fatbinary. */
57 
59 
60 /**
61  * Create a binary file from the given memory buffer.
62  *
63  * The exact type of the binary file will be inferred automatically, and the
64  * appropriate implementation selected. The context may be NULL except if
65  * the resulting file is an LLVM IR file.
66  *
67  * The memory buffer is not consumed by this function. It is the responsibilty
68  * of the caller to free it with \c LLVMDisposeMemoryBuffer.
69  *
70  * If NULL is returned, the \p ErrorMessage parameter is populated with the
71  * error's description. It is then the caller's responsibility to free this
72  * message by calling \c LLVMDisposeMessage.
73  *
74  * @see llvm::object::createBinary
75  */
78  char **ErrorMessage);
79 
80 /**
81  * Dispose of a binary file.
82  *
83  * The binary file does not own its backing buffer. It is the responsibilty
84  * of the caller to free it with \c LLVMDisposeMemoryBuffer.
85  */
87 
88 /**
89  * Retrieves a copy of the memory buffer associated with this object file.
90  *
91  * The returned buffer is merely a shallow copy and does not own the actual
92  * backing buffer of the binary. Nevertheless, it is the responsibility of the
93  * caller to free it with \c LLVMDisposeMemoryBuffer.
94  *
95  * @see llvm::object::getMemoryBufferRef
96  */
98 
99 /**
100  * Retrieve the specific type of a binary.
101  *
102  * @see llvm::object::Binary::getType
103  */
105 
106 /*
107  * For a Mach-O universal binary file, retrieves the object file corresponding
108  * to the given architecture if it is present as a slice.
109  *
110  * If NULL is returned, the \p ErrorMessage parameter is populated with the
111  * error's description. It is then the caller's responsibility to free this
112  * message by calling \c LLVMDisposeMessage.
113  *
114  * It is the responsiblity of the caller to free the returned object file by
115  * calling \c LLVMDisposeBinary.
116  */
118  const char *Arch,
119  size_t ArchLen,
120  char **ErrorMessage);
121 
122 /**
123  * Retrieve a copy of the section iterator for this object file.
124  *
125  * If there are no sections, the result is NULL.
126  *
127  * The returned iterator is merely a shallow copy. Nevertheless, it is
128  * the responsibility of the caller to free it with
129  * \c LLVMDisposeSectionIterator.
130  *
131  * @see llvm::object::sections()
132  */
134 
135 /**
136  * Returns whether the given section iterator is at the end.
137  *
138  * @see llvm::object::section_end
139  */
142 
143 /**
144  * Retrieve a copy of the symbol iterator for this object file.
145  *
146  * If there are no symbols, the result is NULL.
147  *
148  * The returned iterator is merely a shallow copy. Nevertheless, it is
149  * the responsibility of the caller to free it with
150  * \c LLVMDisposeSymbolIterator.
151  *
152  * @see llvm::object::symbols()
153  */
155 
156 /**
157  * Returns whether the given symbol iterator is at the end.
158  *
159  * @see llvm::object::symbol_end
160  */
163 
165 
169 
170 // ObjectFile Symbol iterators
173 
174 // SectionRef accessors
181 
182 // Section Relocation iterators
188 
189 
190 // SymbolRef accessors
194 
195 // RelocationRef accessors
199 // NOTE: Caller takes ownership of returned string of the two
200 // following functions.
203 
204 /** Deprecated: Use LLVMBinaryRef instead. */
205 typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef;
206 
207 /** Deprecated: Use LLVMCreateBinary instead. */
209 
210 /** Deprecated: Use LLVMDisposeBinary instead. */
212 
213 /** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */
215 
216 /** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */
219 
220 /** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */
222 
223 /** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */
226 /**
227  * @}
228  */
229 
231 
232 #endif
LLVMGetSectionContainsSymbol
LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI, LLVMSymbolIteratorRef Sym)
Definition: Object.cpp:277
LLVMContextRef
struct LLVMOpaqueContext * LLVMContextRef
The top-level container for all LLVM global data.
Definition: Types.h:53
LLVMGetRelocationOffset
uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:330
LLVMCreateObjectFile
LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf)
Deprecated: Use LLVMCreateBinary instead.
Definition: Object.cpp:181
LLVMMoveToNextSection
void LLVMMoveToNextSection(LLVMSectionIteratorRef SI)
Definition: Object.cpp:217
LLVMBinaryTypeOffload
@ LLVMBinaryTypeOffload
Offloading fatbinary.
Definition: Object.h:56
LLVMIsSymbolIteratorAtEnd
LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile, LLVMSymbolIteratorRef SI)
Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead.
Definition: Object.cpp:244
Types.h
LLVMGetSymbolSize
uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:325
LLVMDisposeSectionIterator
void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI)
Definition: Object.cpp:207
LLVMDisposeBinary
void LLVMDisposeBinary(LLVMBinaryRef BR)
Dispose of a binary file.
Definition: Object.cpp:86
LLVMIsRelocationIteratorAtEnd
LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section, LLVMRelocationIteratorRef RI)
Definition: Object.cpp:292
LLVMBinaryGetType
LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR)
Retrieve the specific type of a binary.
Definition: Object.cpp:90
LLVMMachOUniversalBinaryCopyObjectForArch
LLVMBinaryRef LLVMMachOUniversalBinaryCopyObjectForArch(LLVMBinaryRef BR, const char *Arch, size_t ArchLen, char **ErrorMessage)
Definition: Object.cpp:138
LLVMGetSectionAddress
uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI)
Definition: Object.cpp:273
Context
LLVMContext & Context
Definition: NVVMIntrRange.cpp:66
llvm::ARMBuildAttrs::Section
@ Section
Legacy Tags.
Definition: ARMBuildAttributes.h:82
LLVMBinaryTypeELF32B
@ LLVMBinaryTypeELF32B
ELF 32-bit, big endian.
Definition: Object.h:48
LLVMBinaryTypeWinRes
@ LLVMBinaryTypeWinRes
Windows resource (.res) file.
Definition: Object.h:45
LLVMCreateBinary
LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf, LLVMContextRef Context, char **ErrorMessage)
Create a binary file from the given memory buffer.
Definition: Object.cpp:65
LLVMObjectFileRef
struct LLVMOpaqueObjectFile * LLVMObjectFileRef
Deprecated: Use LLVMBinaryRef instead.
Definition: Object.h:205
LLVMBinaryTypeMachO32L
@ LLVMBinaryTypeMachO32L
MachO 32-bit, little endian.
Definition: Object.h:51
LLVMBinaryTypeCOFFImportFile
@ LLVMBinaryTypeCOFFImportFile
COFF Import file.
Definition: Object.h:43
LLVMMoveToNextRelocation
void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:297
SI
@ SI
Definition: SIInstrInfo.cpp:7966
LLVMBinaryTypeELF32L
@ LLVMBinaryTypeELF32L
ELF 32-bit, little endian.
Definition: Object.h:47
LLVMMoveToContainingSection
void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect, LLVMSymbolIteratorRef Sym)
Definition: Object.cpp:221
LLVMGetSectionContents
const char * LLVMGetSectionContents(LLVMSectionIteratorRef SI)
Definition: Object.cpp:266
LLVMSectionIteratorRef
struct LLVMOpaqueSectionIterator * LLVMSectionIteratorRef
Definition: Object.h:36
LLVMDisposeRelocationIterator
void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:288
LLVMSymbolIteratorRef
struct LLVMOpaqueSymbolIterator * LLVMSymbolIteratorRef
Definition: Object.h:37
uint64_t
LLVMObjectFileCopySymbolIterator
LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR)
Retrieve a copy of the symbol iterator for this object file.
Definition: Object.cpp:166
LLVMDisposeSymbolIterator
void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:240
LLVMBinaryTypeMachO64L
@ LLVMBinaryTypeMachO64L
MachO 64-bit, little endian.
Definition: Object.h:53
LLVMGetSymbolName
const char * LLVMGetSymbolName(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:303
LLVMGetSymbols
LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile)
Deprecated: Use LLVMObjectFileCopySymbolIterator instead.
Definition: Object.cpp:234
LLVMIsSectionIteratorAtEnd
LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile, LLVMSectionIteratorRef SI)
Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead.
Definition: Object.cpp:211
LLVMGetSectionSize
uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI)
Definition: Object.cpp:262
LLVMGetSections
LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile)
Deprecated: Use LLVMObjectFileCopySectionIterator instead.
Definition: Object.cpp:201
LLVMObjectFileIsSymbolIteratorAtEnd
LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR, LLVMSymbolIteratorRef SI)
Returns whether the given symbol iterator is at the end.
Definition: Object.cpp:174
LLVMGetRelocations
LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section)
Definition: Object.cpp:283
LLVMBinaryRef
struct LLVMOpaqueBinary * LLVMBinaryRef
Definition: Types.h:168
LLVMBinaryType
LLVMBinaryType
Definition: Object.h:40
LLVMBinaryTypeCOFF
@ LLVMBinaryTypeCOFF
COFF Object file.
Definition: Object.h:46
LLVMGetRelocationSymbol
LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:334
LLVMBinaryTypeMachO32B
@ LLVMBinaryTypeMachO32B
MachO 32-bit, big endian.
Definition: Object.h:52
LLVMBinaryTypeELF64B
@ LLVMBinaryTypeELF64B
ELF 64-bit, big endian.
Definition: Object.h:50
LLVM_C_EXTERN_C_END
#define LLVM_C_EXTERN_C_END
Definition: ExternC.h:36
LLVMRelocationIteratorRef
struct LLVMOpaqueRelocationIterator * LLVMRelocationIteratorRef
Definition: Object.h:38
LLVMBool
int LLVMBool
Definition: Types.h:28
llvm::ISD::BR
@ BR
Control flow instructions. These all have token chains.
Definition: ISDOpcodes.h:982
LLVMDisposeObjectFile
void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile)
Deprecated: Use LLVMDisposeBinary instead.
Definition: Object.cpp:196
LLVMGetRelocationValueString
const char * LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:353
LLVM_C_EXTERN_C_BEGIN
#define LLVM_C_EXTERN_C_BEGIN
Definition: ExternC.h:35
LLVMObjectFileCopySectionIterator
LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR)
Retrieve a copy of the section iterator for this object file.
Definition: Object.cpp:152
LLVMBinaryTypeArchive
@ LLVMBinaryTypeArchive
Archive file.
Definition: Object.h:41
LLVMGetSectionName
const char * LLVMGetSectionName(LLVMSectionIteratorRef SI)
Definition: Object.cpp:255
LLVMBinaryCopyMemoryBuffer
LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR)
Retrieves a copy of the memory buffer associated with this object file.
Definition: Object.cpp:79
LLVMGetRelocationType
uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:339
LLVMBinaryTypeELF64L
@ LLVMBinaryTypeELF64L
ELF 64-bit, little endian.
Definition: Object.h:49
LLVMGetSymbolAddress
uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:314
LLVMObjectFileIsSectionIteratorAtEnd
LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR, LLVMSectionIteratorRef SI)
Returns whether the given section iterator is at the end.
Definition: Object.cpp:160
LLVMMemoryBufferRef
struct LLVMOpaqueMemoryBuffer * LLVMMemoryBufferRef
LLVM uses a polymorphic type hierarchy which C cannot represent, therefore parameters must be passed ...
Definition: Types.h:48
LLVMGetRelocationTypeName
const char * LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:344
LLVMBinaryTypeIR
@ LLVMBinaryTypeIR
LLVM IR.
Definition: Object.h:44
LLVMBinaryTypeMachOUniversalBinary
@ LLVMBinaryTypeMachOUniversalBinary
Mach-O Universal Binary file.
Definition: Object.h:42
LLVMBinaryTypeMachO64B
@ LLVMBinaryTypeMachO64B
MachO 64-bit, big endian.
Definition: Object.h:54
ExternC.h
LLVMBinaryTypeWasm
@ LLVMBinaryTypeWasm
Web Assembly.
Definition: Object.h:55
LLVMMoveToNextSymbol
void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:250