include/llvm-c/Object.h

0001 /*===-- llvm-c/Object.h - Object Lib C Iface --------------------*- C++ -*-===*/
0002 /*                                                                            */
0003 /* Part of the LLVM Project, under the Apache License v2.0 with LLVM          */
0004 /* Exceptions.                                                                */
0005 /* See https://llvm.org/LICENSE.txt for license information.                  */
0006 /* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    */
0007 /*                                                                            */
0008 /*===----------------------------------------------------------------------===*/
0009 /*                                                                            */
0010 /* This header declares the C interface to libLLVMObject.a, which             */
0011 /* implements object file reading and writing.                                */
0012 /*                                                                            */
0013 /* Many exotic languages can interoperate with C code but have a harder time  */
0014 /* with C++ due to name mangling. So in addition to C, this interface enables */
0015 /* tools written in such languages.                                           */
0016 /*                                                                            */
0017 /*===----------------------------------------------------------------------===*/
0018
0019 #ifndef LLVM_C_OBJECT_H
0020 #define LLVM_C_OBJECT_H
0021
0022 #include "llvm-c/ExternC.h"
0023 #include "llvm-c/Types.h"
0024 #include "llvm/Config/llvm-config.h"
0025
0026 LLVM_C_EXTERN_C_BEGIN
0027
0028 /**
0029  * @defgroup LLVMCObject Object file reading and writing
0030  * @ingroup LLVMC
0031  *
0032  * @{
0033  */
0034
0035 // Opaque type wrappers
0036 typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef;
0037 typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef;
0038 typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef;
0039
0040 typedef enum {
0041   LLVMBinaryTypeArchive,              /**< Archive file. */
0042   LLVMBinaryTypeMachOUniversalBinary, /**< Mach-O Universal Binary file. */
0043   LLVMBinaryTypeCOFFImportFile,       /**< COFF Import file. */
0044   LLVMBinaryTypeIR,                   /**< LLVM IR. */
0045   LLVMBinaryTypeWinRes,               /**< Windows resource (.res) file. */
0046   LLVMBinaryTypeCOFF,                 /**< COFF Object file. */
0047   LLVMBinaryTypeELF32L,               /**< ELF 32-bit, little endian. */
0048   LLVMBinaryTypeELF32B,               /**< ELF 32-bit, big endian. */
0049   LLVMBinaryTypeELF64L,               /**< ELF 64-bit, little endian. */
0050   LLVMBinaryTypeELF64B,               /**< ELF 64-bit, big endian. */
0051   LLVMBinaryTypeMachO32L,             /**< MachO 32-bit, little endian. */
0052   LLVMBinaryTypeMachO32B,             /**< MachO 32-bit, big endian. */
0053   LLVMBinaryTypeMachO64L,             /**< MachO 64-bit, little endian. */
0054   LLVMBinaryTypeMachO64B,             /**< MachO 64-bit, big endian. */
0055   LLVMBinaryTypeWasm,                 /**< Web Assembly. */
0056   LLVMBinaryTypeOffload,              /**< Offloading fatbinary. */
0057
0058 } LLVMBinaryType;
0059
0060 /**
0061  * Create a binary file from the given memory buffer.
0062  *
0063  * The exact type of the binary file will be inferred automatically, and the
0064  * appropriate implementation selected.  The context may be NULL except if
0065  * the resulting file is an LLVM IR file.
0066  *
0067  * The memory buffer is not consumed by this function.  It is the responsibilty
0068  * of the caller to free it with \c LLVMDisposeMemoryBuffer.
0069  *
0070  * If NULL is returned, the \p ErrorMessage parameter is populated with the
0071  * error's description.  It is then the caller's responsibility to free this
0072  * message by calling \c LLVMDisposeMessage.
0073  *
0074  * @see llvm::object::createBinary
0075  */
0076 LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf,
0077                                LLVMContextRef Context,
0078                                char **ErrorMessage);
0079
0080 /**
0081  * Dispose of a binary file.
0082  *
0083  * The binary file does not own its backing buffer.  It is the responsibilty
0084  * of the caller to free it with \c LLVMDisposeMemoryBuffer.
0085  */
0086 void LLVMDisposeBinary(LLVMBinaryRef BR);
0087
0088 /**
0089  * Retrieves a copy of the memory buffer associated with this object file.
0090  *
0091  * The returned buffer is merely a shallow copy and does not own the actual
0092  * backing buffer of the binary. Nevertheless, it is the responsibility of the
0093  * caller to free it with \c LLVMDisposeMemoryBuffer.
0094  *
0095  * @see llvm::object::getMemoryBufferRef
0096  */
0097 LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR);
0098
0099 /**
0100  * Retrieve the specific type of a binary.
0101  *
0102  * @see llvm::object::Binary::getType
0103  */
0104 LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR);
0105
0106 /*
0107  * For a Mach-O universal binary file, retrieves the object file corresponding
0108  * to the given architecture if it is present as a slice.
0109  *
0110  * If NULL is returned, the \p ErrorMessage parameter is populated with the
0111  * error's description.  It is then the caller's responsibility to free this
0112  * message by calling \c LLVMDisposeMessage.
0113  *
0114  * It is the responsiblity of the caller to free the returned object file by
0115  * calling \c LLVMDisposeBinary.
0116  */
0117 LLVMBinaryRef LLVMMachOUniversalBinaryCopyObjectForArch(LLVMBinaryRef BR,
0118                                                         const char *Arch,
0119                                                         size_t ArchLen,
0120                                                         char **ErrorMessage);
0121
0122 /**
0123  * Retrieve a copy of the section iterator for this object file.
0124  *
0125  * If there are no sections, the result is NULL.
0126  *
0127  * The returned iterator is merely a shallow copy. Nevertheless, it is
0128  * the responsibility of the caller to free it with
0129  * \c LLVMDisposeSectionIterator.
0130  *
0131  * @see llvm::object::sections()
0132  */
0133 LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR);
0134
0135 /**
0136  * Returns whether the given section iterator is at the end.
0137  *
0138  * @see llvm::object::section_end
0139  */
0140 LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR,
0141                                               LLVMSectionIteratorRef SI);
0142
0143 /**
0144  * Retrieve a copy of the symbol iterator for this object file.
0145  *
0146  * If there are no symbols, the result is NULL.
0147  *
0148  * The returned iterator is merely a shallow copy. Nevertheless, it is
0149  * the responsibility of the caller to free it with
0150  * \c LLVMDisposeSymbolIterator.
0151  *
0152  * @see llvm::object::symbols()
0153  */
0154 LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR);
0155
0156 /**
0157  * Returns whether the given symbol iterator is at the end.
0158  *
0159  * @see llvm::object::symbol_end
0160  */
0161 LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR,
0162                                              LLVMSymbolIteratorRef SI);
0163
0164 void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI);
0165
0166 void LLVMMoveToNextSection(LLVMSectionIteratorRef SI);
0167 void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect,
0168                                  LLVMSymbolIteratorRef Sym);
0169
0170 // ObjectFile Symbol iterators
0171 void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI);
0172 void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI);
0173
0174 // SectionRef accessors
0175 const char *LLVMGetSectionName(LLVMSectionIteratorRef SI);
0176 uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI);
0177 const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI);
0178 uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI);
0179 LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI,
0180                                  LLVMSymbolIteratorRef Sym);
0181
0182 // Section Relocation iterators
0183 LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section);
0184 void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI);
0185 LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section,
0186                                        LLVMRelocationIteratorRef RI);
0187 void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI);
0188
0189
0190 // SymbolRef accessors
0191 const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI);
0192 uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI);
0193 uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI);
0194
0195 // RelocationRef accessors
0196 uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI);
0197 LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI);
0198 uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI);
0199 // NOTE: Caller takes ownership of returned string of the two
0200 // following functions.
0201 const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI);
0202 const char *LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI);
0203
0204 /** Deprecated: Use LLVMBinaryRef instead. */
0205 typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef;
0206
0207 /** Deprecated: Use LLVMCreateBinary instead. */
0208 LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf);
0209
0210 /** Deprecated: Use LLVMDisposeBinary instead. */
0211 void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile);
0212
0213 /** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */
0214 LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile);
0215
0216 /** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */
0217 LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile,
0218                                     LLVMSectionIteratorRef SI);
0219
0220 /** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */
0221 LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile);
0222
0223 /** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */
0224 LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile,
0225                                    LLVMSymbolIteratorRef SI);
0226 /**
0227  * @}
0228  */
0229
0230 LLVM_C_EXTERN_C_END
0231
0232 #endif