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