1 .\" The contents of this file are subject to the terms of the
   2 .\" Common Development and Distribution License (the "License").
   3 .\" You may not use this file except in compliance with the License.
   4 .\"
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   6 .\" or http://www.opensolaris.org/os/licensing.
   7 .\" See the License for the specific language governing permissions
   8 .\" and limitations under the License.
   9 .\"
  10 .\" When distributing Covered Code, include this CDDL HEADER in each
  11 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  12 .\" If applicable, add the following below this CDDL HEADER, with the
  13 .\" fields enclosed by brackets "[]" replaced with your own identifying
  14 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  15 .\"
  16 .\" Copyright 2020 Joyent, Inc.
  17 .\"
  18 .Dd February 15, 2020
  19 .Dt DEMANGLE 1
  20 .Os
  21 .Sh NAME
  22 .Nm demangle
  23 .Nd demangle symbols
  24 .Sh SYNOPSIS
  25 .Nm
  26 .Oo
  27 .Fl l
  28 .Ar lang
  29 .Oc
  30 .Op Ar symbol Ns ...
  31 .Sh DESCRIPTION
  32 The
  33 .Nm
  34 utility attempts to detect mangled symbols and transform them back into a
  35 more human friendly version of the symbol.
  36 .Pp
  37 Some languages allow the same identifier to refer to multiple things
  38 (functions, variables, etc\&.) where some additional context such as
  39 parameter types, return types, etc\&. are used to disambiguate between the
  40 symbols sharing the same name.
  41 When compiling such languages into an executable form, most binary formats
  42 do not allow for duplicate symbol names or provide a way to disambiguate
  43 between duplicate names.
  44 .Pp
  45 To solve this problem, many languages will use the additional context from
  46 the source code to transform the symbol name into a unique name.
  47 This process is called name mangling.
  48 While the resulting name is predictable, the mangled names are often difficult
  49 for humans to interpret.
  50 .Pp
  51 The
  52 .Nm
  53 utility can be invoked in one of two ways.
  54 In the first method,
  55 .Ar symbol
  56 is demangled and the result is written to standard out, one line per input
  57 .Ar symbol .
  58 If any input
  59 .Ar symbol
  60 cannot be demangled, the original value of
  61 .Ar symbol
  62 is output unchanged.
  63 In the second method,
  64 .Nm
  65 reads standard in, and whenever it encounters a potential symbol, it will
  66 attempt to replace the symbol in stdandard out with the demangled version.
  67 If the symbol cannot be demangled, it is output unchanged.
  68 .Sh OPTIONS
  69 .Bl -tag -width Fl
  70 .It Fl l Ar lang
  71 Treat all potential symbols as symbols from
  72 .Ar lang .
  73 By default,
  74 .Nm
  75 will attempt to detect the language and demangle symbols for all supported
  76 languages.
  77 Current supported values of
  78 .Ar lang
  79 are:
  80 .Bl -tag -width rust -offset indent
  81 .It c++
  82 The C++ mangling format defined by the Itanium ABI.
  83 While the mangling format was originally defined for the Itanium processor, g++
  84 and clang use this format for all their supported platforms (including x86 and
  85 SPARC).
  86 .It rust
  87 The legacy rust mangling format.
  88 .It auto
  89 Attempt to detect the language automatically (default).
  90 .El
  91 .El
  92 .Sh EXIT STATUS
  93 .Ex -std
  94 .Sh EXAMPLES
  95 .Sy Example 1
  96 Demangle symbols given as command line arguments.
  97 .Bd -literal
  98 % demangle '_ZGVN9__gnu_cxx16bitmap_allocatorIwE13_S_mem_blocksE'
  99 guard variable for __gnu_cxx::bitmap_allocator<wchar_t>::_S_mem_blocks
 100 %
 101 .Ed
 102 .Pp
 103 .Sy Example 2
 104 Demangle symbols from the output of another command.
 105 .Bd -literal
 106 % grep slice rust.c | head -1
 107     T("__ZN4core5slice89_$LT$impl$u20$core..iter..traits..IntoIterator$u20$for$u20$$RF$$u27$a$u20$$u5b$T$u5d$$GT$9into_iter17h450e234d27262170E",
 108 % grep slice rust.c | head -1 | demangle
 109     T("core::slice::<impl core::iter::traits::IntoIterator for &'a [T]>::into_iter::h450e234d27262170",
 110 %
 111 .Ed
 112 .Sh INTERFACE STABILITY
 113 The command line options are not stable.
 114 The output is uncommitted.