Using the library¶
The entry points, roughly in the order you'll need them, and the command line at the end. The API reference has the full signatures.
Demangling a name¶
demangle.demangle(name) # the spelling, or `name` itself
demangle.demangle_strict(name) # raises DemanglingError instead
demangle() never raises over a name. One it can't read comes back exactly as it went
in, so you can run it over every symbol in a binary, most of which aren't mangled
anyway. It only raises when the call itself is wrong, say a language that doesn't
exist.
>>> import demangle
>>> demangle.demangle("eqdestroy___systemZassertions_23")
'system/assertions.=destroy'
>>> demangle.demangle("MYUNIT$_$TWIDGET_$__$$_AREA$$LONGINT")
'MYUNIT.TWIDGET.AREA: LONGINT'
>>> demangle.demangle("AddAlignment__9ivTSolverUiP12ivInteractorP7ivTGlue")
'ivTSolver::AddAlignment(unsigned int, ivInteractor *, ivTGlue *)'
>>> demangle.demangle("__dt__6CActorFv")
'CActor::~CActor()'
>>> demangle.demangle("example.com/m/v2%2e5.(*T).Method", language="go")
'example.com/m/v2.5.(*T).Method'
demangle_all() is the same over an iterable, yielding results in order. Both share
one result cache, and a symbol table repeats its names a lot:
>>> list(demangle.demangle_all(["_Z1fv", "main"]))
['f()', 'main']
The tree¶
parse() gives you the tree the spelling is rendered from:
>>> tree = demangle.parse("_ZNK3Foo3barIiEEvPKc")
>>> tree.spell()
'void Foo::bar<int>(char const*) const'
>>> [node.text for node in tree.find("name")]
['Foo', 'bar']
>>> function = next(tree.find("function"))
>>> len(function.parameters)
1
find() also takes a node class. That's the form a type checker can follow, since it
knows a Name has text and a Function has parameters:
>>> from demangle.core.ast import Name
>>> [name.text for name in demangle.parse("_ZNK3Foo3barIiEEvPKc").find(Name)]
['Foo', 'bar']
All schemes return full trees. A Rust symbol, for one, is a symbol holding a path
of name components:
>>> tree = demangle.parse("_ZN4core3fmt9Formatter3pad17h9b2b3a0e5b4d1b31E")
>>> [node.text for node in tree.find("name")]
['core', 'fmt', 'Formatter', 'pad']
to_dict() turns a tree into plain data (demangle --json prints it), and
node_kinds() lists the kinds a scheme can produce, so you don't have to dig them out
of the source:
>>> demangle.parse("_Z1fPi").to_dict()
{'kind': 'function', 'name': {'kind': 'name', 'text': 'f'}, 'parameters': [{'kind': 'pointer', 'inner': {'kind': 'builtin', 'spelling': 'int'}}], 'returns': None, 'suffix': ''}
>>> demangle.node_kinds("d")
('name', 'path', 'symbol')
A node that's reached more than once, like an Itanium substitution, is written once
with an id and after that as {"$ref": id}. The structure is a graph, and writing it
out in full can blow up.
The nodes also work with match; the tree's reference
has an example. Working with the tree takes one real question
through parse() from start to finish.
The parts of a name¶
signature() gives you the pieces instead of the string: the base name without its
scope, the scope on its own, the parameter types.
>>> parts = demangle.signature("_ZNSt6vectorIiSaIiEE9push_backERKi")
>>> parts.namespace, parts.base_name
('std::vector<int, std::allocator<int>>', 'push_back')
>>> parts.parameters
('int const&',)
>>> demangle.signature("$s4main3FooV3baryS2i_SStF").return_type
'Swift.Int'
namespace, the scheme's separator and base_name put back together give
qualified_name exactly. You can't get that by splitting the string, because ::,
. and , also turn up inside template arguments and operator names.
Schemes don't all record the same things, and the fields say so. A C++ or Swift name
carries a signature. A Rust or Go path doesn't, so its parameters is None, which
isn't the same as (), and is_function is False where the name doesn't say.
Errors and limits¶
demangle_strict(), parse(), signature() and the type readers raise a
DemanglingError when they can't read a name. The subclass tells you why:
>>> demangle.demangle_strict("main")
Traceback (most recent call last):
...
demangle.core.errors.NotMangledError: not a mangled name: 'main'
>>> try:
... demangle.demangle_strict("_ZN3Foo")
... except demangle.ParseError as error:
... print(error.position, error)
7 unterminated nested name at offset 7: '_ZN3Foo'
| Error | Means |
|---|---|
NotMangledError |
No scheme claims the name. |
ParseError |
The name breaks its scheme's grammar; position is where. |
TruncatedError |
A ParseError for a name that stops partway. |
LimitExceeded |
The name may be fine, but it's bigger than this call was allowed to read. |
That last one exists because a mangled name is untrusted input: a few dozen bytes can
describe a type nested deep enough to exhaust the stack.
Limits caps the depth, the output, the substitutions
and the input on every call:
>>> deep = "_Z1f" + "P" * 300 + "i"
>>> demangle.demangle(deep) == deep
True
>>> try:
... demangle.demangle_strict(deep)
... except demangle.LimitExceeded as error:
... print(error.limit_name, error.limit_value)
recursion depth 256
>>> demangle.demangle(deep, limits=demangle.RELAXED_LIMITS)[:12]
'f(int*******'
The defaults, DEFAULT_LIMITS, sit well above anything a compiler emits.
RELAXED_LIMITS is for input you trust, and every call that reads a name takes
limits=. The security policy has the reasoning.
Bare types¶
A typeinfo name, an RTTI type descriptor and a Swift metadata typeref carry a type
rather than a symbol. demangle_type() reads one and parse_type() gives its tree:
>>> demangle.demangle_type("PKFvRiE", language="itanium")
'void (*)(int&) const'
>>> demangle.demangle_type("PEAX", language="msvc")
'void *'
>>> demangle.demangle_type("SaySiG", language="swift")
'[Swift.Int]'
language is required here. A whole symbol announces its scheme with _Z, ? or
$s, but a type encoding announces nothing: Si is std::istream to the Itanium
reader and Swift.Int to the Swift one.
Text and streams¶
nm puts an address and a type letter before each name, and a crash log puts a frame
number. demangle_text() rewrites every symbol-shaped word and leaves the rest alone,
which is also what the command does with no arguments:
>>> demangle.demangle_text("0000000000001139 T _ZN3foo3barEv")
'0000000000001139 T foo::bar()'
>>> [f.mangled for f in demangle.find_symbols("a _ZN3foo3barEv b")]
['_ZN3foo3barEv']
find_symbols() also gives each symbol's span, for when you need to know where in the
line it was. demangle_stream(sys.stdin, sys.stdout) does the same a line at a time.
Choosing the scheme¶
>>> demangle.detect("?f@@YAXH@Z")
'msvc'
detect() says what a name looks like, which is cheap. detect(name, strict=True)
says which scheme actually reads it, which costs a parse.
language="msvc" forces one scheme. A sequence, language=("itanium", "swift"), is an
allow-list: detection runs as usual, but only among those.
Labelling a symbol table
shows both on a real table.
Bytes¶
A string table holds bytes, and they aren't always valid UTF-8: a truncated table can cut a name mid-character. Every single-name entry point has a bytes form, so you don't have to guess an encoding first:
>>> demangle.demangleb(b"_ZN3foo3barEv")
b'foo::bar()'
The others are demangleb_strict, detectb, parseb, signatureb, demangleb_type
and parseb_type. demangleb() hands back bytes it can't read exactly as given,
undecodable ones included; the strict forms raise.
Styles¶
llvm-cxxfilt and GNU c++filt spell some Itanium names differently, and neither is
wrong. Pick whichever you need to match:
>>> demangle.demangle("_ZNSt6vectorIiSaIiEE9push_backERKi", style="llvm") # default
'std::vector<int, std::allocator<int>>::push_back(int const&)'
>>> demangle.demangle("_ZNSt6vectorIiSaIiEE9push_backERKi", style="gnu")
'std::vector<int, std::allocator<int> >::push_back(int const&)'
style() builds a style that leaves things out. You pass it to the calls that want
it, and nothing is registered globally:
>>> demangle.demangle("?g@C@@UEAAXXZ")
'public: virtual void __cdecl C::g(void)'
>>> narrow = demangle.style("llvm", msvc={"calling_convention": False, "access_specifier": False})
>>> demangle.demangle("?g@C@@UEAAXXZ", style=narrow)
'virtual void C::g(void)'
MSVC has nine of these options, each with a command-line flag;
MsvcOptions lists them.
Swift has the short form Xcode and LLDB show: Either for Monads.Either, (_:) for
(Swift.Int) -> Swift.UInt. It's --simplified on the command line.
>>> from demangle.schemes.swift import SIMPLIFIED_OPTIONS
>>> demangle.demangle("_TtFSiSu", style=demangle.style("llvm", swift=SIMPLIFIED_OPTIONS))
'(_:)'
Start-up¶
A scheme is imported the first time a name needs it, so a script that reads one MSVC name never loads the Swift reader. That first import takes a few milliseconds (about 7 for MSVC), which a long-running service may prefer to pay before its first request:
>>> demangle.preload("itanium", "msvc") # or preload() for every scheme
Plugins¶
Another package can add a scheme through the demangle.languages entry-point group.
Installed plugins aren't loaded until you call demangle.load_plugins() (the demangle
command does), so installing something can't quietly replace a built-in scheme.
Adding a scheme shows how to write one.
The command line¶
demangle is a filter like c++filt, over any mix of schemes. python -m demangle is
the same command, for when the script isn't on PATH.
$ nm -a libfoo.so | demangle
$ demangle _ZNSt6vectorIiSaIiEE9push_backERKi
$ demangle -b _ZN3foo3barEv # `mangled ==> demangled`
$ demangle -m _ZN3foo3barEv # only the names it could read
$ demangle -s gnu _ZNSt6vectorIiSaIiEE9push_backERKi # output style: llvm or gnu
$ demangle --strip-underscore '_?f@@YAXH@Z' # ignore one leading underscore
$ printf '%s\0' "$name" | demangle -0 # names ended by NUL, in and out
Choosing the scheme:
$ demangle --detect _RNvC6_123foo3bar
$ demangle --detect --strict _ZN3Foo # the scheme that reads it, or an error
$ nm -a Foo.dylib | demangle -l itanium,swift # detect among these schemes only
$ demangle --types -l itanium PKFvRiE # a bare type, as `c++filt -t`
$ demangle --list-languages # schemes and their aliases
Changing what's printed:
$ demangle -p _ZNSt6vectorIiSaIiEE9push_backERKi # the name, without the signature
$ demangle --base-name _ZSt4sortIPiEvT_S1_ # `sort<int*>`
$ demangle --no-return-type _ZSt4sortIPiEvT_S1_ # the declaration, minus `void `
$ demangle --ret-postfix _Z1fIiET_S0_ # `f<int>(int)int`, as `DMGL_RET_POSTFIX`
$ demangle --keep-hash _ZN4core3fmt5write17h05af221e174051e9E # keep Rust's hash
$ demangle --no-calling-convention '?f@@YAXH@Z' # `void f(int)`
$ demangle --no-tag-kind '?g3@@YAXVV@@@Z' # `void __cdecl g3(V)`
$ demangle --simplified _TtFSiSu # Swift, the way Xcode shows it
The tree and JSON:
$ demangle --tree _Z1fPKc
$ demangle --json _Z1fPi # the parse tree as JSON
$ nm -a libfoo.so | demangle --json-lines # a JSON object per symbol
$ demangle --json-lines --signature _Z1fPi # ... with the parts of the name
--types takes one encoding per argument instead of filtering text, because Pi is an
ordinary word and I like Pi should stay as it is.
--json-lines writes {"mangled": ..., "demangled": ..., "language": ...} per name.
language is the scheme that read it, or null if it came back unchanged.
--signature adds the fields of signature(), all null for a name nothing reads, so
every record has the same keys. Over a stream you get one object per symbol the filter
rewrites.
A name whose bytes aren't UTF-8 gets one more key, mangled_bytes, with the bytes in
base64. mangled carries each such byte as a lone surrogate ("_Z3foo\udcff"), which
most JSON readers turn into U+FFFD. demangled_bytes does the same for the spelling
when the bytes carry through to it.
demangle -h lists the common options and demangle --help all of them. The exit
status is 0 when every name was read or printed unchanged, 1 when one was refused
(under --strict, or with no tree to print for --tree or --json), 2 for a usage
error and 130 after Ctrl-C.