contrib/llvm-project/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 } 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