237 lines · c
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_H20#define LLVM_C_OBJECT_H21 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 27LLVM_C_EXTERN_C_BEGIN28 29/**30 * @defgroup LLVMCObject Object file reading and writing31 * @ingroup LLVMC32 *33 * @{34 */35 36// Opaque type wrappers37typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef;38typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef;39typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef;40 41typedef 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 LLVMBinaryTypeDXcontainer, /**< DirectX Binary Container. */59 60} LLVMBinaryType;61 62/**63 * Create a binary file from the given memory buffer.64 *65 * The exact type of the binary file will be inferred automatically, and the66 * appropriate implementation selected. The context may be NULL except if67 * the resulting file is an LLVM IR file.68 *69 * The memory buffer is not consumed by this function. It is the responsibilty70 * of the caller to free it with \c LLVMDisposeMemoryBuffer.71 *72 * If NULL is returned, the \p ErrorMessage parameter is populated with the73 * error's description. It is then the caller's responsibility to free this74 * message by calling \c LLVMDisposeMessage.75 *76 * @see llvm::object::createBinary77 */78LLVM_C_ABI LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf,79 LLVMContextRef Context,80 char **ErrorMessage);81 82/**83 * Dispose of a binary file.84 *85 * The binary file does not own its backing buffer. It is the responsibilty86 * of the caller to free it with \c LLVMDisposeMemoryBuffer.87 */88LLVM_C_ABI void LLVMDisposeBinary(LLVMBinaryRef BR);89 90/**91 * Retrieves a copy of the memory buffer associated with this object file.92 *93 * The returned buffer is merely a shallow copy and does not own the actual94 * backing buffer of the binary. Nevertheless, it is the responsibility of the95 * caller to free it with \c LLVMDisposeMemoryBuffer.96 *97 * @see llvm::object::getMemoryBufferRef98 */99LLVM_C_ABI LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR);100 101/**102 * Retrieve the specific type of a binary.103 *104 * @see llvm::object::Binary::getType105 */106LLVM_C_ABI LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR);107 108/*109 * For a Mach-O universal binary file, retrieves the object file corresponding110 * to the given architecture if it is present as a slice.111 *112 * If NULL is returned, the \p ErrorMessage parameter is populated with the113 * error's description. It is then the caller's responsibility to free this114 * message by calling \c LLVMDisposeMessage.115 *116 * It is the responsiblity of the caller to free the returned object file by117 * calling \c LLVMDisposeBinary.118 */119LLVM_C_ABI LLVMBinaryRef LLVMMachOUniversalBinaryCopyObjectForArch(120 LLVMBinaryRef BR, const char *Arch, size_t ArchLen, 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 is128 * the responsibility of the caller to free it with129 * \c LLVMDisposeSectionIterator.130 *131 * @see llvm::object::sections()132 */133LLVM_C_ABI LLVMSectionIteratorRef134LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR);135 136/**137 * Returns whether the given section iterator is at the end.138 *139 * @see llvm::object::section_end140 */141LLVM_C_ABI LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(142 LLVMBinaryRef BR, LLVMSectionIteratorRef SI);143 144/**145 * Retrieve a copy of the symbol iterator for this object file.146 *147 * If there are no symbols, the result is NULL.148 *149 * The returned iterator is merely a shallow copy. Nevertheless, it is150 * the responsibility of the caller to free it with151 * \c LLVMDisposeSymbolIterator.152 *153 * @see llvm::object::symbols()154 */155LLVM_C_ABI LLVMSymbolIteratorRef156LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR);157 158/**159 * Returns whether the given symbol iterator is at the end.160 *161 * @see llvm::object::symbol_end162 */163LLVM_C_ABI LLVMBool164LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR, LLVMSymbolIteratorRef SI);165 166LLVM_C_ABI void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI);167 168LLVM_C_ABI void LLVMMoveToNextSection(LLVMSectionIteratorRef SI);169LLVM_C_ABI void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect,170 LLVMSymbolIteratorRef Sym);171 172// ObjectFile Symbol iterators173LLVM_C_ABI void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI);174LLVM_C_ABI void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI);175 176// SectionRef accessors177LLVM_C_ABI const char *LLVMGetSectionName(LLVMSectionIteratorRef SI);178LLVM_C_ABI uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI);179LLVM_C_ABI const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI);180LLVM_C_ABI uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI);181LLVM_C_ABI LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI,182 LLVMSymbolIteratorRef Sym);183 184// Section Relocation iterators185LLVM_C_ABI LLVMRelocationIteratorRef186LLVMGetRelocations(LLVMSectionIteratorRef Section);187LLVM_C_ABI void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI);188LLVM_C_ABI LLVMBool LLVMIsRelocationIteratorAtEnd(189 LLVMSectionIteratorRef Section, LLVMRelocationIteratorRef RI);190LLVM_C_ABI void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI);191 192// SymbolRef accessors193LLVM_C_ABI const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI);194LLVM_C_ABI uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI);195LLVM_C_ABI uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI);196 197// RelocationRef accessors198LLVM_C_ABI uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI);199LLVM_C_ABI LLVMSymbolIteratorRef200LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI);201LLVM_C_ABI uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI);202// NOTE: Caller takes ownership of returned string of the two203// following functions.204LLVM_C_ABI const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI);205LLVM_C_ABI const char *206LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI);207 208/** Deprecated: Use LLVMBinaryRef instead. */209typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef;210 211/** Deprecated: Use LLVMCreateBinary instead. */212LLVM_C_ABI LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf);213 214/** Deprecated: Use LLVMDisposeBinary instead. */215LLVM_C_ABI void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile);216 217/** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */218LLVM_C_ABI LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile);219 220/** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */221LLVM_C_ABI LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile,222 LLVMSectionIteratorRef SI);223 224/** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */225LLVM_C_ABI LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile);226 227/** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */228LLVM_C_ABI LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile,229 LLVMSymbolIteratorRef SI);230/**231 * @}232 */233 234LLVM_C_EXTERN_C_END235 236#endif237