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 LLVMOpaqueSectionIterator *LLVMSectionIteratorRef;
38 typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef;
39 typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef;
40 
41 typedef enum {
42   LLVMBinaryTypeArchive,                /**< Archive file. */
43   LLVMBinaryTypeMachOUniversalBinary,   /**< Mach-O Universal Binary file. */
44   LLVMBinaryTypeCOFFImportFile,         /**< COFF Import file. */
45   LLVMBinaryTypeIR,                     /**< LLVM IR. */
46   LLVMBinaryTypeWinRes,                 /**< Windows resource (.res) file. */
47   LLVMBinaryTypeCOFF,                   /**< COFF Object file. */
48   LLVMBinaryTypeELF32L,                 /**< ELF 32-bit, little endian. */
49   LLVMBinaryTypeELF32B,                 /**< ELF 32-bit, big endian. */
50   LLVMBinaryTypeELF64L,                 /**< ELF 64-bit, little endian. */
51   LLVMBinaryTypeELF64B,                 /**< ELF 64-bit, big endian. */
52   LLVMBinaryTypeMachO32L,               /**< MachO 32-bit, little endian. */
53   LLVMBinaryTypeMachO32B,               /**< MachO 32-bit, big endian. */
54   LLVMBinaryTypeMachO64L,               /**< MachO 64-bit, little endian. */
55   LLVMBinaryTypeMachO64B,               /**< MachO 64-bit, big endian. */
56   LLVMBinaryTypeWasm,                   /**< Web Assembly. */
57 } LLVMBinaryType;
58 
59 /**
60  * Create a binary file from the given memory buffer.
61  *
62  * The exact type of the binary file will be inferred automatically, and the
63  * appropriate implementation selected.  The context may be NULL except if
64  * the resulting file is an LLVM IR file.
65  *
66  * The memory buffer is not consumed by this function.  It is the responsibilty
67  * of the caller to free it with \c LLVMDisposeMemoryBuffer.
68  *
69  * If NULL is returned, the \p ErrorMessage parameter is populated with the
70  * error's description.  It is then the caller's responsibility to free this
71  * message by calling \c LLVMDisposeMessage.
72  *
73  * @see llvm::object::createBinary
74  */
75 LLVMBinaryRef LLVMCreateBinary(LLVMMemoryBufferRef MemBuf,
76                                LLVMContextRef Context,
77                                char **ErrorMessage);
78 
79 /**
80  * Dispose of a binary file.
81  *
82  * The binary file does not own its backing buffer.  It is the responsibilty
83  * of the caller to free it with \c LLVMDisposeMemoryBuffer.
84  */
85 void LLVMDisposeBinary(LLVMBinaryRef BR);
86 
87 /**
88  * Retrieves a copy of the memory buffer associated with this object file.
89  *
90  * The returned buffer is merely a shallow copy and does not own the actual
91  * backing buffer of the binary. Nevertheless, it is the responsibility of the
92  * caller to free it with \c LLVMDisposeMemoryBuffer.
93  *
94  * @see llvm::object::getMemoryBufferRef
95  */
96 LLVMMemoryBufferRef LLVMBinaryCopyMemoryBuffer(LLVMBinaryRef BR);
97 
98 /**
99  * Retrieve the specific type of a binary.
100  *
101  * @see llvm::object::Binary::getType
102  */
103 LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR);
104 
105 /*
106  * For a Mach-O universal binary file, retrieves the object file corresponding
107  * to the given architecture if it is present as a slice.
108  *
109  * If NULL is returned, the \p ErrorMessage parameter is populated with the
110  * error's description.  It is then the caller's responsibility to free this
111  * message by calling \c LLVMDisposeMessage.
112  *
113  * It is the responsiblity of the caller to free the returned object file by
114  * calling \c LLVMDisposeBinary.
115  */
116 LLVMBinaryRef LLVMMachOUniversalBinaryCopyObjectForArch(LLVMBinaryRef BR,
117                                                         const char *Arch,
118                                                         size_t ArchLen,
119                                                         char **ErrorMessage);
120 
121 /**
122  * Retrieve a copy of the section iterator for this object file.
123  *
124  * If there are no sections, the result is NULL.
125  *
126  * The returned iterator is merely a shallow copy. Nevertheless, it is
127  * the responsibility of the caller to free it with
128  * \c LLVMDisposeSectionIterator.
129  *
130  * @see llvm::object::sections()
131  */
132 LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR);
133 
134 /**
135  * Returns whether the given section iterator is at the end.
136  *
137  * @see llvm::object::section_end
138  */
139 LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR,
140                                               LLVMSectionIteratorRef SI);
141 
142 /**
143  * Retrieve a copy of the symbol iterator for this object file.
144  *
145  * If there are no symbols, the result is NULL.
146  *
147  * The returned iterator is merely a shallow copy. Nevertheless, it is
148  * the responsibility of the caller to free it with
149  * \c LLVMDisposeSymbolIterator.
150  *
151  * @see llvm::object::symbols()
152  */
153 LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR);
154 
155 /**
156  * Returns whether the given symbol iterator is at the end.
157  *
158  * @see llvm::object::symbol_end
159  */
160 LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR,
161                                              LLVMSymbolIteratorRef SI);
162 
163 void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI);
164 
165 void LLVMMoveToNextSection(LLVMSectionIteratorRef SI);
166 void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect,
167                                  LLVMSymbolIteratorRef Sym);
168 
169 // ObjectFile Symbol iterators
170 void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI);
171 void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI);
172 
173 // SectionRef accessors
174 const char *LLVMGetSectionName(LLVMSectionIteratorRef SI);
175 uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI);
176 const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI);
177 uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI);
178 LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI,
179                                  LLVMSymbolIteratorRef Sym);
180 
181 // Section Relocation iterators
182 LLVMRelocationIteratorRef LLVMGetRelocations(LLVMSectionIteratorRef Section);
183 void LLVMDisposeRelocationIterator(LLVMRelocationIteratorRef RI);
184 LLVMBool LLVMIsRelocationIteratorAtEnd(LLVMSectionIteratorRef Section,
185                                        LLVMRelocationIteratorRef RI);
186 void LLVMMoveToNextRelocation(LLVMRelocationIteratorRef RI);
187 
188 
189 // SymbolRef accessors
190 const char *LLVMGetSymbolName(LLVMSymbolIteratorRef SI);
191 uint64_t LLVMGetSymbolAddress(LLVMSymbolIteratorRef SI);
192 uint64_t LLVMGetSymbolSize(LLVMSymbolIteratorRef SI);
193 
194 // RelocationRef accessors
195 uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI);
196 LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI);
197 uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI);
198 // NOTE: Caller takes ownership of returned string of the two
199 // following functions.
200 const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI);
201 const char *LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI);
202 
203 /** Deprecated: Use LLVMBinaryRef instead. */
204 typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef;
205 
206 /** Deprecated: Use LLVMCreateBinary instead. */
207 LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf);
208 
209 /** Deprecated: Use LLVMDisposeBinary instead. */
210 void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile);
211 
212 /** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */
213 LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile);
214 
215 /** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */
216 LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile,
217                                     LLVMSectionIteratorRef SI);
218 
219 /** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */
220 LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile);
221 
222 /** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */
223 LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile,
224                                    LLVMSymbolIteratorRef SI);
225 /**
226  * @}
227  */
228 
229 #ifdef __cplusplus
230 }
231 #endif /* defined(__cplusplus) */
232 
233 #endif
234