blob: 1e9b703a68ff171206bc3ec118381c5ca2471696 [file] [log] [blame]
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001/*===-- llvm-c/Object.h - Object Lib C Iface --------------------*- C++ -*-===*/
2/* */
Andrew Walbran16937d02019-10-22 13:54:20 +01003/* 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 */
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01007/* */
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/Types.h"
23#include "llvm/Config/llvm-config.h"
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29/**
30 * @defgroup LLVMCObject Object file reading and writing
31 * @ingroup LLVMC
32 *
33 * @{
34 */
35
36// Opaque type wrappers
Andrew Scull5e1ddfa2018-08-14 10:06:54 +010037typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef;
38typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef;
39typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef;
40
Andrew Walbran3d2c1972020-04-07 12:24:26 +010041typedef 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} LLVMBinaryType;
Andrew Scull5e1ddfa2018-08-14 10:06:54 +010058
Andrew Walbran3d2c1972020-04-07 12:24:26 +010059/**
60 * Create a binary file from the given memory buffer.
61 *
62 * The exact type of the binary file will be inferred automatically, and the
63 * appropriate implementation selected. The context may be NULL except if
64 * the resulting file is an LLVM IR file.
65 *
66 * The memory buffer is not consumed by this function. It is the responsibilty
67 * of the caller to free it with \c LLVMDisposeMemoryBuffer.
68 *
69 * If NULL is returned, the \p ErrorMessage parameter is populated with the
70 * error's description. It is then the caller's responsibility to free this
71 * message by calling \c LLVMDisposeMessage.
72 *
73 * @see llvm::object::createBinary
74 */
75LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf,
76 LLVMContextRef Context,
77 char **ErrorMessage);
78
79/**
80 * Dispose of a binary file.
81 *
82 * The binary file does not own its backing buffer. It is the responsibilty
83 * of the caller to free it with \c LLVMDisposeMemoryBuffer.
84 */
85void LLVMDisposeBinary(LLVMBinaryRef BR);
86
87/**
88 * Retrieves a copy of the memory buffer associated with this object file.
89 *
90 * The returned buffer is merely a shallow copy and does not own the actual
91 * backing buffer of the binary. Nevertheless, it is the responsibility of the
92 * caller to free it with \c LLVMDisposeMemoryBuffer.
93 *
94 * @see llvm::object::getMemoryBufferRef
95 */
96LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR);
97
98/**
99 * Retrieve the specific type of a binary.
100 *
101 * @see llvm::object::Binary::getType
102 */
103LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR);
104
105/*
106 * For a Mach-O universal binary file, retrieves the object file corresponding
107 * to the given architecture if it is present as a slice.
108 *
109 * If NULL is returned, the \p ErrorMessage parameter is populated with the
110 * error's description. It is then the caller's responsibility to free this
111 * message by calling \c LLVMDisposeMessage.
112 *
113 * It is the responsiblity of the caller to free the returned object file by
114 * calling \c LLVMDisposeBinary.
115 */
116LLVMBinaryRef LLVMMachOUniversalBinaryCopyObjectForArch(LLVMBinaryRef BR,
117 const char *Arch,
118 size_t ArchLen,
119 char **ErrorMessage);
120
121/**
122 * Retrieve a copy of the section iterator for this object file.
123 *
124 * If there are no sections, the result is NULL.
125 *
126 * The returned iterator is merely a shallow copy. Nevertheless, it is
127 * the responsibility of the caller to free it with
128 * \c LLVMDisposeSectionIterator.
129 *
130 * @see llvm::object::sections()
131 */
132LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR);
133
134/**
135 * Returns whether the given section iterator is at the end.
136 *
137 * @see llvm::object::section_end
138 */
139LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR,
140 LLVMSectionIteratorRef SI);
141
142/**
143 * Retrieve a copy of the symbol iterator for this object file.
144 *
145 * If there are no symbols, the result is NULL.
146 *
147 * The returned iterator is merely a shallow copy. Nevertheless, it is
148 * the responsibility of the caller to free it with
149 * \c LLVMDisposeSymbolIterator.
150 *
151 * @see llvm::object::symbols()
152 */
153LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR);
154
155/**
156 * Returns whether the given symbol iterator is at the end.
157 *
158 * @see llvm::object::symbol_end
159 */
160LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR,
161 LLVMSymbolIteratorRef SI);
162
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100163void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI);
Andrew Walbran3d2c1972020-04-07 12:24:26 +0100164
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100165void LLVMMoveToNextSection(LLVMSectionIteratorRef SI);
166void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect,
167 LLVMSymbolIteratorRef Sym);
168
169// ObjectFile Symbol iterators
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100170void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI);
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100171void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI);
172
173// SectionRef accessors
174const char *LLVMGetSectionName(LLVMSectionIteratorRef SI);
175uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI);
176const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI);
177uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI);
178LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI,
179 LLVMSymbolIteratorRef Sym);
180
181// Section Relocation iterators
182LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section);
183void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI);
184LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section,
185 LLVMRelocationIteratorRef RI);
186void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI);
187
188
189// SymbolRef accessors
190const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI);
191uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI);
192uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI);
193
194// RelocationRef accessors
195uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI);
196LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI);
197uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI);
198// NOTE: Caller takes ownership of returned string of the two
199// following functions.
200const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI);
201const char *LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI);
202
Andrew Walbran3d2c1972020-04-07 12:24:26 +0100203/** Deprecated: Use LLVMBinaryRef instead. */
204typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef;
205
206/** Deprecated: Use LLVMCreateBinary instead. */
207LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf);
208
209/** Deprecated: Use LLVMDisposeBinary instead. */
210void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile);
211
212/** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */
213LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile);
214
215/** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */
216LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile,
217 LLVMSectionIteratorRef SI);
218
219/** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */
220LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile);
221
222/** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */
223LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile,
224 LLVMSymbolIteratorRef SI);
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100225/**
226 * @}
227 */
228
229#ifdef __cplusplus
230}
231#endif /* defined(__cplusplus) */
232
233#endif