llvm/include/llvm-c/Object.h

   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   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  */
  76 LLVMBinaryRef 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  */
  86 void 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  */
  97 LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR);
  98
  99 /**
 100  * Retrieve the specific type of a binary.
 101  *
 102  * @see llvm::object::Binary::getType
 103  */
 104 LLVMBinaryType 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  */
 117 LLVMBinaryRef 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  */
 133 LLVMSectionIteratorRef 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 LLVMBool 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  */
 154 LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR);
 155
 156 /**
 157  * Returns whether the given symbol iterator is at the end.
 158  *
 159  * @see llvm::object::symbol_end
 160  */
 161 LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR,
 162                                              LLVMSymbolIteratorRef SI);
 163
 164 void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI);
 165
 166 void LLVMMoveToNextSection(LLVMSectionIteratorRef SI);
 167 void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect,
 168                                  LLVMSymbolIteratorRef Sym);
 169
 170 // ObjectFile Symbol iterators
 171 void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI);
 172 void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI);
 173
 174 // SectionRef accessors
 175 const char *LLVMGetSectionName(LLVMSectionIteratorRef SI);
 176 uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI);
 177 const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI);
 178 uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI);
 179 LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI,
 180                                  LLVMSymbolIteratorRef Sym);
 181
 182 // Section Relocation iterators
 183 LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section);
 184 void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI);
 185 LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section,
 186                                        LLVMRelocationIteratorRef RI);
 187 void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI);
 188
 189
 190 // SymbolRef accessors
 191 const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI);
 192 uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI);
 193 uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI);
 194
 195 // RelocationRef accessors
 196 uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI);
 197 LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI);
 198 uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI);
 199 // NOTE: Caller takes ownership of returned string of the two
 200 // following functions.
 201 const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI);
 202 const char *LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI);
 203
 204 /** Deprecated: Use LLVMBinaryRef instead. */
 205 typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef;
 206
 207 /** Deprecated: Use LLVMCreateBinary instead. */
 208 LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf);
 209
 210 /** Deprecated: Use LLVMDisposeBinary instead. */
 211 void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile);
 212
 213 /** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */
 214 LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile);
 215
 216 /** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */
 217 LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile,
 218                                     LLVMSectionIteratorRef SI);
 219
 220 /** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */
 221 LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile);
 222
 223 /** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */
 224 LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile,
 225                                    LLVMSymbolIteratorRef SI);
 226 /**
 227  * @}
 228  */
 229
 230 LLVM_C_EXTERN_C_END
 231
 232 #endif