A crate for demangling C++ symbols
Clone or download
fitzgen Merge pull request #166 from rocallahan/template-params
Return error instead of stack overflow demangling invalid possibly-cy…
Latest commit bea738e Nov 5, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Fix `no-default-features = true` for non-nightly rust channels Aug 9, 2018
fuzz
in Add the AFL hanging test cases as well Feb 3, 2017
src Return error instead of stack overflow demangling invalid possibly-cy… Nov 2, 2018
tests
.coveralls.yml Add Travis CI and coveralls.io Dec 11, 2016
.gitignore Add a test against regressions on symbols from libxul Nov 14, 2017
.travis.yml
CHANGELOG.md *Actually* fix building on stable with `default-features = false` Aug 10, 2018
CONTRIBUTING.md Update AFL integration to reflect recent rewrite. Apr 29, 2018
Cargo.toml
LICENSE-APACHE Add license files Feb 24, 2017
LICENSE-MIT
README.md *Actually* fix building on stable with `default-features = false` Aug 10, 2018
build.rs Handle conversion operators correctly. Jun 5, 2018
rustfmt.toml Run rustfmt on everything Nov 14, 2017

README.md

cpp_demangle: a C++ linker symbol demangler

Build Status

This crate can parse a C++ “mangled” linker symbol name into a Rust value describing what the name refers to: a variable, a function, a virtual table, etc. The description type implements Display, producing human-readable text describing the mangled name. Debuggers and profilers can use this crate to provide more meaningful output.

C++ requires the compiler to choose names for linker symbols consistently across compilation units, so that two compilation units that have seen the same declarations can pair up definitions in one unit with references in another. Almost all platforms other than Microsoft Windows follow the Itanium C++ ABI's rules for this.

For example, suppose a C++ compilation unit has the definition:

namespace space {
  int foo(int x, int y) { return x+y; }
}

The Itanium C++ ABI specifies that the linker symbol for that function must be named _ZN5space3fooEii. This crate can parse that name into a Rust value representing its structure. Formatting the value with the format! macro or the std::string::ToString::to_string trait method yields the string space::foo(int, int), which is more meaningful to the C++ developer.

Usage

Add cpp_demangle to your crate's Cargo.toml:

[dependencies]
cpp_demangle = "0.2.12"

And then demangle some C++ symbols!

extern crate cpp_demangle;
use cpp_demangle::Symbol;
use std::string::ToString;

let mangled = b"_ZN5space3fooEibc";

let sym = Symbol::new(&mangled[..])
    .expect("Could not parse mangled symbol!");

let demangled = sym.to_string();
assert_eq!(demangled, "space::foo(int, bool, char)");

no_std Support

cpp_demangle may be configured for working in no_std environments that still have allocation support via the alloc crate. This is nightly rust only, at the moment, since the alloc crate's collections aren't stabilized.

Disable the "std" feature, and enable the "alloc" feature:

[dependencies]
cpp_demangle = {
  version = "0.2.12",
  default-features = false,
  features = ["alloc"]
}

Documentation

Documentation on docs.rs

Example programs:

  • A c++filt clone.

    Install it locally with this command:

    cargo install cpp_demangle --example cppfilt
    

Implementation Status

Work is ongoing. While cpp_demangle can parse every mangled symbol in libiberty's demangler's test suite (the canonical Itanium C++ symbol demangler used by GNU tools such as c++filt), it does not format all of them character-for-character identically. I'm working on fixing that ;)

Despite that, I believe cpp_demangle is fairly robust. I've been running AFL on cpp_demangle overnight and it hasn't found any panics for a long time now (and never found any crashes -- thanks Rust!).

License

Licensed under either of

at your option.

Contribution

See CONTRIBUTING.md for hacking.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.