10b57cec5SDimitry Andric /*===-- llvm-c/Object.h - Object Lib C Iface --------------------*- C++ -*-===*/ 20b57cec5SDimitry Andric /* */ 30b57cec5SDimitry Andric /* Part of the LLVM Project, under the Apache License v2.0 with LLVM */ 40b57cec5SDimitry Andric /* Exceptions. */ 50b57cec5SDimitry Andric /* See https://llvm.org/LICENSE.txt for license information. */ 60b57cec5SDimitry Andric /* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception */ 70b57cec5SDimitry Andric /* */ 80b57cec5SDimitry Andric /*===----------------------------------------------------------------------===*/ 90b57cec5SDimitry Andric /* */ 100b57cec5SDimitry Andric /* This header declares the C interface to libLLVMObject.a, which */ 110b57cec5SDimitry Andric /* implements object file reading and writing. */ 120b57cec5SDimitry Andric /* */ 130b57cec5SDimitry Andric /* Many exotic languages can interoperate with C code but have a harder time */ 140b57cec5SDimitry Andric /* with C++ due to name mangling. So in addition to C, this interface enables */ 150b57cec5SDimitry Andric /* tools written in such languages. */ 160b57cec5SDimitry Andric /* */ 170b57cec5SDimitry Andric /*===----------------------------------------------------------------------===*/ 180b57cec5SDimitry Andric 190b57cec5SDimitry Andric #ifndef LLVM_C_OBJECT_H 200b57cec5SDimitry Andric #define LLVM_C_OBJECT_H 210b57cec5SDimitry Andric 22480093f4SDimitry Andric #include "llvm-c/ExternC.h" 230b57cec5SDimitry Andric #include "llvm-c/Types.h" 240b57cec5SDimitry Andric #include "llvm/Config/llvm-config.h" 250b57cec5SDimitry Andric 26480093f4SDimitry Andric LLVM_C_EXTERN_C_BEGIN 270b57cec5SDimitry Andric 280b57cec5SDimitry Andric /** 290b57cec5SDimitry Andric * @defgroup LLVMCObject Object file reading and writing 300b57cec5SDimitry Andric * @ingroup LLVMC 310b57cec5SDimitry Andric * 320b57cec5SDimitry Andric * @{ 330b57cec5SDimitry Andric */ 340b57cec5SDimitry Andric 350b57cec5SDimitry Andric // Opaque type wrappers 360b57cec5SDimitry Andric typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef; 370b57cec5SDimitry Andric typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef; 380b57cec5SDimitry Andric typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef; 390b57cec5SDimitry Andric 400b57cec5SDimitry Andric typedef enum { 410b57cec5SDimitry Andric LLVMBinaryTypeArchive, /**< Archive file. */ 420b57cec5SDimitry Andric LLVMBinaryTypeMachOUniversalBinary, /**< Mach-O Universal Binary file. */ 430b57cec5SDimitry Andric LLVMBinaryTypeCOFFImportFile, /**< COFF Import file. */ 440b57cec5SDimitry Andric LLVMBinaryTypeIR, /**< LLVM IR. */ 450b57cec5SDimitry Andric LLVMBinaryTypeWinRes, /**< Windows resource (.res) file. */ 460b57cec5SDimitry Andric LLVMBinaryTypeCOFF, /**< COFF Object file. */ 470b57cec5SDimitry Andric LLVMBinaryTypeELF32L, /**< ELF 32-bit, little endian. */ 480b57cec5SDimitry Andric LLVMBinaryTypeELF32B, /**< ELF 32-bit, big endian. */ 490b57cec5SDimitry Andric LLVMBinaryTypeELF64L, /**< ELF 64-bit, little endian. */ 500b57cec5SDimitry Andric LLVMBinaryTypeELF64B, /**< ELF 64-bit, big endian. */ 510b57cec5SDimitry Andric LLVMBinaryTypeMachO32L, /**< MachO 32-bit, little endian. */ 520b57cec5SDimitry Andric LLVMBinaryTypeMachO32B, /**< MachO 32-bit, big endian. */ 530b57cec5SDimitry Andric LLVMBinaryTypeMachO64L, /**< MachO 64-bit, little endian. */ 540b57cec5SDimitry Andric LLVMBinaryTypeMachO64B, /**< MachO 64-bit, big endian. */ 550b57cec5SDimitry Andric LLVMBinaryTypeWasm, /**< Web Assembly. */ 5681ad6265SDimitry Andric LLVMBinaryTypeOffload, /**< Offloading fatbinary. */ 5781ad6265SDimitry Andric 580b57cec5SDimitry Andric } LLVMBinaryType; 590b57cec5SDimitry Andric 600b57cec5SDimitry Andric /** 610b57cec5SDimitry Andric * Create a binary file from the given memory buffer. 620b57cec5SDimitry Andric * 630b57cec5SDimitry Andric * The exact type of the binary file will be inferred automatically, and the 640b57cec5SDimitry Andric * appropriate implementation selected. The context may be NULL except if 650b57cec5SDimitry Andric * the resulting file is an LLVM IR file. 660b57cec5SDimitry Andric * 670b57cec5SDimitry Andric * The memory buffer is not consumed by this function. It is the responsibilty 680b57cec5SDimitry Andric * of the caller to free it with \c LLVMDisposeMemoryBuffer. 690b57cec5SDimitry Andric * 700b57cec5SDimitry Andric * If NULL is returned, the \p ErrorMessage parameter is populated with the 710b57cec5SDimitry Andric * error's description. It is then the caller's responsibility to free this 720b57cec5SDimitry Andric * message by calling \c LLVMDisposeMessage. 730b57cec5SDimitry Andric * 740b57cec5SDimitry Andric * @see llvm::object::createBinary 750b57cec5SDimitry Andric */ 760b57cec5SDimitry Andric LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf, 770b57cec5SDimitry Andric LLVMContextRef Context, 780b57cec5SDimitry Andric char **ErrorMessage); 790b57cec5SDimitry Andric 800b57cec5SDimitry Andric /** 810b57cec5SDimitry Andric * Dispose of a binary file. 820b57cec5SDimitry Andric * 830b57cec5SDimitry Andric * The binary file does not own its backing buffer. It is the responsibilty 840b57cec5SDimitry Andric * of the caller to free it with \c LLVMDisposeMemoryBuffer. 850b57cec5SDimitry Andric */ 860b57cec5SDimitry Andric void LLVMDisposeBinary(LLVMBinaryRef BR); 870b57cec5SDimitry Andric 880b57cec5SDimitry Andric /** 890b57cec5SDimitry Andric * Retrieves a copy of the memory buffer associated with this object file. 900b57cec5SDimitry Andric * 910b57cec5SDimitry Andric * The returned buffer is merely a shallow copy and does not own the actual 920b57cec5SDimitry Andric * backing buffer of the binary. Nevertheless, it is the responsibility of the 930b57cec5SDimitry Andric * caller to free it with \c LLVMDisposeMemoryBuffer. 940b57cec5SDimitry Andric * 950b57cec5SDimitry Andric * @see llvm::object::getMemoryBufferRef 960b57cec5SDimitry Andric */ 970b57cec5SDimitry Andric LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR); 980b57cec5SDimitry Andric 990b57cec5SDimitry Andric /** 1000b57cec5SDimitry Andric * Retrieve the specific type of a binary. 1010b57cec5SDimitry Andric * 1020b57cec5SDimitry Andric * @see llvm::object::Binary::getType 1030b57cec5SDimitry Andric */ 1040b57cec5SDimitry Andric LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR); 1050b57cec5SDimitry Andric 1060b57cec5SDimitry Andric /* 1070b57cec5SDimitry Andric * For a Mach-O universal binary file, retrieves the object file corresponding 1080b57cec5SDimitry Andric * to the given architecture if it is present as a slice. 1090b57cec5SDimitry Andric * 1100b57cec5SDimitry Andric * If NULL is returned, the \p ErrorMessage parameter is populated with the 1110b57cec5SDimitry Andric * error's description. It is then the caller's responsibility to free this 1120b57cec5SDimitry Andric * message by calling \c LLVMDisposeMessage. 1130b57cec5SDimitry Andric * 1140b57cec5SDimitry Andric * It is the responsiblity of the caller to free the returned object file by 1150b57cec5SDimitry Andric * calling \c LLVMDisposeBinary. 1160b57cec5SDimitry Andric */ 1170b57cec5SDimitry Andric LLVMBinaryRef LLVMMachOUniversalBinaryCopyObjectForArch(LLVMBinaryRef BR, 1180b57cec5SDimitry Andric const char *Arch, 1190b57cec5SDimitry Andric size_t ArchLen, 1200b57cec5SDimitry Andric char **ErrorMessage); 1210b57cec5SDimitry Andric 1220b57cec5SDimitry Andric /** 1230b57cec5SDimitry Andric * Retrieve a copy of the section iterator for this object file. 1240b57cec5SDimitry Andric * 1250b57cec5SDimitry Andric * If there are no sections, the result is NULL. 1260b57cec5SDimitry Andric * 1270b57cec5SDimitry Andric * The returned iterator is merely a shallow copy. Nevertheless, it is 1280b57cec5SDimitry Andric * the responsibility of the caller to free it with 1290b57cec5SDimitry Andric * \c LLVMDisposeSectionIterator. 1300b57cec5SDimitry Andric * 1310b57cec5SDimitry Andric * @see llvm::object::sections() 1320b57cec5SDimitry Andric */ 1330b57cec5SDimitry Andric LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR); 1340b57cec5SDimitry Andric 1350b57cec5SDimitry Andric /** 1360b57cec5SDimitry Andric * Returns whether the given section iterator is at the end. 1370b57cec5SDimitry Andric * 1380b57cec5SDimitry Andric * @see llvm::object::section_end 1390b57cec5SDimitry Andric */ 1400b57cec5SDimitry Andric LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR, 1410b57cec5SDimitry Andric LLVMSectionIteratorRef SI); 1420b57cec5SDimitry Andric 1430b57cec5SDimitry Andric /** 1440b57cec5SDimitry Andric * Retrieve a copy of the symbol iterator for this object file. 1450b57cec5SDimitry Andric * 1460b57cec5SDimitry Andric * If there are no symbols, the result is NULL. 1470b57cec5SDimitry Andric * 1480b57cec5SDimitry Andric * The returned iterator is merely a shallow copy. Nevertheless, it is 1490b57cec5SDimitry Andric * the responsibility of the caller to free it with 1500b57cec5SDimitry Andric * \c LLVMDisposeSymbolIterator. 1510b57cec5SDimitry Andric * 1520b57cec5SDimitry Andric * @see llvm::object::symbols() 1530b57cec5SDimitry Andric */ 1540b57cec5SDimitry Andric LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR); 1550b57cec5SDimitry Andric 1560b57cec5SDimitry Andric /** 1570b57cec5SDimitry Andric * Returns whether the given symbol iterator is at the end. 1580b57cec5SDimitry Andric * 1590b57cec5SDimitry Andric * @see llvm::object::symbol_end 1600b57cec5SDimitry Andric */ 1610b57cec5SDimitry Andric LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR, 1620b57cec5SDimitry Andric LLVMSymbolIteratorRef SI); 1630b57cec5SDimitry Andric 1640b57cec5SDimitry Andric void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI); 1650b57cec5SDimitry Andric 1660b57cec5SDimitry Andric void LLVMMoveToNextSection(LLVMSectionIteratorRef SI); 1670b57cec5SDimitry Andric void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect, 1680b57cec5SDimitry Andric LLVMSymbolIteratorRef Sym); 1690b57cec5SDimitry Andric 1700b57cec5SDimitry Andric // ObjectFile Symbol iterators 1710b57cec5SDimitry Andric void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI); 1720b57cec5SDimitry Andric void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI); 1730b57cec5SDimitry Andric 1740b57cec5SDimitry Andric // SectionRef accessors 1750b57cec5SDimitry Andric const char *LLVMGetSectionName(LLVMSectionIteratorRef SI); 1760b57cec5SDimitry Andric uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI); 1770b57cec5SDimitry Andric const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI); 1780b57cec5SDimitry Andric uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI); 1790b57cec5SDimitry Andric LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI, 1800b57cec5SDimitry Andric LLVMSymbolIteratorRef Sym); 1810b57cec5SDimitry Andric 1820b57cec5SDimitry Andric // Section Relocation iterators 1830b57cec5SDimitry Andric LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section); 1840b57cec5SDimitry Andric void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI); 1850b57cec5SDimitry Andric LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section, 1860b57cec5SDimitry Andric LLVMRelocationIteratorRef RI); 1870b57cec5SDimitry Andric void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI); 1880b57cec5SDimitry Andric 1890b57cec5SDimitry Andric 1900b57cec5SDimitry Andric // SymbolRef accessors 1910b57cec5SDimitry Andric const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI); 1920b57cec5SDimitry Andric uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI); 1930b57cec5SDimitry Andric uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI); 1940b57cec5SDimitry Andric 1950b57cec5SDimitry Andric // RelocationRef accessors 1960b57cec5SDimitry Andric uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI); 1970b57cec5SDimitry Andric LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI); 1980b57cec5SDimitry Andric uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI); 1990b57cec5SDimitry Andric // NOTE: Caller takes ownership of returned string of the two 2000b57cec5SDimitry Andric // following functions. 2010b57cec5SDimitry Andric const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI); 2020b57cec5SDimitry Andric const char *LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI); 2030b57cec5SDimitry Andric 2040b57cec5SDimitry Andric /** Deprecated: Use LLVMBinaryRef instead. */ 2050b57cec5SDimitry Andric typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef; 2060b57cec5SDimitry Andric 2070b57cec5SDimitry Andric /** Deprecated: Use LLVMCreateBinary instead. */ 2080b57cec5SDimitry Andric LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf); 2090b57cec5SDimitry Andric 2100b57cec5SDimitry Andric /** Deprecated: Use LLVMDisposeBinary instead. */ 2110b57cec5SDimitry Andric void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile); 2120b57cec5SDimitry Andric 2130b57cec5SDimitry Andric /** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */ 2140b57cec5SDimitry Andric LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile); 2150b57cec5SDimitry Andric 2160b57cec5SDimitry Andric /** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */ 2170b57cec5SDimitry Andric LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile, 2180b57cec5SDimitry Andric LLVMSectionIteratorRef SI); 2190b57cec5SDimitry Andric 2200b57cec5SDimitry Andric /** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */ 2210b57cec5SDimitry Andric LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile); 2220b57cec5SDimitry Andric 2230b57cec5SDimitry Andric /** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */ 2240b57cec5SDimitry Andric LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile, 2250b57cec5SDimitry Andric LLVMSymbolIteratorRef SI); 2260b57cec5SDimitry Andric /** 2270b57cec5SDimitry Andric * @} 2280b57cec5SDimitry Andric */ 2290b57cec5SDimitry Andric 230480093f4SDimitry Andric LLVM_C_EXTERN_C_END 2310b57cec5SDimitry Andric 2320b57cec5SDimitry Andric #endif 233