llvm/docs/CommandGuide/llvm-strip.rst

   1 llvm-strip - object stripping tool
   2 ==================================
   3
   4 .. program:: llvm-strip
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-strip` [*options*] *inputs...*
  10
  11 DESCRIPTION
  12 -----------
  13
  14 :program:`llvm-strip` is a tool to strip sections and symbols from object files.
  15 If no other stripping or remove options are specified, :option:`--strip-all`
  16 will be enabled.
  17
  18 By default, the input files are modified in-place. If "-" is specified for the
  19 input file, the input is read from the program's standard input stream.
  20
  21 If the input is an archive, any requested operations will be applied to each
  22 archive member individually.
  23
  24 The tool is still in active development, but in most scenarios it works as a
  25 drop-in replacement for GNU's :program:`strip`.
  26
  27 GENERIC AND CROSS-PLATFORM OPTIONS
  28 ----------------------------------
  29
  30 The following options are either agnostic of the file format, or apply to
  31 multiple file formats.
  32
  33 .. option:: --disable-deterministic-archives, -U
  34
  35  Use real values for UIDs, GIDs and timestamps when updating archive member
  36  headers.
  37
  38 .. option:: --discard-all, -x
  39
  40  Remove most local symbols from the output. Different file formats may limit
  41  this to a subset of the local symbols. For example, file and section symbols in
  42  ELF objects will not be discarded. Additionally, remove all debug sections.
  43
  44 .. option::  --enable-deterministic-archives, -D
  45
  46  Enable deterministic mode when stripping archives, i.e. use 0 for archive member
  47  header UIDs, GIDs and timestamp fields. On by default.
  48
  49 .. option:: --help, -h
  50
  51  Print a summary of command line options.
  52
  53 .. option::  --no-strip-all
  54
  55  Disable :option:`--strip-all`.
  56
  57 .. option::  -o <file>
  58
  59  Write output to <file>. Multiple input files cannot be used in combination
  60  with -o.
  61
  62 .. option:: --only-keep-debug
  63
  64  Produce a debug file as the output that only preserves contents of sections
  65  useful for debugging purposes.
  66
  67  For ELF objects, this removes the contents of `SHF_ALLOC` sections that are not
  68  `SHT_NOTE` by making them `SHT_NOBITS` and shrinking the program headers where
  69  possible.
  70
  71 .. option:: --regex
  72
  73  If specified, symbol and section names specified by other switches are treated
  74  as extended POSIX regular expression patterns.
  75
  76 .. option:: --remove-section <section>, -R
  77
  78  Remove the specified section from the output. Can be specified multiple times
  79  to remove multiple sections simultaneously.
  80
  81 .. option:: --strip-all-gnu
  82
  83  Remove all symbols, debug sections and relocations from the output. This option
  84  is equivalent to GNU :program:`strip`'s ``--strip-all`` switch.
  85
  86 .. option:: --strip-all, -s
  87
  88  For ELF objects, remove from the output all symbols and non-alloc sections not
  89  within segments, except for .gnu.warning, .ARM.attribute sections and the
  90  section name table.
  91
  92  For COFF objects, remove all symbols, debug sections, and relocations from the
  93  output.
  94
  95 .. option:: --strip-debug, -d, -g, -S
  96
  97  Remove all debug sections from the output.
  98
  99 .. option:: --strip-symbol <symbol>, -N
 100
 101  Remove all symbols named ``<symbol>`` from the output. Can be specified
 102  multiple times to remove multiple symbols.
 103
 104 .. option:: --strip-unneeded
 105
 106  Remove from the output all local or undefined symbols that are not required by
 107  relocations. Also remove all debug sections.
 108
 109 .. option:: --version, -V
 110
 111  Display the version of the :program:`llvm-strip` executable.
 112
 113 .. option:: --wildcard, -w
 114
 115   Allow wildcard syntax for symbol-related flags. On by default for
 116   section-related flags. Incompatible with --regex.
 117
 118   Wildcard syntax allows the following special symbols:
 119
 120   ====================== ========================= ==================
 121    Character              Meaning                   Equivalent
 122   ====================== ========================= ==================
 123   ``*``                  Any number of characters  ``.*``
 124   ``?``                  Any single character      ``.``
 125   ``\``                  Escape the next character ``\``
 126   ``[a-z]``              Character class           ``[a-z]``
 127   ``[!a-z]``, ``[^a-z]`` Negated character class   ``[^a-z]``
 128   ====================== ========================= ==================
 129
 130   Additionally, starting a wildcard with '!' will prevent a match, even if
 131   another flag matches. For example ``-w -N '*' -N '!x'`` will strip all symbols
 132   except for ``x``.
 133
 134   The order of wildcards does not matter. For example, ``-w -N '*' -N '!x'`` is
 135   the same as ``-w -N '!x' -N '*'``.
 136
 137 .. option:: @<FILE>
 138
 139  Read command-line options and commands from response file `<FILE>`.
 140
 141 ELF-SPECIFIC OPTIONS
 142 --------------------
 143
 144 The following options are implemented only for ELF objects. If used with other
 145 objects, :program:`llvm-strip` will either emit an error or silently ignore
 146 them.
 147
 148 .. option:: --allow-broken-links
 149
 150  Allow :program:`llvm-strip` to remove sections even if it would leave invalid
 151  section references. Any invalid sh_link fields will be set to zero.
 152
 153 .. option:: --discard-locals, -X
 154
 155  Remove local symbols starting with ".L" from the output.
 156
 157 .. option:: --keep-file-symbols
 158
 159  Keep symbols of type `STT_FILE`, even if they would otherwise be stripped.
 160
 161 .. option:: --keep-section <section>
 162
 163  When removing sections from the output, do not remove sections named
 164  ``<section>``. Can be specified multiple times to keep multiple sections.
 165
 166 .. option:: --keep-symbol <symbol>, -K
 167
 168  When removing symbols from the output, do not remove symbols named
 169  ``<symbol>``. Can be specified multiple times to keep multiple symbols.
 170
 171 .. option::  --preserve-dates, -p
 172
 173  Preserve access and modification timestamps in the output.
 174
 175 .. option:: --strip-sections
 176
 177  Remove from the output all section headers and all section data not within
 178  segments. Note that many tools will not be able to use an object without
 179  section headers.
 180
 181 .. option:: -T
 182
 183  Remove Swift symbols.
 184
 185 EXIT STATUS
 186 -----------
 187
 188 :program:`llvm-strip` exits with a non-zero exit code if there is an error.
 189 Otherwise, it exits with code 0.
 190
 191 BUGS
 192 ----
 193
 194 To report bugs, please visit <https://github.com/llvm/llvm-project/labels/tools:llvm-objcopy%2Fstrip>.
 195
 196 SEE ALSO
 197 --------
 198
 199 :manpage:`llvm-objcopy(1)`