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