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.
  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:: --regex
  63
  64  If specified, symbol and section names specified by other switches are treated
  65  as extended POSIX regular expression patterns.
  66
  67 .. option:: --remove-section <section>, -R
  68
  69  Remove the specified section from the output. Can be specified multiple times
  70  to remove multiple sections simultaneously.
  71
  72 .. option:: --strip-all-gnu
  73
  74  Remove all symbols, debug sections and relocations from the output. This option
  75  is equivalent to GNU :program:`strip`'s ``--strip-all`` switch.
  76
  77 .. option:: --strip-all, -S
  78
  79  For ELF objects, remove from the output all symbols and non-alloc sections not
  80  within segments, except for .gnu.warning sections and the section name table.
  81
  82  For COFF objects, remove all symbols, debug sections, and relocations from the
  83  output.
  84
  85 .. option:: --strip-debug, -g
  86
  87  Remove all debug sections from the output.
  88
  89 .. option:: --strip-symbol <symbol>, -N
  90
  91  Remove all symbols named ``<symbol>`` from the output. Can be specified
  92  multiple times to remove multiple symbols.
  93
  94 .. option:: --strip-unneeded
  95
  96  Remove from the output all local or undefined symbols that are not required by
  97  relocations. Also remove all debug sections.
  98
  99 .. option:: --version, -V
 100
 101  Display the version of the :program:`llvm-strip` executable.
 102
 103 .. option:: @<FILE>
 104
 105  Read command-line options and commands from response file `<FILE>`.
 106
 107 .. option:: --wildcard, -w
 108
 109   Allow wildcard syntax for symbol-related flags. On by default for
 110   section-related flags. Incompatible with --regex.
 111
 112   Wildcard syntax allows the following special symbols:
 113
 114   ====================== ========================= ==================
 115    Character              Meaning                   Equivalent
 116   ====================== ========================= ==================
 117   ``*``                  Any number of characters  ``.*``
 118   ``?``                  Any single character      ``.``
 119   ``\``                  Escape the next character ``\``
 120   ``[a-z]``              Character class           ``[a-z]``
 121   ``[!a-z]``, ``[^a-z]`` Negated character class   ``[^a-z]``
 122   ====================== ========================= ==================
 123
 124   Additionally, starting a wildcard with '!' will prevent a match, even if
 125   another flag matches. For example ``-w -N '*' -N '!x'`` will strip all symbols
 126   except for ``x``.
 127
 128   The order of wildcards does not matter. For example, ``-w -N '*' -N '!x'`` is
 129   the same as ``-w -N '!x' -N '*'``.
 130
 131 COFF-SPECIFIC OPTIONS
 132 ---------------------
 133
 134 The following options are implemented only for COFF objects. If used with other
 135 objects, :program:`llvm-strip` will either emit an error or silently ignore
 136 them.
 137
 138 .. option:: --only-keep-debug
 139
 140  Remove the contents of non-debug sections from the output, but keep the section
 141  headers.
 142
 143 ELF-SPECIFIC OPTIONS
 144 --------------------
 145
 146 The following options are implemented only for ELF objects. If used with other
 147 objects, :program:`llvm-strip` will either emit an error or silently ignore
 148 them.
 149
 150 .. option:: --allow-broken-links
 151
 152  Allow :program:`llvm-strip` to remove sections even if it would leave invalid
 153  section references. Any invalid sh_link fields will be set to zero.
 154
 155 .. option:: --discard-locals, -X
 156
 157  Remove local symbols starting with ".L" from the output.
 158
 159 .. option:: --keep-file-symbols
 160
 161  Keep symbols of type `STT_FILE`, even if they would otherwise be stripped.
 162
 163 .. option:: --keep-section <section>
 164
 165  When removing sections from the output, do not remove sections named
 166  ``<section>``. Can be specified multiple times to keep multiple sections.
 167
 168 .. option:: --keep-symbol <symbol>, -K
 169
 170  When removing symbols from the output, do not remove symbols named
 171  ``<symbol>``. Can be specified multiple times to keep multiple symbols.
 172
 173 .. option::  --preserve-dates, -p
 174
 175  Preserve access and modification timestamps in the output.
 176
 177 .. option:: --strip-sections
 178
 179  Remove from the output all section headers and all section data not within
 180  segments. Note that many tools will not be able to use an object without
 181  section headers.
 182
 183 EXIT STATUS
 184 -----------
 185
 186 :program:`llvm-strip` exits with a non-zero exit code if there is an error.
 187 Otherwise, it exits with code 0.
 188
 189 BUGS
 190 ----
 191
 192 To report bugs, please visit <http://llvm.org/bugs/>.
 193
 194 SEE ALSO
 195 --------
 196
 197 :manpage:`llvm-objcopy(1)`