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 LLVMOpaqueObjectFile *LLVMObjectFileRef;
  38 typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef;
  39 typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef;
  40 typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef;
  41
  42 /**
  43  * Create a binary file from the given memory buffer.
  44  *
  45  * The exact type of the binary file will be inferred automatically, and the
  46  * appropriate implementation selected.  The context may be NULL except if
  47  * the resulting file is an LLVM IR file.
  48  *
  49  * The memory buffer is not consumed by this function.  It is the responsibilty
  50  * of the caller to free it with \c LLVMDisposeMemoryBuffer.
  51  *
  52  * If NULL is returned, the \p ErrorMessage parameter is populated with the
  53  * error's description.  It is then the caller's responsibility to free this
  54  * message by calling \c LLVMDisposeMessage.
  55  *
  56  * @see llvm::object::createBinary
  57  */
  58 LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf,
  59                                LLVMContextRef Context,
  60                                char **ErrorMessage);
  61
  62 /**
  63  * Dispose of a binary file.
  64  *
  65  * The binary file does not own its backing buffer.  It is the responsibilty
  66  * of the caller to free it with \c LLVMDisposeMemoryBuffer.
  67  */
  68 void LLVMDisposeBinary(LLVMBinaryRef BR);
  69
  70 /**
  71  * Retrieves a copy of the memory buffer associated with this object file.
  72  *
  73  * The returned buffer is merely a shallow copy and does not own the actual
  74  * backing buffer of the binary. Nevertheless, it is the responsibility of the
  75  * caller to free it with \c LLVMDisposeMemoryBuffer.
  76  *
  77  * @see llvm::object::getMemoryBufferRef
  78  */
  79 LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR);
  80
  81 // ObjectFile creation
  82 LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf);
  83 void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile);
  84
  85 // ObjectFile Section iterators
  86 LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile);
  87 void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI);
  88 LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile,
  89                                 LLVMSectionIteratorRef SI);
  90 void LLVMMoveToNextSection(LLVMSectionIteratorRef SI);
  91 void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect,
  92                                  LLVMSymbolIteratorRef Sym);
  93
  94 // ObjectFile Symbol iterators
  95 LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile);
  96 void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI);
  97 LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile,
  98                                 LLVMSymbolIteratorRef SI);
  99 void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI);
 100
 101 // SectionRef accessors
 102 const char *LLVMGetSectionName(LLVMSectionIteratorRef SI);
 103 uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI);
 104 const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI);
 105 uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI);
 106 LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI,
 107                                  LLVMSymbolIteratorRef Sym);
 108
 109 // Section Relocation iterators
 110 LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section);
 111 void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI);
 112 LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section,
 113                                        LLVMRelocationIteratorRef RI);
 114 void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI);
 115
 116
 117 // SymbolRef accessors
 118 const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI);
 119 uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI);
 120 uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI);
 121
 122 // RelocationRef accessors
 123 uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI);
 124 LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI);
 125 uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI);
 126 // NOTE: Caller takes ownership of returned string of the two
 127 // following functions.
 128 const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI);
 129 const char *LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI);
 130
 131 /**
 132  * @}
 133  */
 134
 135 #ifdef __cplusplus
 136 }
 137 #endif /* defined(__cplusplus) */
 138
 139 #endif