[LLVM-C] Add Section and Symbol Iterator Accessors for Object File Binaries

[CodaFi]

Summary

This brings us to full feature parity with the old API, so I've deprecated it and updated the tests. I'll do a follow-up patch to do some more cleanup and documentation work in this header.

[whitequark]

LGTM

[CodaFi]

Correct a typo in the header

[CodaFi]

The ELF section and symbol iterators can produce error values which turn into NULL underlying data in the iterators. Propagate this out as a NULL returned iterator.

[CodaFi]

@whitequark Could you give it one more look. Had to fix a corner-case.

[whitequark]

Yup, good catch! I'll make sure to check for this in the future as well.

[CodaFi]

Thanks!

llvm/trunk/include/llvm-c/Object.h

 /**
  * @defgroup LLVMCObject Object file reading and writing
  * @ingroup LLVMC
  *
  * @{
  */
 
 // Opaque type wrappers
-typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef;
 typedef struct LLVMOpaqueSectionIterator *LLVMSectionIteratorRef;
 typedef struct LLVMOpaqueSymbolIterator *LLVMSymbolIteratorRef;
 typedef struct LLVMOpaqueRelocationIterator *LLVMRelocationIteratorRef;
 
 typedef enum {
   LLVMBinaryTypeArchive,                /**< Archive file. */
   LLVMBinaryTypeMachOUniversalBinary,   /**< Mach-O Universal Binary file. */
   LLVMBinaryTypeCOFFImportFile,         /**< COFF Import file. */

 
 /**
  * Retrieve the specific type of a binary.
  *
  * @see llvm::object::Binary::getType
  */
 LLVMBinaryType LLVMBinaryGetType(LLVMBinaryRef BR);
 
+/**
+ * Retrieve a copy of the the section iterator for this object file.
+ *
+ * If there are no sections, the result is NULL.
+ *
+ * The returned iterator is merely a shallow copy. Nevertheless, it is
+ * the responsibility of the caller to free it with
+ * \c LLVMDisposeSectionIterator.
+ *
+ * @see llvm::object::sections()
+ */
+LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR);
 
-// ObjectFile creation
-LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf);
-void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile);
+/**
+ * Returns whether the given section iterator is at the end.
+ *
+ * @see llvm::object::section_end
+ */
+LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR,
+                                              LLVMSectionIteratorRef SI);
+
+/**
+ * Retrieve a copy of the the symbol iterator for this object file.
+ *
+ * If there are no symbols, the result is NULL.
+ *
+ * The returned iterator is merely a shallow copy. Nevertheless, it is
+ * the responsibility of the caller to free it with
+ * \c LLVMDisposeSymbolIterator.
+ *
+ * @see llvm::object::symbols()
+ */
+LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR);
+
+/**
+ * Returns whether the given symbol iterator is at the end.
+ *
+ * @see llvm::object::symbol_end
+ */
+LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR,
+                                             LLVMSymbolIteratorRef SI);
 
-// ObjectFile Section iterators
-LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile);
 void LLVMDisposeSectionIterator(LLVMSectionIteratorRef SI);
-LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile,
-                                LLVMSectionIteratorRef SI);
+
 void LLVMMoveToNextSection(LLVMSectionIteratorRef SI);
 void LLVMMoveToContainingSection(LLVMSectionIteratorRef Sect,
                                  LLVMSymbolIteratorRef Sym);
 
 // ObjectFile Symbol iterators
-LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile);
 void LLVMDisposeSymbolIterator(LLVMSymbolIteratorRef SI);
-LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile,
-                                LLVMSymbolIteratorRef SI);
 void LLVMMoveToNextSymbol(LLVMSymbolIteratorRef SI);
 
 // SectionRef accessors
 const char *LLVMGetSectionName(LLVMSectionIteratorRef SI);
 uint64_t LLVMGetSectionSize(LLVMSectionIteratorRef SI);
 const char *LLVMGetSectionContents(LLVMSectionIteratorRef SI);
 uint64_t LLVMGetSectionAddress(LLVMSectionIteratorRef SI);
 LLVMBool LLVMGetSectionContainsSymbol(LLVMSectionIteratorRef SI,

 uint64_t LLVMGetRelocationOffset(LLVMRelocationIteratorRef RI);
 LLVMSymbolIteratorRef LLVMGetRelocationSymbol(LLVMRelocationIteratorRef RI);
 uint64_t LLVMGetRelocationType(LLVMRelocationIteratorRef RI);
 // NOTE: Caller takes ownership of returned string of the two
 // following functions.
 const char *LLVMGetRelocationTypeName(LLVMRelocationIteratorRef RI);
 const char *LLVMGetRelocationValueString(LLVMRelocationIteratorRef RI);
 
+/** Deprecated: Use LLVMBinaryRef instead. */
+typedef struct LLVMOpaqueObjectFile *LLVMObjectFileRef;
+
+/** Deprecated: Use LLVMCreateBinary instead. */
+LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf);
+
+/** Deprecated: Use LLVMDisposeBinary instead. */
+void LLVMDisposeObjectFile(LLVMObjectFileRef ObjectFile);
+
+/** Deprecated: Use LLVMObjectFileCopySectionIterator instead. */
+LLVMSectionIteratorRef LLVMGetSections(LLVMObjectFileRef ObjectFile);
+
+/** Deprecated: Use LLVMObjectFileIsSectionIteratorAtEnd instead. */
+LLVMBool LLVMIsSectionIteratorAtEnd(LLVMObjectFileRef ObjectFile,
+                                    LLVMSectionIteratorRef SI);
+
+/** Deprecated: Use LLVMObjectFileCopySymbolIterator instead. */
+LLVMSymbolIteratorRef LLVMGetSymbols(LLVMObjectFileRef ObjectFile);
+
+/** Deprecated: Use LLVMObjectFileIsSymbolIteratorAtEnd instead. */
+LLVMBool LLVMIsSymbolIteratorAtEnd(LLVMObjectFileRef ObjectFile,
+                                   LLVMSymbolIteratorRef SI);
 /**
  * @}
  */
 
 #ifdef __cplusplus
 }
 #endif /* defined(__cplusplus) */
 
 #endif

llvm/trunk/lib/Object/Object.cpp

static LLVMBinaryType mapBinaryTypeToLLVMBinaryType(unsigned Kind) {
       default:
         llvm_unreachable("Unknown binary kind!");
       }
     }
   };
   return BinaryTypeMapper::mapBinaryTypeToLLVMBinaryType(unwrap(BR)->getType());
 }
 
+LLVMSectionIteratorRef LLVMObjectFileCopySectionIterator(LLVMBinaryRef BR) {
+  auto OF = cast<ObjectFile>(unwrap(BR));
+  auto sections = OF->sections();
+  if (sections.begin() == sections.end())
+    return nullptr;
+  return wrap(new section_iterator(sections.begin()));
+}
+
+LLVMBool LLVMObjectFileIsSectionIteratorAtEnd(LLVMBinaryRef BR,
+                                              LLVMSectionIteratorRef SI) {
+  auto OF = cast<ObjectFile>(unwrap(BR));
+  return (*unwrap(SI) == OF->section_end()) ? 1 : 0;
+}
+
+LLVMSymbolIteratorRef LLVMObjectFileCopySymbolIterator(LLVMBinaryRef BR) {
+  auto OF = cast<ObjectFile>(unwrap(BR));
+  auto symbols = OF->symbols();
+  if (symbols.begin() == symbols.end())
+    return nullptr;
+  return wrap(new symbol_iterator(symbols.begin()));
+}
+
+LLVMBool LLVMObjectFileIsSymbolIteratorAtEnd(LLVMBinaryRef BR,
+                                             LLVMSymbolIteratorRef SI) {
+  auto OF = cast<ObjectFile>(unwrap(BR));
+  return (*unwrap(SI) == OF->symbol_end()) ? 1 : 0;
+}
+
 // ObjectFile creation
 LLVMObjectFileRef LLVMCreateObjectFile(LLVMMemoryBufferRef MemBuf) {
   std::unique_ptr<MemoryBuffer> Buf(unwrap(MemBuf));
   Expected<std::unique_ptr<ObjectFile>> ObjOrErr(
       ObjectFile::createObjectFile(Buf->getMemBufferRef()));
   std::unique_ptr<ObjectFile> Obj;
   if (!ObjOrErr) {
     // TODO: Actually report errors helpfully.

llvm/trunk/tools/llvm-c-test/object.c

 
 #include "llvm-c-test.h"
 #include "llvm-c/Object.h"
 #include <stdio.h>
 #include <stdlib.h>
 
 int llvm_object_list_sections(void) {
   LLVMMemoryBufferRef MB;
-  LLVMObjectFileRef O;
+  LLVMBinaryRef O;
   LLVMSectionIteratorRef sect;
-  char *msg = NULL;
 
-  if (LLVMCreateMemoryBufferWithSTDIN(&MB, &msg)) {
-    fprintf(stderr, "Error reading file: %s\n", msg);
+  char *outBufferErr = NULL;
+  if (LLVMCreateMemoryBufferWithSTDIN(&MB, &outBufferErr)) {
+    fprintf(stderr, "Error reading file: %s\n", outBufferErr);
+    free(outBufferErr);
     exit(1);
   }
 
-  O = LLVMCreateObjectFile(MB);
-  if (!O) {
-    fprintf(stderr, "Error reading object\n");
+  char *outBinaryErr = NULL;
+  O = LLVMCreateBinary(MB, LLVMGetGlobalContext(), &outBinaryErr);
+  if (!O || outBinaryErr) {
+    fprintf(stderr, "Error reading object: %s\n", outBinaryErr);
+    free(outBinaryErr);
     exit(1);
   }
 
-  sect = LLVMGetSections(O);
-  while (!LLVMIsSectionIteratorAtEnd(O, sect)) {
+  sect = LLVMObjectFileCopySectionIterator(O);
+  while (sect && !LLVMObjectFileIsSectionIteratorAtEnd(O, sect)) {
     printf("'%s': @0x%08" PRIx64 " +%" PRIu64 "\n", LLVMGetSectionName(sect),
            LLVMGetSectionAddress(sect), LLVMGetSectionSize(sect));
 
     LLVMMoveToNextSection(sect);
   }
 
   LLVMDisposeSectionIterator(sect);
 
-  LLVMDisposeObjectFile(O);
+  LLVMDisposeBinary(O);
+
+  LLVMDisposeMemoryBuffer(MB);
 
   return 0;
 }
 
 int llvm_object_list_symbols(void) {
   LLVMMemoryBufferRef MB;
-  LLVMObjectFileRef O;
+  LLVMBinaryRef O;
   LLVMSectionIteratorRef sect;
   LLVMSymbolIteratorRef sym;
-  char *msg = NULL;
 
-  if (LLVMCreateMemoryBufferWithSTDIN(&MB, &msg)) {
-    fprintf(stderr, "Error reading file: %s\n", msg);
+  char *outBufferErr = NULL;
+  if (LLVMCreateMemoryBufferWithSTDIN(&MB, &outBufferErr)) {
+    fprintf(stderr, "Error reading file: %s\n", outBufferErr);
+    free(outBufferErr);
     exit(1);
   }
 
-  O = LLVMCreateObjectFile(MB);
-  if (!O) {
-    fprintf(stderr, "Error reading object\n");
+  char *outBinaryErr = NULL;
+  O = LLVMCreateBinary(MB, LLVMGetGlobalContext(), &outBinaryErr);
+  if (!O || outBinaryErr) {
+    fprintf(stderr, "Error reading object: %s\n", outBinaryErr);
+    free(outBinaryErr);
     exit(1);
   }
 
-  sect = LLVMGetSections(O);
-  sym = LLVMGetSymbols(O);
-  while (!LLVMIsSymbolIteratorAtEnd(O, sym)) {
+  sect = LLVMObjectFileCopySectionIterator(O);
+  sym = LLVMObjectFileCopySymbolIterator(O);
+  while (sect && sym && !LLVMObjectFileIsSymbolIteratorAtEnd(O, sym)) {
 
     LLVMMoveToContainingSection(sect, sym);
     printf("%s @0x%08" PRIx64 " +%" PRIu64 " (%s)\n", LLVMGetSymbolName(sym),
            LLVMGetSymbolAddress(sym), LLVMGetSymbolSize(sym),
            LLVMGetSectionName(sect));
 
     LLVMMoveToNextSymbol(sym);
   }
 
   LLVMDisposeSymbolIterator(sym);
 
-  LLVMDisposeObjectFile(O);
+  LLVMDisposeBinary(O);
+
+  LLVMDisposeMemoryBuffer(MB);
 
   return 0;
 }