1 /*===-- llvm-c/Object.h - Object Lib C Iface --------------------*- C++ -*-===*/
3 /* Part of the LLVM Project, under the Apache License v2.0 with LLVM */
5 /* See https://llvm.org/LICENSE.txt for license information. */
6 /* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception */
8 /*===----------------------------------------------------------------------===*/
10 /* This header declares the C interface to libLLVMObject.a, which */
11 /* implements object file reading and writing. */
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. */
17 /*===----------------------------------------------------------------------===*/
19 #ifndef LLVM_C_OBJECT_H
20 #define LLVM_C_OBJECT_H
22 #include "llvm-c/ExternC.h"
23 #include "llvm-c/Types.h"
24 #include "llvm/Config/llvm-config.h"
29 * @defgroup LLVMCObject Object file reading and writing
35 // Opaque type wrappers
36 typedef struct LLVMOpaqueSectionIterator
*LLVMSectionIteratorRef
;
37 typedef struct LLVMOpaqueSymbolIterator
*LLVMSymbolIteratorRef
;
38 typedef struct LLVMOpaqueRelocationIterator
*LLVMRelocationIteratorRef
;
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. */
59 * Create a binary file from the given memory buffer.
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.
65 * The memory buffer is not consumed by this function. It is the responsibilty
66 * of the caller to free it with \c LLVMDisposeMemoryBuffer.
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.
72 * @see llvm::object::createBinary
74 LLVMBinaryRef
LLVMCreateBinary(LLVMMemoryBufferRef MemBuf
,
75 LLVMContextRef Context
,
79 * Dispose of a binary file.
81 * The binary file does not own its backing buffer. It is the responsibilty
82 * of the caller to free it with \c LLVMDisposeMemoryBuffer.
84 void LLVMDisposeBinary(LLVMBinaryRef BR
);
87 * Retrieves a copy of the memory buffer associated with this object file.
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.
93 * @see llvm::object::getMemoryBufferRef
95 LLVMMemoryBufferRef
LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR
);
98 * Retrieve the specific type of a binary.
100 * @see llvm::object::Binary::getType
102 LLVMBinaryType
LLVMBinaryGetType(LLVMBinaryRef BR
);
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.
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.
112 * It is the responsiblity of the caller to free the returned object file by
113 * calling \c LLVMDisposeBinary.
115 LLVMBinaryRef
LLVMMachOUniversalBinaryCopyObjectForArch(LLVMBinaryRef BR
,
118 char **ErrorMessage
);
121 * Retrieve a copy of the section iterator for this object file.
123 * If there are no sections, the result is NULL.
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.
129 * @see llvm::object::sections()
131 LLVMSectionIteratorRef
LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR
);
134 * Returns whether the given section iterator is at the end.
136 * @see llvm::object::section_end
138 LLVMBool
LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR
,
139 LLVMSectionIteratorRef SI
);
142 * Retrieve a copy of the symbol iterator for this object file.
144 * If there are no symbols, the result is NULL.
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.
150 * @see llvm::object::symbols()
152 LLVMSymbolIteratorRef
LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR
);
155 * Returns whether the given symbol iterator is at the end.
157 * @see llvm::object::symbol_end
159 LLVMBool
LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR
,
160 LLVMSymbolIteratorRef SI
);
162 void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI
);
164 void LLVMMoveToNextSection(LLVMSectionIteratorRef SI
);
165 void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect
,
166 LLVMSymbolIteratorRef Sym
);
168 // ObjectFile Symbol iterators
169 void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI
);
170 void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI
);
172 // SectionRef accessors
173 const char *LLVMGetSectionName(LLVMSectionIteratorRef SI
);
174 uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI
);
175 const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI
);
176 uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI
);
177 LLVMBool
LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI
,
178 LLVMSymbolIteratorRef Sym
);
180 // Section Relocation iterators
181 LLVMRelocationIteratorRef
LLVMGetRelocations(LLVMSectionIteratorRef Section
);
182 void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI
);
183 LLVMBool
LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section
,
184 LLVMRelocationIteratorRef RI
);
185 void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI
);
188 // SymbolRef accessors
189 const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI
);
190 uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI
);
191 uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI
);
193 // RelocationRef accessors
194 uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI
);
195 LLVMSymbolIteratorRef
LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI
);
196 uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI
);
197 // NOTE: Caller takes ownership of returned string of the two
198 // following functions.
199 const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI
);
200 const char *LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI
);
202 /** Deprecated: Use LLVMBinaryRef instead. */
203 typedef struct LLVMOpaqueObjectFile
*LLVMObjectFileRef
;
205 /** Deprecated: Use LLVMCreateBinary instead. */
206 LLVMObjectFileRef
LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf
);
208 /** Deprecated: Use LLVMDisposeBinary instead. */
209 void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile
);
211 /** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */
212 LLVMSectionIteratorRef
LLVMGetSections(LLVMObjectFileRef ObjectFile
);
214 /** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */
215 LLVMBool
LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile
,
216 LLVMSectionIteratorRef SI
);
218 /** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */
219 LLVMSymbolIteratorRef
LLVMGetSymbols(LLVMObjectFileRef ObjectFile
);
221 /** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */
222 LLVMBool
LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile
,
223 LLVMSymbolIteratorRef SI
);