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/Config/llvm-config.h" 25 26 LLVM_C_EXTERN_C_BEGIN 27 28 /** 29 * @defgroup LLVMCObject Object file reading and writing 30 * @ingroup LLVMC 31 * 32 * @{ 33 */ 34 35 // Opaque type wrappers 36 typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef; 37 typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef; 38 typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef; 39 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; 57 58 /** 59 * Create a binary file from the given memory buffer. 60 * 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. 64 * 65 * The memory buffer is not consumed by this function. It is the responsibilty 66 * of the caller to free it with \c LLVMDisposeMemoryBuffer. 67 * 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. 71 * 72 * @see llvm::object::createBinary 73 */ 74 LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf, 75 LLVMContextRef Context, 76 char **ErrorMessage); 77 78 /** 79 * Dispose of a binary file. 80 * 81 * The binary file does not own its backing buffer. It is the responsibilty 82 * of the caller to free it with \c LLVMDisposeMemoryBuffer. 83 */ 84 void LLVMDisposeBinary(LLVMBinaryRef BR); 85 86 /** 87 * Retrieves a copy of the memory buffer associated with this object file. 88 * 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. 92 * 93 * @see llvm::object::getMemoryBufferRef 94 */ 95 LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR); 96 97 /** 98 * Retrieve the specific type of a binary. 99 * 100 * @see llvm::object::Binary::getType 101 */ 102 LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR); 103 104 /* 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. 107 * 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. 111 * 112 * It is the responsiblity of the caller to free the returned object file by 113 * calling \c LLVMDisposeBinary. 114 */ 115 LLVMBinaryRef LLVMMachOUniversalBinaryCopyObjectForArch(LLVMBinaryRef BR, 116 const char *Arch, 117 size_t ArchLen, 118 char **ErrorMessage); 119 120 /** 121 * Retrieve a copy of the section iterator for this object file. 122 * 123 * If there are no sections, the result is NULL. 124 * 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. 128 * 129 * @see llvm::object::sections() 130 */ 131 LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR); 132 133 /** 134 * Returns whether the given section iterator is at the end. 135 * 136 * @see llvm::object::section_end 137 */ 138 LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR, 139 LLVMSectionIteratorRef SI); 140 141 /** 142 * Retrieve a copy of the symbol iterator for this object file. 143 * 144 * If there are no symbols, the result is NULL. 145 * 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. 149 * 150 * @see llvm::object::symbols() 151 */ 152 LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR); 153 154 /** 155 * Returns whether the given symbol iterator is at the end. 156 * 157 * @see llvm::object::symbol_end 158 */ 159 LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR, 160 LLVMSymbolIteratorRef SI); 161 162 void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI); 163 164 void LLVMMoveToNextSection(LLVMSectionIteratorRef SI); 165 void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect, 166 LLVMSymbolIteratorRef Sym); 167 168 // ObjectFile Symbol iterators 169 void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI); 170 void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI); 171 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); 179 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); 186 187 188 // SymbolRef accessors 189 const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI); 190 uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI); 191 uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI); 192 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); 201 202 /** Deprecated: Use LLVMBinaryRef instead. */ 203 typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef; 204 205 /** Deprecated: Use LLVMCreateBinary instead. */ 206 LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf); 207 208 /** Deprecated: Use LLVMDisposeBinary instead. */ 209 void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile); 210 211 /** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */ 212 LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile); 213 214 /** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */ 215 LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile, 216 LLVMSectionIteratorRef SI); 217 218 /** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */ 219 LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile); 220 221 /** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */ 222 LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile, 223 LLVMSymbolIteratorRef SI); 224 /** 225 * @} 226 */ 227 228 LLVM_C_EXTERN_C_END 229 230 #endif 231