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-c/Visibility.h"
25#include "llvm/Config/llvm-config.h"
26
27LLVM_C_EXTERN_C_BEGIN
28
29/**
30 * @defgroup LLVMCObject Object file reading and writing
31 * @ingroup LLVMC
32 *
33 * @{
34 */
35
36// Opaque type wrappers
37typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef;
38typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef;
39typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef;
40
41typedef enum {
42 LLVMBinaryTypeArchive, /**< Archive file. */
43 LLVMBinaryTypeMachOUniversalBinary, /**< Mach-O Universal Binary file. */
44 LLVMBinaryTypeCOFFImportFile, /**< COFF Import file. */
45 LLVMBinaryTypeIR, /**< LLVM IR. */
46 LLVMBinaryTypeWinRes, /**< Windows resource (.res) file. */
47 LLVMBinaryTypeCOFF, /**< COFF Object file. */
48 LLVMBinaryTypeELF32L, /**< ELF 32-bit, little endian. */
49 LLVMBinaryTypeELF32B, /**< ELF 32-bit, big endian. */
50 LLVMBinaryTypeELF64L, /**< ELF 64-bit, little endian. */
51 LLVMBinaryTypeELF64B, /**< ELF 64-bit, big endian. */
52 LLVMBinaryTypeMachO32L, /**< MachO 32-bit, little endian. */
53 LLVMBinaryTypeMachO32B, /**< MachO 32-bit, big endian. */
54 LLVMBinaryTypeMachO64L, /**< MachO 64-bit, little endian. */
55 LLVMBinaryTypeMachO64B, /**< MachO 64-bit, big endian. */
56 LLVMBinaryTypeWasm, /**< Web Assembly. */
57 LLVMBinaryTypeOffload, /**< Offloading fatbinary. */
58 LLVMBinaryTypeDXcontainer, /**< DirectX Binary Container. */
59
60} LLVMBinaryType;
61
62/**
63 * Create a binary file from the given memory buffer.
64 *
65 * The exact type of the binary file will be inferred automatically, and the
66 * appropriate implementation selected. The context may be NULL except if
67 * the resulting file is an LLVM IR file.
68 *
69 * The memory buffer is not consumed by this function. It is the responsibility
70 * of the caller to free it with \c LLVMDisposeMemoryBuffer.
71 *
72 * If NULL is returned, the \p ErrorMessage parameter is populated with the
73 * error's description. It is then the caller's responsibility to free this
74 * message by calling \c LLVMDisposeMessage.
75 *
76 * @see llvm::object::createBinary
77 */
78LLVM_C_ABI LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf,
79 LLVMContextRef Context,
80 char **ErrorMessage);
81
82/**
83 * Dispose of a binary file.
84 *
85 * The binary file does not own its backing buffer. It is the responsibility
86 * of the caller to free it with \c LLVMDisposeMemoryBuffer.
87 */
88LLVM_C_ABI void LLVMDisposeBinary(LLVMBinaryRef BR);
89
90/**
91 * Retrieves a copy of the memory buffer associated with this object file.
92 *
93 * The returned buffer is merely a shallow copy and does not own the actual
94 * backing buffer of the binary. Nevertheless, it is the responsibility of the
95 * caller to free it with \c LLVMDisposeMemoryBuffer.
96 *
97 * @see llvm::object::getMemoryBufferRef
98 */
99LLVM_C_ABI LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR);
100
101/**
102 * Retrieve the specific type of a binary.
103 *
104 * @see llvm::object::Binary::getType
105 */
106LLVM_C_ABI LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR);
107
108/*
109 * For a Mach-O universal binary file, retrieves the object file corresponding
110 * to the given architecture if it is present as a slice.
111 *
112 * If NULL is returned, the \p ErrorMessage parameter is populated with the
113 * error's description. It is then the caller's responsibility to free this
114 * message by calling \c LLVMDisposeMessage.
115 *
116 * It is the responsiblity of the caller to free the returned object file by
117 * calling \c LLVMDisposeBinary.
118 */
119LLVM_C_ABI LLVMBinaryRef LLVMMachOUniversalBinaryCopyObjectForArch(
120 LLVMBinaryRef BR, const char *Arch, size_t ArchLen, 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 */
133LLVM_C_ABI LLVMSectionIteratorRef
134LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR);
135
136/**
137 * Returns whether the given section iterator is at the end.
138 *
139 * @see llvm::object::section_end
140 */
141LLVM_C_ABI LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(
142 LLVMBinaryRef BR, LLVMSectionIteratorRef SI);
143
144/**
145 * Retrieve a copy of the symbol iterator for this object file.
146 *
147 * If there are no symbols, the result is NULL.
148 *
149 * The returned iterator is merely a shallow copy. Nevertheless, it is
150 * the responsibility of the caller to free it with
151 * \c LLVMDisposeSymbolIterator.
152 *
153 * @see llvm::object::symbols()
154 */
155LLVM_C_ABI LLVMSymbolIteratorRef
156LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR);
157
158/**
159 * Returns whether the given symbol iterator is at the end.
160 *
161 * @see llvm::object::symbol_end
162 */
163LLVM_C_ABI LLVMBool
164LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR, LLVMSymbolIteratorRef SI);
165
166LLVM_C_ABI void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI);
167
168LLVM_C_ABI void LLVMMoveToNextSection(LLVMSectionIteratorRef SI);
169LLVM_C_ABI void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect,
170 LLVMSymbolIteratorRef Sym);
171
172// ObjectFile Symbol iterators
173LLVM_C_ABI void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI);
174LLVM_C_ABI void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI);
175
176// SectionRef accessors
177LLVM_C_ABI const char *LLVMGetSectionName(LLVMSectionIteratorRef SI);
178LLVM_C_ABI uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI);
179LLVM_C_ABI const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI);
180LLVM_C_ABI uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI);
181LLVM_C_ABI LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI,
182 LLVMSymbolIteratorRef Sym);
183
184// Section Relocation iterators
185LLVM_C_ABI LLVMRelocationIteratorRef
186LLVMGetRelocations(LLVMSectionIteratorRef Section);
187LLVM_C_ABI void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI);
188LLVM_C_ABI LLVMBool LLVMIsRelocationIteratorAtEnd(
189 LLVMSectionIteratorRef Section, LLVMRelocationIteratorRef RI);
190LLVM_C_ABI void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI);
191
192// SymbolRef accessors
193LLVM_C_ABI const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI);
194LLVM_C_ABI uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI);
195LLVM_C_ABI uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI);
196
197// RelocationRef accessors
198LLVM_C_ABI uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI);
199LLVM_C_ABI LLVMSymbolIteratorRef
200LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI);
201LLVM_C_ABI uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI);
202// NOTE: Caller takes ownership of returned string of the two
203// following functions.
204LLVM_C_ABI const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI);
205LLVM_C_ABI const char *
206LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI);
207
208/** Deprecated: Use LLVMBinaryRef instead. */
209typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef;
210
211/** Deprecated: Use LLVMCreateBinary instead. */
212LLVM_C_ABI LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf);
213
214/** Deprecated: Use LLVMDisposeBinary instead. */
215LLVM_C_ABI void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile);
216
217/** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */
218LLVM_C_ABI LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile);
219
220/** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */
221LLVM_C_ABI LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile,
222 LLVMSectionIteratorRef SI);
223
224/** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */
225LLVM_C_ABI LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile);
226
227/** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */
228LLVM_C_ABI LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile,
229 LLVMSymbolIteratorRef SI);
230/**
231 * @}
232 */
233
234LLVM_C_EXTERN_C_END
235
236#endif
237