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