diff options
Diffstat (limited to 'upstream/debian-unstable/man1/strip.1')
| -rw-r--r-- | upstream/debian-unstable/man1/strip.1 | 437 |
1 files changed, 437 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/strip.1 b/upstream/debian-unstable/man1/strip.1 new file mode 100644 index 00000000..1b011d0b --- /dev/null +++ b/upstream/debian-unstable/man1/strip.1 @@ -0,0 +1,437 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "STRIP 1" +.TH STRIP 1 2024-02-21 binutils-2.42 "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +strip \- discard symbols and other data from object files +.SH SYNOPSIS +.IX Header "SYNOPSIS" +strip [\fB\-F\fR \fIbfdname\fR |\fB\-\-target=\fR\fIbfdname\fR] + [\fB\-I\fR \fIbfdname\fR |\fB\-\-input\-target=\fR\fIbfdname\fR] + [\fB\-O\fR \fIbfdname\fR |\fB\-\-output\-target=\fR\fIbfdname\fR] + [\fB\-s\fR|\fB\-\-strip\-all\fR] + [\fB\-S\fR|\fB\-g\fR|\fB\-d\fR|\fB\-\-strip\-debug\fR] + [\fB\-\-strip\-dwo\fR] + [\fB\-K\fR \fIsymbolname\fR|\fB\-\-keep\-symbol=\fR\fIsymbolname\fR] + [\fB\-M\fR|\fB\-\-merge\-notes\fR][\fB\-\-no\-merge\-notes\fR] + [\fB\-N\fR \fIsymbolname\fR |\fB\-\-strip\-symbol=\fR\fIsymbolname\fR] + [\fB\-w\fR|\fB\-\-wildcard\fR] + [\fB\-x\fR|\fB\-\-discard\-all\fR] [\fB\-X\fR |\fB\-\-discard\-locals\fR] + [\fB\-R\fR \fIsectionname\fR |\fB\-\-remove\-section=\fR\fIsectionname\fR] + [\fB\-\-keep\-section=\fR\fIsectionpattern\fR] + [\fB\-\-remove\-relocations=\fR\fIsectionpattern\fR] + [\fB\-\-strip\-section\-headers\fR] + [\fB\-o\fR \fIfile\fR] [\fB\-p\fR|\fB\-\-preserve\-dates\fR] + [\fB\-D\fR|\fB\-\-enable\-deterministic\-archives\fR] + [\fB\-U\fR|\fB\-\-disable\-deterministic\-archives\fR] + [\fB\-\-keep\-section\-symbols\fR] + [\fB\-\-keep\-file\-symbols\fR] + [\fB\-\-only\-keep\-debug\fR] + [\fB\-v\fR |\fB\-\-verbose\fR] [\fB\-V\fR|\fB\-\-version\fR] + [\fB\-\-help\fR] [\fB\-\-info\fR] + \fIobjfile\fR... +.SH DESCRIPTION +.IX Header "DESCRIPTION" +GNU \fBstrip\fR discards all symbols from object files +\&\fIobjfile\fR. The list of object files may include archives. +At least one object file must be given. +.PP +\&\fBstrip\fR modifies the files named in its argument, +rather than writing modified copies under different names. +.SH OPTIONS +.IX Header "OPTIONS" +.IP "\fB\-F\fR \fIbfdname\fR" 4 +.IX Item "-F bfdname" +.PD 0 +.IP \fB\-\-target=\fR\fIbfdname\fR 4 +.IX Item "--target=bfdname" +.PD +Treat the original \fIobjfile\fR as a file with the object +code format \fIbfdname\fR, and rewrite it in the same format. +.IP \fB\-\-help\fR 4 +.IX Item "--help" +Show a summary of the options to \fBstrip\fR and exit. +.IP \fB\-\-info\fR 4 +.IX Item "--info" +Display a list showing all architectures and object formats available. +.IP "\fB\-I\fR \fIbfdname\fR" 4 +.IX Item "-I bfdname" +.PD 0 +.IP \fB\-\-input\-target=\fR\fIbfdname\fR 4 +.IX Item "--input-target=bfdname" +.PD +Treat the original \fIobjfile\fR as a file with the object +code format \fIbfdname\fR. +.IP "\fB\-O\fR \fIbfdname\fR" 4 +.IX Item "-O bfdname" +.PD 0 +.IP \fB\-\-output\-target=\fR\fIbfdname\fR 4 +.IX Item "--output-target=bfdname" +.PD +Replace \fIobjfile\fR with a file in the output format \fIbfdname\fR. +.IP "\fB\-R\fR \fIsectionname\fR" 4 +.IX Item "-R sectionname" +.PD 0 +.IP \fB\-\-remove\-section=\fR\fIsectionname\fR 4 +.IX Item "--remove-section=sectionname" +.PD +Remove any section named \fIsectionname\fR from the output file, in +addition to whatever sections would otherwise be removed. This +option may be given more than once. Note that using this option +inappropriately may make the output file unusable. The wildcard +character \fB*\fR may be given at the end of \fIsectionname\fR. If +so, then any section starting with \fIsectionname\fR will be removed. +.Sp +If the first character of \fIsectionpattern\fR is the exclamation +point (!) then matching sections will not be removed even if an +earlier use of \fB\-\-remove\-section\fR on the same command line +would otherwise remove it. For example: +.Sp +.Vb 1 +\& \-\-remove\-section=.text.* \-\-remove\-section=!.text.foo +.Ve +.Sp +will remove all sections matching the pattern '.text.*', but will not +remove the section '.text.foo'. +.IP \fB\-\-keep\-section=\fR\fIsectionpattern\fR 4 +.IX Item "--keep-section=sectionpattern" +When removing sections from the output file, keep sections that match +\&\fIsectionpattern\fR. +.IP \fB\-\-remove\-relocations=\fR\fIsectionpattern\fR 4 +.IX Item "--remove-relocations=sectionpattern" +Remove relocations from the output file for any section matching +\&\fIsectionpattern\fR. This option may be given more than once. Note +that using this option inappropriately may make the output file +unusable. Wildcard characters are accepted in \fIsectionpattern\fR. +For example: +.Sp +.Vb 1 +\& \-\-remove\-relocations=.text.* +.Ve +.Sp +will remove the relocations for all sections matching the patter +\&'.text.*'. +.Sp +If the first character of \fIsectionpattern\fR is the exclamation +point (!) then matching sections will not have their relocation +removed even if an earlier use of \fB\-\-remove\-relocations\fR on the +same command line would otherwise cause the relocations to be removed. +For example: +.Sp +.Vb 1 +\& \-\-remove\-relocations=.text.* \-\-remove\-relocations=!.text.foo +.Ve +.Sp +will remove all relocations for sections matching the pattern +\&'.text.*', but will not remove relocations for the section +\&'.text.foo'. +.IP \fB\-\-strip\-section\-headers\fR 4 +.IX Item "--strip-section-headers" +Strip section headers. This option is specific to ELF files. Implies +\&\fB\-\-strip\-all\fR and \fB\-\-merge\-notes\fR. +.IP \fB\-s\fR 4 +.IX Item "-s" +.PD 0 +.IP \fB\-\-strip\-all\fR 4 +.IX Item "--strip-all" +.PD +Remove all symbols. +.IP \fB\-g\fR 4 +.IX Item "-g" +.PD 0 +.IP \fB\-S\fR 4 +.IX Item "-S" +.IP \fB\-d\fR 4 +.IX Item "-d" +.IP \fB\-\-strip\-debug\fR 4 +.IX Item "--strip-debug" +.PD +Remove debugging symbols only. +.IP \fB\-\-strip\-dwo\fR 4 +.IX Item "--strip-dwo" +Remove the contents of all DWARF .dwo sections, leaving the +remaining debugging sections and all symbols intact. +See the description of this option in the \fBobjcopy\fR section +for more information. +.IP \fB\-\-strip\-unneeded\fR 4 +.IX Item "--strip-unneeded" +Remove all symbols that are not needed for relocation processing in +addition to debugging symbols and sections stripped by +\&\fB\-\-strip\-debug\fR. +.IP "\fB\-K\fR \fIsymbolname\fR" 4 +.IX Item "-K symbolname" +.PD 0 +.IP \fB\-\-keep\-symbol=\fR\fIsymbolname\fR 4 +.IX Item "--keep-symbol=symbolname" +.PD +When stripping symbols, keep symbol \fIsymbolname\fR even if it would +normally be stripped. This option may be given more than once. +.IP \fB\-M\fR 4 +.IX Item "-M" +.PD 0 +.IP \fB\-\-merge\-notes\fR 4 +.IX Item "--merge-notes" +.IP \fB\-\-no\-merge\-notes\fR 4 +.IX Item "--no-merge-notes" +.PD +For ELF files, attempt (or do not attempt) to reduce the size of any +SHT_NOTE type sections by removing duplicate notes. The default is to +attempt this reduction unless stripping debug or DWO information. +.IP "\fB\-N\fR \fIsymbolname\fR" 4 +.IX Item "-N symbolname" +.PD 0 +.IP \fB\-\-strip\-symbol=\fR\fIsymbolname\fR 4 +.IX Item "--strip-symbol=symbolname" +.PD +Remove symbol \fIsymbolname\fR from the source file. This option may be +given more than once, and may be combined with strip options other than +\&\fB\-K\fR. +.IP "\fB\-o\fR \fIfile\fR" 4 +.IX Item "-o file" +Put the stripped output in \fIfile\fR, rather than replacing the +existing file. When this argument is used, only one \fIobjfile\fR +argument may be specified. +.IP \fB\-p\fR 4 +.IX Item "-p" +.PD 0 +.IP \fB\-\-preserve\-dates\fR 4 +.IX Item "--preserve-dates" +.PD +Preserve the access and modification dates of the file. +.IP \fB\-D\fR 4 +.IX Item "-D" +.PD 0 +.IP \fB\-\-enable\-deterministic\-archives\fR 4 +.IX Item "--enable-deterministic-archives" +.PD +Operate in \fIdeterministic\fR mode. When copying archive members +and writing the archive index, use zero for UIDs, GIDs, timestamps, +and use consistent file modes for all files. +.Sp +If \fIbinutils\fR was configured with +\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default. +It can be disabled with the \fB\-U\fR option, below. +.IP \fB\-U\fR 4 +.IX Item "-U" +.PD 0 +.IP \fB\-\-disable\-deterministic\-archives\fR 4 +.IX Item "--disable-deterministic-archives" +.PD +Do \fInot\fR operate in \fIdeterministic\fR mode. This is the +inverse of the \fB\-D\fR option, above: when copying archive members +and writing the archive index, use their actual UID, GID, timestamp, +and file mode values. +.Sp +This is the default unless \fIbinutils\fR was configured with +\&\fB\-\-enable\-deterministic\-archives\fR. +.IP \fB\-w\fR 4 +.IX Item "-w" +.PD 0 +.IP \fB\-\-wildcard\fR 4 +.IX Item "--wildcard" +.PD +Permit regular expressions in \fIsymbolname\fRs used in other command +line options. The question mark (?), asterisk (*), backslash (\e) and +square brackets ([]) operators can be used anywhere in the symbol +name. If the first character of the symbol name is the exclamation +point (!) then the sense of the switch is reversed for that symbol. +For example: +.Sp +.Vb 1 +\& \-w \-K !foo \-K fo* +.Ve +.Sp +would cause strip to only keep symbols that start with the letters +"fo", but to discard the symbol "foo". +.IP \fB\-x\fR 4 +.IX Item "-x" +.PD 0 +.IP \fB\-\-discard\-all\fR 4 +.IX Item "--discard-all" +.PD +Remove non-global symbols. +.IP \fB\-X\fR 4 +.IX Item "-X" +.PD 0 +.IP \fB\-\-discard\-locals\fR 4 +.IX Item "--discard-locals" +.PD +Remove compiler-generated local symbols. +(These usually start with \fBL\fR or \fB.\fR.) +.IP \fB\-\-keep\-section\-symbols\fR 4 +.IX Item "--keep-section-symbols" +When stripping a file, perhaps with \fB\-\-strip\-debug\fR or +\&\fB\-\-strip\-unneeded\fR, retain any symbols specifying section names, +which would otherwise get stripped. +.IP \fB\-\-keep\-file\-symbols\fR 4 +.IX Item "--keep-file-symbols" +When stripping a file, perhaps with \fB\-\-strip\-debug\fR or +\&\fB\-\-strip\-unneeded\fR, retain any symbols specifying source file names, +which would otherwise get stripped. +.IP \fB\-\-only\-keep\-debug\fR 4 +.IX Item "--only-keep-debug" +Strip a file, emptying the contents of any sections that would not be +stripped by \fB\-\-strip\-debug\fR and leaving the debugging sections +intact. In ELF files, this preserves all the note sections in the +output as well. +.Sp +Note \- the section headers of the stripped sections are preserved, +including their sizes, but the contents of the section are discarded. +The section headers are preserved so that other tools can match up the +debuginfo file with the real executable, even if that executable has +been relocated to a different address space. +.Sp +The intention is that this option will be used in conjunction with +\&\fB\-\-add\-gnu\-debuglink\fR to create a two part executable. One a +stripped binary which will occupy less space in RAM and in a +distribution and the second a debugging information file which is only +needed if debugging abilities are required. The suggested procedure +to create these files is as follows: +.RS 4 +.IP "1.<Link the executable as normal. Assuming that it is called>" 4 +.IX Item "1.<Link the executable as normal. Assuming that it is called>" +\&\f(CW\*(C`foo\*(C'\fR then... +.ie n .IP "1.<Run ""objcopy \-\-only\-keep\-debug foo foo.dbg"" to>" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-only\-keep\-debug foo foo.dbg\fR to>" 4 +.IX Item "1.<Run objcopy --only-keep-debug foo foo.dbg to>" +create a file containing the debugging info. +.ie n .IP "1.<Run ""objcopy \-\-strip\-debug foo"" to create a>" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-strip\-debug foo\fR to create a>" 4 +.IX Item "1.<Run objcopy --strip-debug foo to create a>" +stripped executable. +.ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.dbg foo"">" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.dbg foo\fR>" 4 +.IX Item "1.<Run objcopy --add-gnu-debuglink=foo.dbg foo>" +to add a link to the debugging info into the stripped executable. +.RE +.RS 4 +.Sp +Note\-\-\-the choice of \f(CW\*(C`.dbg\*(C'\fR as an extension for the debug info +file is arbitrary. Also the \f(CW\*(C`\-\-only\-keep\-debug\*(C'\fR step is +optional. You could instead do this: +.IP "1.<Link the executable as normal.>" 4 +.IX Item "1.<Link the executable as normal.>" +.PD 0 +.ie n .IP "1.<Copy ""foo"" to ""foo.full"">" 4 +.el .IP "1.<Copy \f(CWfoo\fR to \f(CWfoo.full\fR>" 4 +.IX Item "1.<Copy foo to foo.full>" +.ie n .IP "1.<Run ""strip \-\-strip\-debug foo"">" 4 +.el .IP "1.<Run \f(CWstrip \-\-strip\-debug foo\fR>" 4 +.IX Item "1.<Run strip --strip-debug foo>" +.ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.full foo"">" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.full foo\fR>" 4 +.IX Item "1.<Run objcopy --add-gnu-debuglink=foo.full foo>" +.RE +.RS 4 +.PD +.Sp +i.e., the file pointed to by the \fB\-\-add\-gnu\-debuglink\fR can be the +full executable. It does not have to be a file created by the +\&\fB\-\-only\-keep\-debug\fR switch. +.Sp +Note\-\-\-this switch is only intended for use on fully linked files. It +does not make sense to use it on object files where the debugging +information may be incomplete. Besides the gnu_debuglink feature +currently only supports the presence of one filename containing +debugging information, not multiple filenames on a one-per-object-file +basis. +.RE +.IP \fB\-V\fR 4 +.IX Item "-V" +.PD 0 +.IP \fB\-\-version\fR 4 +.IX Item "--version" +.PD +Show the version number for \fBstrip\fR. +.IP \fB\-v\fR 4 +.IX Item "-v" +.PD 0 +.IP \fB\-\-verbose\fR 4 +.IX Item "--verbose" +.PD +Verbose output: list all object files modified. In the case of +archives, \fBstrip \-v\fR lists all members of the archive. +.IP \fB@\fR\fIfile\fR 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +the Info entries for \fIbinutils\fR. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 1991\-2024 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled "GNU Free Documentation License". |