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
231