Skip to content

Latest commit

 

History

History
86 lines (59 loc) · 6.65 KB

README.md

File metadata and controls

86 lines (59 loc) · 6.65 KB

Kaisa the Sharp Librarian

MIT Licensed CI Status NuGet Version Sponsor

Kaisa is a C# parser for various library files consumed by linkers. It is primarily intended to support locating where and how symbols are exported by dynamic and static libraries. However basic information about unrelated object sections is exposed for advanced users.

The following formats are currently supported:

It also supports automatic identification of such files. Including a best guess differentiation between Windows and Linux archives (which use the same-yet-different non-standardized format.)

Note that PE images (IE: .dll files) are not supported since linkers on Windows do not consume them.

License

This project is licensed under the MIT License. See the license file for details.

Archive file feature support

The parser should tolerate any library archive file, but only the following information is explicitly parsed and exposed:

  • V1 index files (AKA "first linker member")
  • V2 index files* (AKA "second linker member")
  • The longnames file
  • Import members*
  • COFF object members*
  • ELF object members** (see ELF support below for details.)
  • Unrecognized members (only exposes a data range in case you want to parse something exotic yourself)
    • "Unrecognized" is tricky due to COFF members having no magic signature. For a member to be considered unrecognized, all of the following must be true:
      • It is not recognized as an import object
      • It is not recognized as an ELF file
      • It would have an invalid COFF machine type if it were parsed as a COFF object

* Specific to Windows archives
** Specific to Linux archives

Note that the parser currently requires the symbol index file to be present. As such it cannot be used to parse non-library archive files such as .deb packages. It also does not currently understand BSD-style library archives (including those used on macOS.)

Unsupported COFF object member features

The following are explicitly not parsed or exposed for COFF objects: (Although enough information is exposed that you should be able to parse them yourself.)

  • The optional (image-only) COFF header
  • Section data
  • COFF relocations
  • COFF line numbers
  • The (image-only) attribute certificate table
  • Delay-load import only tables (image-only)

Other unsupported features

Some AR archive fields that are meaningless to the Microsoft spec (such as the UID and GID) are skipped when parsing. (They aren't particularly useful or important to linkers on Linux either, they're an artifact from archive files being a general-purpose archive format.)

ELF file feature support

The parser should tolerate any ELF file, but only the following sections are explicitly parsed and exposed:

  • General and dynamic symbols tables (SHT_SYMTAB and SHT_DYNSYM)
    • Extended index tables (SHT_SYMTAB_SHNDX) -- Not directly exposed but extended indices are automatically resolved on symbols.
  • String tables (SHT_STRTAB)
  • Basic metadata of other unrecognized sections
    • Including whether the section is a special well-known section or a non-standard operating system or processor-specific extension section.
    • Advanced users can extract the range of these sections for manual parsing if so desired.

Additionally, relevant x64-specific extensions are exposed. (Although not many actually affect the features we do expose.)

In theory 32-bit ELF files are supported, but their support is not regularly exercised. Big endian ELF files are not supported unless your app is running on a big endian platform. Developers with more advanced needs might consider evaluating LibObjectFile instead.

Unsupported ELF features

The program headers (if present) are not parsed. However, their offset and size is exposed via ElfFile.Header for advanced users who wish to parse them manually.

API Stability

This library primarily exists to support the librarian functionality in Biohazrd. Not a ton of thought went into the API, especially for things not needed by Biohazrd. As such I might tweak the API to better support these needs as they evolve. I consider this library to be pretty niche, so if you use this library in a major way consider posting a discussion or DMing me so I know to avoid breaking you.