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/Types.h" 23 #include "llvm/Config/llvm-config.h" 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 /** 30 * @defgroup LLVMCObject Object file reading and writing 31 * @ingroup LLVMC 32 * 33 * @{ 34 */ 35 36 // Opaque type wrappers 37 typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef; 38 typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef; 39 typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef; 40 41 typedef 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; 58 59 /** 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 */ 75 LLVMBinaryRef 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 */ 85 void 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 */ 96 LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR); 97 98 /** 99 * Retrieve the specific type of a binary. 100 * 101 * @see llvm::object::Binary::getType 102 */ 103 LLVMBinaryType 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 */ 116 LLVMBinaryRef 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 */ 132 LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR); 133 134 /** 135 * Returns whether the given section iterator is at the end. 136 * 137 * @see llvm::object::section_end 138 */ 139 LLVMBool 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 */ 153 LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR); 154 155 /** 156 * Returns whether the given symbol iterator is at the end. 157 * 158 * @see llvm::object::symbol_end 159 */ 160 LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR, 161 LLVMSymbolIteratorRef SI); 162 163 void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI); 164 165 void LLVMMoveToNextSection(LLVMSectionIteratorRef SI); 166 void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect, 167 LLVMSymbolIteratorRef Sym); 168 169 // ObjectFile Symbol iterators 170 void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI); 171 void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI); 172 173 // SectionRef accessors 174 const char *LLVMGetSectionName(LLVMSectionIteratorRef SI); 175 uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI); 176 const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI); 177 uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI); 178 LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI, 179 LLVMSymbolIteratorRef Sym); 180 181 // Section Relocation iterators 182 LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section); 183 void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI); 184 LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section, 185 LLVMRelocationIteratorRef RI); 186 void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI); 187 188 189 // SymbolRef accessors 190 const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI); 191 uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI); 192 uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI); 193 194 // RelocationRef accessors 195 uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI); 196 LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI); 197 uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI); 198 // NOTE: Caller takes ownership of returned string of the two 199 // following functions. 200 const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI); 201 const char *LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI); 202 203 /** Deprecated: Use LLVMBinaryRef instead. */ 204 typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef; 205 206 /** Deprecated: Use LLVMCreateBinary instead. */ 207 LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf); 208 209 /** Deprecated: Use LLVMDisposeBinary instead. */ 210 void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile); 211 212 /** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */ 213 LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile); 214 215 /** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */ 216 LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile, 217 LLVMSectionIteratorRef SI); 218 219 /** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */ 220 LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile); 221 222 /** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */ 223 LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile, 224 LLVMSymbolIteratorRef SI); 225 /** 226 * @} 227 */ 228 229 #ifdef __cplusplus 230 } 231 #endif /* defined(__cplusplus) */ 232 233 #endif 234