LLVM 19.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
36typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef;
37typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef;
38typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef;
39
40typedef 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 */
77 LLVMContextRef Context,
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. */
205typedef 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
Symbol * Sym
Definition: ELF_riscv.cpp:479
#define LLVM_C_EXTERN_C_BEGIN
Definition: ExternC.h:35
#define LLVM_C_EXTERN_C_END
Definition: ExternC.h:36
StandardInstrumentations SI(Mod->getContext(), Debug, VerifyEach)
uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:339
LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf)
Deprecated: Use LLVMCreateBinary instead.
Definition: Object.cpp:181
LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR)
Retrieve a copy of the symbol iterator for this object file.
Definition: Object.cpp:166
LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section, LLVMRelocationIteratorRef RI)
Definition: Object.cpp:292
struct LLVMOpaqueSymbolIterator * LLVMSymbolIteratorRef
Definition: Object.h:37
void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:297
void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI)
Definition: Object.cpp:207
const char * LLVMGetSectionContents(LLVMSectionIteratorRef SI)
Definition: Object.cpp:266
const char * LLVMGetSectionName(LLVMSectionIteratorRef SI)
Definition: Object.cpp:255
uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:330
uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:325
const char * LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:344
LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile, LLVMSectionIteratorRef SI)
Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead.
Definition: Object.cpp:211
uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI)
Definition: Object.cpp:262
void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:240
LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile)
Deprecated: Use LLVMObjectFileCopySymbolIterator instead.
Definition: Object.cpp:234
LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile)
Deprecated: Use LLVMObjectFileCopySectionIterator instead.
Definition: Object.cpp:201
uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI)
Definition: Object.cpp:273
LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile, LLVMSymbolIteratorRef SI)
Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead.
Definition: Object.cpp:244
LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR)
Retrieve the specific type of a binary.
Definition: Object.cpp:90
LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR, LLVMSectionIteratorRef SI)
Returns whether the given section iterator is at the end.
Definition: Object.cpp:160
void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:250
LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section)
Definition: Object.cpp:283
struct LLVMOpaqueSectionIterator * LLVMSectionIteratorRef
Definition: Object.h:36
LLVMBinaryRef LLVMMachOUniversalBinaryCopyObjectForArch(LLVMBinaryRef BR, const char *Arch, size_t ArchLen, char **ErrorMessage)
Definition: Object.cpp:138
LLVMBinaryType
Definition: Object.h:40
void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect, LLVMSymbolIteratorRef Sym)
Definition: Object.cpp:221
void LLVMDisposeBinary(LLVMBinaryRef BR)
Dispose of a binary file.
Definition: Object.cpp:86
LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR)
Retrieve a copy of the section iterator for this object file.
Definition: Object.cpp:152
void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:288
LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf, LLVMContextRef Context, char **ErrorMessage)
Create a binary file from the given memory buffer.
Definition: Object.cpp:65
LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:334
void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile)
Deprecated: Use LLVMDisposeBinary instead.
Definition: Object.cpp:196
LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR, LLVMSymbolIteratorRef SI)
Returns whether the given symbol iterator is at the end.
Definition: Object.cpp:174
const char * LLVMGetSymbolName(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:303
struct LLVMOpaqueRelocationIterator * LLVMRelocationIteratorRef
Definition: Object.h:38
struct LLVMOpaqueObjectFile * LLVMObjectFileRef
Deprecated: Use LLVMBinaryRef instead.
Definition: Object.h:205
LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR)
Retrieves a copy of the memory buffer associated with this object file.
Definition: Object.cpp:79
void LLVMMoveToNextSection(LLVMSectionIteratorRef SI)
Definition: Object.cpp:217
LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI, LLVMSymbolIteratorRef Sym)
Definition: Object.cpp:277
const char * LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI)
Definition: Object.cpp:353
uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI)
Definition: Object.cpp:314
@ LLVMBinaryTypeIR
LLVM IR.
Definition: Object.h:44
@ LLVMBinaryTypeELF64B
ELF 64-bit, big endian.
Definition: Object.h:50
@ LLVMBinaryTypeArchive
Archive file.
Definition: Object.h:41
@ LLVMBinaryTypeMachO32B
MachO 32-bit, big endian.
Definition: Object.h:52
@ LLVMBinaryTypeWasm
Web Assembly.
Definition: Object.h:55
@ LLVMBinaryTypeELF64L
ELF 64-bit, little endian.
Definition: Object.h:49
@ LLVMBinaryTypeWinRes
Windows resource (.res) file.
Definition: Object.h:45
@ LLVMBinaryTypeMachOUniversalBinary
Mach-O Universal Binary file.
Definition: Object.h:42
@ LLVMBinaryTypeMachO64B
MachO 64-bit, big endian.
Definition: Object.h:54
@ LLVMBinaryTypeCOFF
COFF Object file.
Definition: Object.h:46
@ LLVMBinaryTypeCOFFImportFile
COFF Import file.
Definition: Object.h:43
@ LLVMBinaryTypeELF32B
ELF 32-bit, big endian.
Definition: Object.h:48
@ LLVMBinaryTypeELF32L
ELF 32-bit, little endian.
Definition: Object.h:47
@ LLVMBinaryTypeMachO32L
MachO 32-bit, little endian.
Definition: Object.h:51
@ LLVMBinaryTypeMachO64L
MachO 64-bit, little endian.
Definition: Object.h:53
@ LLVMBinaryTypeOffload
Offloading fatbinary.
Definition: Object.h:56
int LLVMBool
Definition: Types.h:28
struct LLVMOpaqueBinary * LLVMBinaryRef
Definition: Types.h:170
struct LLVMOpaqueMemoryBuffer * LLVMMemoryBufferRef
LLVM uses a polymorphic type hierarchy which C cannot represent, therefore parameters must be passed ...
Definition: Types.h:48
struct LLVMOpaqueContext * LLVMContextRef
The top-level container for all LLVM global data.
Definition: Types.h:53