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