[sanitizer] Improve FreeBSD ASLR detection
[llvm-project.git] / llvm / include / llvm-c / Object.h
blob9a9596aaa08cd484239af0aee1652673aed6db13
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 /*===----------------------------------------------------------------------===*/
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"
26 LLVM_C_EXTERN_C_BEGIN
28 /**
29 * @defgroup LLVMCObject Object file reading and writing
30 * @ingroup LLVMC
32 * @{
35 // Opaque type wrappers
36 typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef;
37 typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef;
38 typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef;
40 typedef 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;
58 /**
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,
76 char **ErrorMessage);
78 /**
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);
86 /**
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);
97 /**
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,
116 const char *Arch,
117 size_t ArchLen,
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);
225 * @}
228 LLVM_C_EXTERN_C_END
230 #endif