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
26LLVM_C_EXTERN_C_BEGIN
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} LLVMBinaryType;
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 */
74LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf,
75 LLVMContextRef Context,
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 */
84void LLVMDisposeBinary(LLVMBinaryRef BR);
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 */
95LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR);
96
97/**
98 * Retrieve the specific type of a binary.
99 *
100 * @see llvm::object::Binary::getType
101 */
102LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR);
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 */
115LLVMBinaryRef LLVMMachOUniversalBinaryCopyObjectForArch(LLVMBinaryRef BR,
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 */
131LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR);
132
133/**
134 * Returns whether the given section iterator is at the end.
135 *
136 * @see llvm::object::section_end
137 */
138LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR,
139 LLVMSectionIteratorRef SI);
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 */
152LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR);
153
154/**
155 * Returns whether the given symbol iterator is at the end.
156 *
157 * @see llvm::object::symbol_end
158 */
159LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR,
160 LLVMSymbolIteratorRef SI);
161
162void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI);
163
164void LLVMMoveToNextSection(LLVMSectionIteratorRef SI);
165void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect,
166 LLVMSymbolIteratorRef Sym);
167
168// ObjectFile Symbol iterators
169void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI);
170void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI);
171
172// SectionRef accessors
173const char *LLVMGetSectionName(LLVMSectionIteratorRef SI);
174uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI);
175const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI);
176uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI);
177LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI,
178 LLVMSymbolIteratorRef Sym);
179
180// Section Relocation iterators
181LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section);
182void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI);
183LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section,
184 LLVMRelocationIteratorRef RI);
185void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI);
186
187
188// SymbolRef accessors
189const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI);
190uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI);
191uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI);
192
193// RelocationRef accessors
194uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI);
195LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI);
196uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI);
197// NOTE: Caller takes ownership of returned string of the two
198// following functions.
199const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI);
200const char *LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI);
201
202/** Deprecated: Use LLVMBinaryRef instead. */
203typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef;
204
205/** Deprecated: Use LLVMCreateBinary instead. */
206LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf);
207
208/** Deprecated: Use LLVMDisposeBinary instead. */
209void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile);
210
211/** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */
212LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile);
213
214/** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */
215LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile,
216 LLVMSectionIteratorRef SI);
217
218/** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */
219LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile);
220
221/** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */
222LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile,
223 LLVMSymbolIteratorRef SI);
224/**
225 * @}
226 */
227
228LLVM_C_EXTERN_C_END
229
230#endif
231