1508 lines
52 KiB
HTML
1508 lines
52 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of OBJCOPY</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>OBJCOPY</H1>
|
|
Section: GNU Development Tools (1)<BR>Updated: 2021-01-21<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
objcopy - copy and translate object files
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
objcopy [<B>-F</B> <I>bfdname</I>|<B>--target=</B><I>bfdname</I>]
|
|
<BR> [<B>-I</B> <I>bfdname</I>|<B>--input-target=</B><I>bfdname</I>]
|
|
<BR> [<B>-O</B> <I>bfdname</I>|<B>--output-target=</B><I>bfdname</I>]
|
|
<BR> [<B>-B</B> <I>bfdarch</I>|<B>--binary-architecture=</B><I>bfdarch</I>]
|
|
<BR> [<B>-S</B>|<B>--strip-all</B>]
|
|
<BR> [<B>-g</B>|<B>--strip-debug</B>]
|
|
<BR> [<B>--strip-unneeded</B>]
|
|
<BR> [<B>-K</B> <I>symbolname</I>|<B>--keep-symbol=</B><I>symbolname</I>]
|
|
<BR> [<B>-N</B> <I>symbolname</I>|<B>--strip-symbol=</B><I>symbolname</I>]
|
|
<BR> [<B>--strip-unneeded-symbol=</B><I>symbolname</I>]
|
|
<BR> [<B>-G</B> <I>symbolname</I>|<B>--keep-global-symbol=</B><I>symbolname</I>]
|
|
<BR> [<B>--localize-hidden</B>]
|
|
<BR> [<B>-L</B> <I>symbolname</I>|<B>--localize-symbol=</B><I>symbolname</I>]
|
|
<BR> [<B>--globalize-symbol=</B><I>symbolname</I>]
|
|
<BR> [<B>--globalize-symbols=</B><I>filename</I>]
|
|
<BR> [<B>-W</B> <I>symbolname</I>|<B>--weaken-symbol=</B><I>symbolname</I>]
|
|
<BR> [<B>-w</B>|<B>--wildcard</B>]
|
|
<BR> [<B>-x</B>|<B>--discard-all</B>]
|
|
<BR> [<B>-X</B>|<B>--discard-locals</B>]
|
|
<BR> [<B>-b</B> <I>byte</I>|<B>--byte=</B><I>byte</I>]
|
|
<BR> [<B>-i</B> [<I>breadth</I>]|<B>--interleave</B>[=<I>breadth</I>]]
|
|
<BR> [<B>--interleave-width=</B><I>width</I>]
|
|
<BR> [<B>-j</B> <I>sectionpattern</I>|<B>--only-section=</B><I>sectionpattern</I>]
|
|
<BR> [<B>-R</B> <I>sectionpattern</I>|<B>--remove-section=</B><I>sectionpattern</I>]
|
|
<BR> [<B>--keep-section=</B><I>sectionpattern</I>]
|
|
<BR> [<B>--remove-relocations=</B><I>sectionpattern</I>]
|
|
<BR> [<B>-p</B>|<B>--preserve-dates</B>]
|
|
<BR> [<B>-D</B>|<B>--enable-deterministic-archives</B>]
|
|
<BR> [<B>-U</B>|<B>--disable-deterministic-archives</B>]
|
|
<BR> [<B>--debugging</B>]
|
|
<BR> [<B>--gap-fill=</B><I>val</I>]
|
|
<BR> [<B>--pad-to=</B><I>address</I>]
|
|
<BR> [<B>--set-start=</B><I>val</I>]
|
|
<BR> [<B>--adjust-start=</B><I>incr</I>]
|
|
<BR> [<B>--change-addresses=</B><I>incr</I>]
|
|
<BR> [<B>--change-section-address</B> <I>sectionpattern</I>{=,+,-}<I>val</I>]
|
|
<BR> [<B>--change-section-lma</B> <I>sectionpattern</I>{=,+,-}<I>val</I>]
|
|
<BR> [<B>--change-section-vma</B> <I>sectionpattern</I>{=,+,-}<I>val</I>]
|
|
<BR> [<B>--change-warnings</B>] [<B>--no-change-warnings</B>]
|
|
<BR> [<B>--set-section-flags</B> <I>sectionpattern</I>=<I>flags</I>]
|
|
<BR> [<B>--set-section-alignment</B> <I>sectionpattern</I>=<I>align</I>]
|
|
<BR> [<B>--add-section</B> <I>sectionname</I>=<I>filename</I>]
|
|
<BR> [<B>--dump-section</B> <I>sectionname</I>=<I>filename</I>]
|
|
<BR> [<B>--update-section</B> <I>sectionname</I>=<I>filename</I>]
|
|
<BR> [<B>--rename-section</B> <I>oldname</I>=<I>newname</I>[,<I>flags</I>]]
|
|
<BR> [<B>--long-section-names</B> {enable,disable,keep}]
|
|
<BR> [<B>--change-leading-char</B>] [<B>--remove-leading-char</B>]
|
|
<BR> [<B>--reverse-bytes=</B><I>num</I>]
|
|
<BR> [<B>--srec-len=</B><I>ival</I>] [<B>--srec-forceS3</B>]
|
|
<BR> [<B>--redefine-sym</B> <I>old</I>=<I>new</I>]
|
|
<BR> [<B>--redefine-syms=</B><I>filename</I>]
|
|
<BR> [<B>--weaken</B>]
|
|
<BR> [<B>--keep-symbols=</B><I>filename</I>]
|
|
<BR> [<B>--strip-symbols=</B><I>filename</I>]
|
|
<BR> [<B>--strip-unneeded-symbols=</B><I>filename</I>]
|
|
<BR> [<B>--keep-global-symbols=</B><I>filename</I>]
|
|
<BR> [<B>--localize-symbols=</B><I>filename</I>]
|
|
<BR> [<B>--weaken-symbols=</B><I>filename</I>]
|
|
<BR> [<B>--add-symbol</B> <I>name</I>=[<I>section</I>:]<I>value</I>[,<I>flags</I>]]
|
|
<BR> [<B>--alt-machine-code=</B><I>index</I>]
|
|
<BR> [<B>--prefix-symbols=</B><I>string</I>]
|
|
<BR> [<B>--prefix-sections=</B><I>string</I>]
|
|
<BR> [<B>--prefix-alloc-sections=</B><I>string</I>]
|
|
<BR> [<B>--add-gnu-debuglink=</B><I>path-to-file</I>]
|
|
<BR> [<B>--keep-file-symbols</B>]
|
|
<BR> [<B>--only-keep-debug</B>]
|
|
<BR> [<B>--strip-dwo</B>]
|
|
<BR> [<B>--extract-dwo</B>]
|
|
<BR> [<B>--extract-symbol</B>]
|
|
<BR> [<B>--writable-text</B>]
|
|
<BR> [<B>--readonly-text</B>]
|
|
<BR> [<B>--pure</B>]
|
|
<BR> [<B>--impure</B>]
|
|
<BR> [<B>--file-alignment=</B><I>num</I>]
|
|
<BR> [<B>--heap=</B><I>size</I>]
|
|
<BR> [<B>--image-base=</B><I>address</I>]
|
|
<BR> [<B>--section-alignment=</B><I>num</I>]
|
|
<BR> [<B>--stack=</B><I>size</I>]
|
|
<BR> [<B>--subsystem=</B><I>which</I>:<I>major</I>.<I>minor</I>]
|
|
<BR> [<B>--compress-debug-sections</B>]
|
|
<BR> [<B>--decompress-debug-sections</B>]
|
|
<BR> [<B>--elf-stt-common=</B><I>val</I>]
|
|
<BR> [<B>--merge-notes</B>]
|
|
<BR> [<B>--no-merge-notes</B>]
|
|
<BR> [<B>--verilog-data-width=</B><I>val</I>]
|
|
<BR> [<B>-v</B>|<B>--verbose</B>]
|
|
<BR> [<B>-V</B>|<B>--version</B>]
|
|
<BR> [<B>--help</B>] [<B>--info</B>]
|
|
<BR> <I>infile</I> [<I>outfile</I>]
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
The <FONT SIZE="-1">GNU</FONT> <B>objcopy</B> utility copies the contents of an object
|
|
file to another. <B>objcopy</B> uses the <FONT SIZE="-1">GNU BFD</FONT> Library to
|
|
read and write the object files. It can write the destination object
|
|
file in a format different from that of the source object file. The
|
|
exact behavior of <B>objcopy</B> is controlled by command-line options.
|
|
Note that <B>objcopy</B> should be able to copy a fully linked file
|
|
between any two formats. However, copying a relocatable object file
|
|
between any two formats may not work as expected.
|
|
<P>
|
|
|
|
<B>objcopy</B> creates temporary files to do its translations and
|
|
deletes them afterward. <B>objcopy</B> uses <FONT SIZE="-1">BFD</FONT> to do all its
|
|
translation work; it has access to all the formats described in <FONT SIZE="-1">BFD</FONT>
|
|
and thus is able to recognize most formats without being told
|
|
explicitly.
|
|
<P>
|
|
|
|
<B>objcopy</B> can be used to generate S-records by using an output
|
|
target of <B>srec</B> (e.g., use <B>-O srec</B>).
|
|
<P>
|
|
|
|
<B>objcopy</B> can be used to generate a raw binary file by using an
|
|
output target of <B>binary</B> (e.g., use <B>-O binary</B>). When
|
|
<B>objcopy</B> generates a raw binary file, it will essentially produce
|
|
a memory dump of the contents of the input object file. All symbols and
|
|
relocation information will be discarded. The memory dump will start at
|
|
the load address of the lowest section copied into the output file.
|
|
<P>
|
|
|
|
When generating an S-record or a raw binary file, it may be helpful to
|
|
use <B>-S</B> to remove sections containing debugging information. In
|
|
some cases <B>-R</B> will be useful to remove sections which contain
|
|
information that is not needed by the binary file.
|
|
<P>
|
|
|
|
Note---<B>objcopy</B> is not able to change the endianness of its input
|
|
files. If the input format has an endianness (some formats do not),
|
|
<B>objcopy</B> can only copy the inputs into file formats that have the
|
|
same endianness or which have no endianness (e.g., <B>srec</B>).
|
|
(However, see the <B>--reverse-bytes</B> option.)
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><I>infile</I><DD>
|
|
|
|
|
|
|
|
<DT id="2"><I>outfile</I><DD>
|
|
|
|
|
|
|
|
The input and output files, respectively.
|
|
If you do not specify <I>outfile</I>, <B>objcopy</B> creates a
|
|
temporary file and destructively renames the result with
|
|
the name of <I>infile</I>.
|
|
<DT id="3"><B>-I</B> <I>bfdname</I><DD>
|
|
|
|
|
|
|
|
<DT id="4"><B>--input-target=</B><I>bfdname</I><DD>
|
|
|
|
|
|
|
|
Consider the source file's object format to be <I>bfdname</I>, rather than
|
|
attempting to deduce it.
|
|
<DT id="5"><B>-O</B> <I>bfdname</I><DD>
|
|
|
|
|
|
|
|
<DT id="6"><B>--output-target=</B><I>bfdname</I><DD>
|
|
|
|
|
|
|
|
Write the output file using the object format <I>bfdname</I>.
|
|
<DT id="7"><B>-F</B> <I>bfdname</I><DD>
|
|
|
|
|
|
|
|
<DT id="8"><B>--target=</B><I>bfdname</I><DD>
|
|
|
|
|
|
|
|
Use <I>bfdname</I> as the object format for both the input and the output
|
|
file; i.e., simply transfer data from source to destination with no
|
|
translation.
|
|
<DT id="9"><B>-B</B> <I>bfdarch</I><DD>
|
|
|
|
|
|
|
|
<DT id="10"><B>--binary-architecture=</B><I>bfdarch</I><DD>
|
|
|
|
|
|
|
|
Useful when transforming a architecture-less input file into an object file.
|
|
In this case the output architecture can be set to <I>bfdarch</I>. This
|
|
option will be ignored if the input file has a known <I>bfdarch</I>. You
|
|
can access this binary data inside a program by referencing the special
|
|
symbols that are created by the conversion process. These symbols are
|
|
called _binary_<I>objfile</I>_start, _binary_<I>objfile</I>_end and
|
|
_binary_<I>objfile</I>_size. e.g. you can transform a picture file into
|
|
an object file and then access it in your code using these symbols.
|
|
<DT id="11"><B>-j</B> <I>sectionpattern</I><DD>
|
|
|
|
|
|
|
|
<DT id="12"><B>--only-section=</B><I>sectionpattern</I><DD>
|
|
|
|
|
|
|
|
Copy only the indicated sections from the input file to the output file.
|
|
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 <I>sectionpattern</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the first character of <I>sectionpattern</I> is the exclamation
|
|
point (!) then matching sections will not be copied, even if earlier
|
|
use of <B>--only-section</B> on the same command line would
|
|
otherwise copy it. For example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
--only-section=.text.* --only-section=!.text.foo
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
will copy all sectinos maching '.text.*' but not the section
|
|
'.text.foo'.
|
|
<DT id="13"><B>-R</B> <I>sectionpattern</I><DD>
|
|
|
|
|
|
|
|
<DT id="14"><B>--remove-section=</B><I>sectionpattern</I><DD>
|
|
|
|
|
|
|
|
Remove any section matching <I>sectionpattern</I> from the output file.
|
|
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 <I>sectionpattern</I>. Using both the
|
|
<B>-j</B> and <B>-R</B> options together results in undefined
|
|
behaviour.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the first character of <I>sectionpattern</I> is the exclamation
|
|
point (!) then matching sections will not be removed even if an
|
|
earlier use of <B>--remove-section</B> on the same command line
|
|
would otherwise remove it. For example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
--remove-section=.text.* --remove-section=!.text.foo
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
will remove all sections matching the pattern '.text.*', but will not
|
|
remove the section '.text.foo'.
|
|
<DT id="15"><B>--keep-section=</B><I>sectionpattern</I><DD>
|
|
|
|
|
|
When removing sections from the output file, keep sections that match
|
|
<I>sectionpattern</I>.
|
|
<DT id="16"><B>--remove-relocations=</B><I>sectionpattern</I><DD>
|
|
|
|
|
|
Remove non-dynamic relocations from the output file for any section
|
|
matching <I>sectionpattern</I>. This option may be given more than
|
|
once. Note that using this option inappropriately may make the output
|
|
file unusable, and attempting to remove a dynamic relocation section
|
|
such as <B>.rela.plt</B> from an executable or shared library with
|
|
<B>--remove-relocations=.plt</B> will not work. Wildcard characters
|
|
are accepted in <I>sectionpattern</I>.
|
|
For example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
--remove-relocations=.text.*
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
will remove the relocations for all sections matching the pattern
|
|
'.text.*'.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the first character of <I>sectionpattern</I> is the exclamation
|
|
point (!) then matching sections will not have their relocation
|
|
removed even if an earlier use of <B>--remove-relocations</B> on the
|
|
same command line would otherwise cause the relocations to be removed.
|
|
For example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
--remove-relocations=.text.* --remove-relocations=!.text.foo
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
will remove all relocations for sections matching the pattern
|
|
'.text.*', but will not remove relocations for the section
|
|
'.text.foo'.
|
|
<DT id="17"><B>-S</B><DD>
|
|
|
|
|
|
|
|
<DT id="18"><B>--strip-all</B><DD>
|
|
|
|
|
|
|
|
Do not copy relocation and symbol information from the source file.
|
|
<DT id="19"><B>-g</B><DD>
|
|
|
|
|
|
|
|
<DT id="20"><B>--strip-debug</B><DD>
|
|
|
|
|
|
|
|
Do not copy debugging symbols or sections from the source file.
|
|
<DT id="21"><B>--strip-unneeded</B><DD>
|
|
|
|
|
|
Strip all symbols that are not needed for relocation processing.
|
|
<DT id="22"><B>-K</B> <I>symbolname</I><DD>
|
|
|
|
|
|
|
|
<DT id="23"><B>--keep-symbol=</B><I>symbolname</I><DD>
|
|
|
|
|
|
|
|
When stripping symbols, keep symbol <I>symbolname</I> even if it would
|
|
normally be stripped. This option may be given more than once.
|
|
<DT id="24"><B>-N</B> <I>symbolname</I><DD>
|
|
|
|
|
|
|
|
<DT id="25"><B>--strip-symbol=</B><I>symbolname</I><DD>
|
|
|
|
|
|
|
|
Do not copy symbol <I>symbolname</I> from the source file. This option
|
|
may be given more than once.
|
|
<DT id="26"><B>--strip-unneeded-symbol=</B><I>symbolname</I><DD>
|
|
|
|
|
|
Do not copy symbol <I>symbolname</I> from the source file unless it is needed
|
|
by a relocation. This option may be given more than once.
|
|
<DT id="27"><B>-G</B> <I>symbolname</I><DD>
|
|
|
|
|
|
|
|
<DT id="28"><B>--keep-global-symbol=</B><I>symbolname</I><DD>
|
|
|
|
|
|
|
|
Keep only symbol <I>symbolname</I> global. Make all other symbols local
|
|
to the file, so that they are not visible externally. This option may
|
|
be given more than once. Note: this option cannot be used in
|
|
conjunction with the <B>--globalize-symbol</B> or
|
|
<B>--globalize-symbols</B> options.
|
|
<DT id="29"><B>--localize-hidden</B><DD>
|
|
|
|
|
|
In an <FONT SIZE="-1">ELF</FONT> object, mark all symbols that have hidden or internal visibility
|
|
as local. This option applies on top of symbol-specific localization options
|
|
such as <B>-L</B>.
|
|
<DT id="30"><B>-L</B> <I>symbolname</I><DD>
|
|
|
|
|
|
|
|
<DT id="31"><B>--localize-symbol=</B><I>symbolname</I><DD>
|
|
|
|
|
|
|
|
Convert a global or weak symbol called <I>symbolname</I> into a local
|
|
symbol, so that it is not visible externally. This option may be
|
|
given more than once. Note - unique symbols are not converted.
|
|
<DT id="32"><B>-W</B> <I>symbolname</I><DD>
|
|
|
|
|
|
|
|
<DT id="33"><B>--weaken-symbol=</B><I>symbolname</I><DD>
|
|
|
|
|
|
|
|
Make symbol <I>symbolname</I> weak. This option may be given more than once.
|
|
<DT id="34"><B>--globalize-symbol=</B><I>symbolname</I><DD>
|
|
|
|
|
|
Give symbol <I>symbolname</I> global scoping so that it is visible
|
|
outside of the file in which it is defined. This option may be given
|
|
more than once. Note: this option cannot be used in conjunction with
|
|
the <B>-G</B> or <B>--keep-global-symbol</B> options.
|
|
<DT id="35"><B>-w</B><DD>
|
|
|
|
|
|
|
|
<DT id="36"><B>--wildcard</B><DD>
|
|
|
|
|
|
|
|
Permit regular expressions in <I>symbolname</I>s used in other command
|
|
line options. The question mark (?), asterisk (*), backslash (\) 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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
-w -W !foo -W fo*
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
would cause objcopy to weaken all symbols that start with ``fo''
|
|
except for the symbol ``foo''.
|
|
<DT id="37"><B>-x</B><DD>
|
|
|
|
|
|
|
|
<DT id="38"><B>--discard-all</B><DD>
|
|
|
|
|
|
|
|
Do not copy non-global symbols from the source file.
|
|
<DT id="39"><B>-X</B><DD>
|
|
|
|
|
|
|
|
<DT id="40"><B>--discard-locals</B><DD>
|
|
|
|
|
|
|
|
Do not copy compiler-generated local symbols.
|
|
(These usually start with <B>L</B> or <B>.</B>.)
|
|
<DT id="41"><B>-b</B> <I>byte</I><DD>
|
|
|
|
|
|
|
|
<DT id="42"><B>--byte=</B><I>byte</I><DD>
|
|
|
|
|
|
|
|
If interleaving has been enabled via the <B>--interleave</B> option
|
|
then start the range of bytes to keep at the <I>byte</I>th byte.
|
|
<I>byte</I> can be in the range from 0 to <I>breadth</I>-1, where
|
|
<I>breadth</I> is the value given by the <B>--interleave</B> option.
|
|
<DT id="43"><B>-i [</B><I>breadth</I><B>]</B><DD>
|
|
|
|
|
|
|
|
<DT id="44"><B>--interleave[=</B><I>breadth</I><B>]</B><DD>
|
|
|
|
|
|
|
|
Only copy a range out of every <I>breadth</I> bytes. (Header data is
|
|
not affected). Select which byte in the range begins the copy with
|
|
the <B>--byte</B> option. Select the width of the range with the
|
|
<B>--interleave-width</B> option.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option is useful for creating files to program <FONT SIZE="-1">ROM.</FONT> It is
|
|
typically used with an <TT>"srec"</TT> output target. Note that
|
|
<B>objcopy</B> will complain if you do not specify the
|
|
<B>--byte</B> option as well.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default interleave breadth is 4, so with <B>--byte</B> set to 0,
|
|
<B>objcopy</B> would copy the first byte out of every four bytes
|
|
from the input to the output.
|
|
<DT id="45"><B>--interleave-width=</B><I>width</I><DD>
|
|
|
|
|
|
When used with the <B>--interleave</B> option, copy <I>width</I>
|
|
bytes at a time. The start of the range of bytes to be copied is set
|
|
by the <B>--byte</B> option, and the extent of the range is set with
|
|
the <B>--interleave</B> option.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default value for this option is 1. The value of <I>width</I> plus
|
|
the <I>byte</I> value set by the <B>--byte</B> option must not exceed
|
|
the interleave breadth set by the <B>--interleave</B> option.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option can be used to create images for two 16-bit flashes interleaved
|
|
in a 32-bit bus by passing <B>-b 0 -i 4 --interleave-width=2</B>
|
|
and <B>-b 2 -i 4 --interleave-width=2</B> to two <B>objcopy</B>
|
|
commands. If the input was '12345678' then the outputs would be
|
|
'1256' and '3478' respectively.
|
|
<DT id="46"><B>-p</B><DD>
|
|
|
|
|
|
|
|
<DT id="47"><B>--preserve-dates</B><DD>
|
|
|
|
|
|
|
|
Set the access and modification dates of the output file to be the same
|
|
as those of the input file.
|
|
<DT id="48"><B>-D</B><DD>
|
|
|
|
|
|
|
|
<DT id="49"><B>--enable-deterministic-archives</B><DD>
|
|
|
|
|
|
|
|
Operate in <I>deterministic</I> mode. When copying archive members
|
|
and writing the archive index, use zero for UIDs, GIDs, timestamps,
|
|
and use consistent file modes for all files.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If <I>binutils</I> was configured with
|
|
<B>--enable-deterministic-archives</B>, then this mode is on by default.
|
|
It can be disabled with the <B>-U</B> option, below.
|
|
<DT id="50"><B>-U</B><DD>
|
|
|
|
|
|
|
|
<DT id="51"><B>--disable-deterministic-archives</B><DD>
|
|
|
|
|
|
|
|
Do <I>not</I> operate in <I>deterministic</I> mode. This is the
|
|
inverse of the <B>-D</B> option, above: when copying archive members
|
|
and writing the archive index, use their actual <FONT SIZE="-1">UID, GID,</FONT> timestamp,
|
|
and file mode values.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This is the default unless <I>binutils</I> was configured with
|
|
<B>--enable-deterministic-archives</B>.
|
|
<DT id="52"><B>--debugging</B><DD>
|
|
|
|
|
|
Convert debugging information, if possible. This is not the default
|
|
because only certain debugging formats are supported, and the
|
|
conversion process can be time consuming.
|
|
<DT id="53"><B>--gap-fill</B> <I>val</I><DD>
|
|
|
|
|
|
Fill gaps between sections with <I>val</I>. This operation applies to
|
|
the <I>load address</I> (<FONT SIZE="-1">LMA</FONT>) of the sections. It is done by increasing
|
|
the size of the section with the lower address, and filling in the extra
|
|
space created with <I>val</I>.
|
|
<DT id="54"><B>--pad-to</B> <I>address</I><DD>
|
|
|
|
|
|
Pad the output file up to the load address <I>address</I>. This is
|
|
done by increasing the size of the last section. The extra space is
|
|
filled in with the value specified by <B>--gap-fill</B> (default zero).
|
|
<DT id="55"><B>--set-start</B> <I>val</I><DD>
|
|
|
|
|
|
Set the start address of the new file to <I>val</I>. Not all object file
|
|
formats support setting the start address.
|
|
<DT id="56"><B>--change-start</B> <I>incr</I><DD>
|
|
|
|
|
|
|
|
<DT id="57"><B>--adjust-start</B> <I>incr</I><DD>
|
|
|
|
|
|
|
|
Change the start address by adding <I>incr</I>. Not all object file
|
|
formats support setting the start address.
|
|
<DT id="58"><B>--change-addresses</B> <I>incr</I><DD>
|
|
|
|
|
|
|
|
<DT id="59"><B>--adjust-vma</B> <I>incr</I><DD>
|
|
|
|
|
|
|
|
Change the <FONT SIZE="-1">VMA</FONT> and <FONT SIZE="-1">LMA</FONT> addresses of all sections, as well as the start
|
|
address, by adding <I>incr</I>. Some object file formats do not permit
|
|
section addresses to be changed arbitrarily. Note that this does not
|
|
relocate the sections; if the program expects sections to be loaded at a
|
|
certain address, and this option is used to change the sections such
|
|
that they are loaded at a different address, the program may fail.
|
|
<DT id="60"><B>--change-section-address</B> <I>sectionpattern</I><B>{=,+,-}</B><I>val</I><DD>
|
|
|
|
|
|
|
|
<DT id="61"><B>--adjust-section-vma</B> <I>sectionpattern</I><B>{=,+,-}</B><I>val</I><DD>
|
|
|
|
|
|
|
|
Set or change both the <FONT SIZE="-1">VMA</FONT> address and the <FONT SIZE="-1">LMA</FONT> address of any section
|
|
matching <I>sectionpattern</I>. If <B>=</B> is used, the section
|
|
address is set to <I>val</I>. Otherwise, <I>val</I> is added to or
|
|
subtracted from the section address. See the comments under
|
|
<B>--change-addresses</B>, above. If <I>sectionpattern</I> does not
|
|
match any sections in the input file, a warning will be issued, unless
|
|
<B>--no-change-warnings</B> is used.
|
|
<DT id="62"><B>--change-section-lma</B> <I>sectionpattern</I><B>{=,+,-}</B><I>val</I><DD>
|
|
|
|
|
|
Set or change the <FONT SIZE="-1">LMA</FONT> address of any sections matching
|
|
<I>sectionpattern</I>. The <FONT SIZE="-1">LMA</FONT> address is the address where the
|
|
section will be loaded into memory at program load time. Normally
|
|
this is the same as the <FONT SIZE="-1">VMA</FONT> address, which is the address of the
|
|
section at program run time, but on some systems, especially those
|
|
where a program is held in <FONT SIZE="-1">ROM,</FONT> the two can be different. If <B>=</B>
|
|
is used, the section address is set to <I>val</I>. Otherwise,
|
|
<I>val</I> is added to or subtracted from the section address. See the
|
|
comments under <B>--change-addresses</B>, above. If
|
|
<I>sectionpattern</I> does not match any sections in the input file, a
|
|
warning will be issued, unless <B>--no-change-warnings</B> is used.
|
|
<DT id="63"><B>--change-section-vma</B> <I>sectionpattern</I><B>{=,+,-}</B><I>val</I><DD>
|
|
|
|
|
|
Set or change the <FONT SIZE="-1">VMA</FONT> address of any section matching
|
|
<I>sectionpattern</I>. The <FONT SIZE="-1">VMA</FONT> address is the address where the
|
|
section will be located once the program has started executing.
|
|
Normally this is the same as the <FONT SIZE="-1">LMA</FONT> address, which is the address
|
|
where the section will be loaded into memory, but on some systems,
|
|
especially those where a program is held in <FONT SIZE="-1">ROM,</FONT> the two can be
|
|
different. If <B>=</B> is used, the section address is set to
|
|
<I>val</I>. Otherwise, <I>val</I> is added to or subtracted from the
|
|
section address. See the comments under <B>--change-addresses</B>,
|
|
above. If <I>sectionpattern</I> does not match any sections in the
|
|
input file, a warning will be issued, unless
|
|
<B>--no-change-warnings</B> is used.
|
|
<DT id="64"><B>--change-warnings</B><DD>
|
|
|
|
|
|
|
|
<DT id="65"><B>--adjust-warnings</B><DD>
|
|
|
|
|
|
|
|
If <B>--change-section-address</B> or <B>--change-section-lma</B> or
|
|
<B>--change-section-vma</B> is used, and the section pattern does not
|
|
match any sections, issue a warning. This is the default.
|
|
<DT id="66"><B>--no-change-warnings</B><DD>
|
|
|
|
|
|
|
|
<DT id="67"><B>--no-adjust-warnings</B><DD>
|
|
|
|
|
|
|
|
Do not issue a warning if <B>--change-section-address</B> or
|
|
<B>--adjust-section-lma</B> or <B>--adjust-section-vma</B> is used, even
|
|
if the section pattern does not match any sections.
|
|
<DT id="68"><B>--set-section-flags</B> <I>sectionpattern</I><B>=</B><I>flags</I><DD>
|
|
|
|
|
|
Set the flags for any sections matching <I>sectionpattern</I>. The
|
|
<I>flags</I> argument is a comma separated string of flag names. The
|
|
recognized names are <B>alloc</B>, <B>contents</B>, <B>load</B>,
|
|
<B>noload</B>, <B>readonly</B>, <B>code</B>, <B>data</B>, <B>rom</B>,
|
|
<B>share</B>, and <B>debug</B>. You can set the <B>contents</B> flag
|
|
for a section which does not have contents, but it is not meaningful
|
|
to clear the <B>contents</B> flag of a section which does have
|
|
contents---just remove the section instead. Not all flags are
|
|
meaningful for all object file formats.
|
|
<DT id="69"><B>--set-section-alignment</B> <I>sectionpattern</I><B>=</B><I>align</I><DD>
|
|
|
|
|
|
Set the alignment for any sections matching <I>sectionpattern</I>.
|
|
<I>align</I> specifies the alignment in bytes and must be a power of
|
|
two, i.e. 1, 2, 4, 8....
|
|
<DT id="70"><B>--add-section</B> <I>sectionname</I><B>=</B><I>filename</I><DD>
|
|
|
|
|
|
Add a new section named <I>sectionname</I> while copying the file. The
|
|
contents of the new section are taken from the file <I>filename</I>. The
|
|
size of the section will be the size of the file. This option only
|
|
works on file formats which can support sections with arbitrary names.
|
|
Note - it may be necessary to use the <B>--set-section-flags</B>
|
|
option to set the attributes of the newly created section.
|
|
<DT id="71"><B>--dump-section</B> <I>sectionname</I><B>=</B><I>filename</I><DD>
|
|
|
|
|
|
Place the contents of section named <I>sectionname</I> into the file
|
|
<I>filename</I>, overwriting any contents that may have been there
|
|
previously. This option is the inverse of <B>--add-section</B>.
|
|
This option is similar to the <B>--only-section</B> option except
|
|
that it does not create a formatted file, it just dumps the contents
|
|
as raw binary data, without applying any relocations. The option can
|
|
be specified more than once.
|
|
<DT id="72"><B>--update-section</B> <I>sectionname</I><B>=</B><I>filename</I><DD>
|
|
|
|
|
|
Replace the existing contents of a section named <I>sectionname</I>
|
|
with the contents of file <I>filename</I>. The size of the section
|
|
will be adjusted to the size of the file. The section flags for
|
|
<I>sectionname</I> will be unchanged. For <FONT SIZE="-1">ELF</FONT> format files the section
|
|
to segment mapping will also remain unchanged, something which is not
|
|
possible using <B>--remove-section</B> followed by
|
|
<B>--add-section</B>. The option can be specified more than once.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note - it is possible to use <B>--rename-section</B> and
|
|
<B>--update-section</B> to both update and rename a section from one
|
|
command line. In this case, pass the original section name to
|
|
<B>--update-section</B>, and the original and new section names to
|
|
<B>--rename-section</B>.
|
|
<DT id="73"><B>--add-symbol</B> <I>name</I><B>=[</B><I>section</I><B>:]</B><I>value</I><B>[,</B><I>flags</I><B>]</B><DD>
|
|
|
|
|
|
Add a new symbol named <I>name</I> while copying the file. This option may be
|
|
specified multiple times. If the <I>section</I> is given, the symbol will be
|
|
associated with and relative to that section, otherwise it will be an <FONT SIZE="-1">ABS</FONT>
|
|
symbol. Specifying an undefined section will result in a fatal error. There
|
|
is no check for the value, it will be taken as specified. Symbol flags can
|
|
be specified and not all flags will be meaningful for all object file
|
|
formats. By default, the symbol will be global. The special flag
|
|
'before=<I>othersym</I>' will insert the new symbol in front of the specified
|
|
<I>othersym</I>, otherwise the symbol(s) will be added at the end of the
|
|
symbol table in the order they appear.
|
|
<DT id="74"><B>--rename-section</B> <I>oldname</I><B>=</B><I>newname</I><B>[,</B><I>flags</I><B>]</B><DD>
|
|
|
|
|
|
Rename a section from <I>oldname</I> to <I>newname</I>, optionally
|
|
changing the section's flags to <I>flags</I> in the process. This has
|
|
the advantage over using a linker script to perform the rename in that
|
|
the output stays as an object file and does not become a linked
|
|
executable.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option is particularly helpful when the input format is binary,
|
|
since this will always create a section called .data. If for example,
|
|
you wanted instead to create a section called .rodata containing binary
|
|
data you could use the following command line to achieve it:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
objcopy -I binary -O <output_format> -B <architecture> \
|
|
--rename-section .data=.rodata,alloc,load,readonly,data,contents \
|
|
<input_binary_file> <output_object_file>
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="75"><B>--long-section-names {enable,disable,keep}</B><DD>
|
|
|
|
|
|
Controls the handling of long section names when processing <TT>"COFF"</TT>
|
|
and <TT>"PE-COFF"</TT> object formats. The default behaviour, <B>keep</B>,
|
|
is to preserve long section names if any are present in the input file.
|
|
The <B>enable</B> and <B>disable</B> options forcibly enable or disable
|
|
the use of long section names in the output object; when <B>disable</B>
|
|
is in effect, any long section names in the input object will be truncated.
|
|
The <B>enable</B> option will only emit long section names if any are
|
|
present in the inputs; this is mostly the same as <B>keep</B>, but it
|
|
is left undefined whether the <B>enable</B> option might force the
|
|
creation of an empty string table in the output file.
|
|
<DT id="76"><B>--change-leading-char</B><DD>
|
|
|
|
|
|
Some object file formats use special characters at the start of
|
|
symbols. The most common such character is underscore, which compilers
|
|
often add before every symbol. This option tells <B>objcopy</B> to
|
|
change the leading character of every symbol when it converts between
|
|
object file formats. If the object file formats use the same leading
|
|
character, this option has no effect. Otherwise, it will add a
|
|
character, or remove a character, or change a character, as
|
|
appropriate.
|
|
<DT id="77"><B>--remove-leading-char</B><DD>
|
|
|
|
|
|
If the first character of a global symbol is a special symbol leading
|
|
character used by the object file format, remove the character. The
|
|
most common symbol leading character is underscore. This option will
|
|
remove a leading underscore from all global symbols. This can be useful
|
|
if you want to link together objects of different file formats with
|
|
different conventions for symbol names. This is different from
|
|
<B>--change-leading-char</B> because it always changes the symbol name
|
|
when appropriate, regardless of the object file format of the output
|
|
file.
|
|
<DT id="78"><B>--reverse-bytes=</B><I>num</I><DD>
|
|
|
|
|
|
Reverse the bytes in a section with output contents. A section length must
|
|
be evenly divisible by the value given in order for the swap to be able to
|
|
take place. Reversing takes place before the interleaving is performed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option is used typically in generating <FONT SIZE="-1">ROM</FONT> images for problematic
|
|
target systems. For example, on some target boards, the 32-bit words
|
|
fetched from 8-bit ROMs are re-assembled in little-endian byte order
|
|
regardless of the <FONT SIZE="-1">CPU</FONT> byte order. Depending on the programming model, the
|
|
endianness of the <FONT SIZE="-1">ROM</FONT> may need to be modified.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Consider a simple file with a section containing the following eight
|
|
bytes: <TT>12345678</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Using <B>--reverse-bytes=2</B> for the above example, the bytes in the
|
|
output file would be ordered <TT>21436587</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Using <B>--reverse-bytes=4</B> for the above example, the bytes in the
|
|
output file would be ordered <TT>43218765</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
By using <B>--reverse-bytes=2</B> for the above example, followed by
|
|
<B>--reverse-bytes=4</B> on the output file, the bytes in the second
|
|
output file would be ordered <TT>34127856</TT>.
|
|
<DT id="79"><B>--srec-len=</B><I>ival</I><DD>
|
|
|
|
|
|
Meaningful only for srec output. Set the maximum length of the Srecords
|
|
being produced to <I>ival</I>. This length covers both address, data and
|
|
crc fields.
|
|
<DT id="80"><B>--srec-forceS3</B><DD>
|
|
|
|
|
|
Meaningful only for srec output. Avoid generation of S1/S2 records,
|
|
creating S3-only record format.
|
|
<DT id="81"><B>--redefine-sym</B> <I>old</I><B>=</B><I>new</I><DD>
|
|
|
|
|
|
Change the name of a symbol <I>old</I>, to <I>new</I>. This can be useful
|
|
when one is trying link two things together for which you have no
|
|
source, and there are name collisions.
|
|
<DT id="82"><B>--redefine-syms=</B><I>filename</I><DD>
|
|
|
|
|
|
Apply <B>--redefine-sym</B> to each symbol pair "<I>old</I> <I>new</I>"
|
|
listed in the file <I>filename</I>. <I>filename</I> is simply a flat file,
|
|
with one symbol pair per line. Line comments may be introduced by the hash
|
|
character. This option may be given more than once.
|
|
<DT id="83"><B>--weaken</B><DD>
|
|
|
|
|
|
Change all global symbols in the file to be weak. This can be useful
|
|
when building an object which will be linked against other objects using
|
|
the <B>-R</B> option to the linker. This option is only effective when
|
|
using an object file format which supports weak symbols.
|
|
<DT id="84"><B>--keep-symbols=</B><I>filename</I><DD>
|
|
|
|
|
|
Apply <B>--keep-symbol</B> option to each symbol listed in the file
|
|
<I>filename</I>. <I>filename</I> is simply a flat file, with one symbol
|
|
name per line. Line comments may be introduced by the hash character.
|
|
This option may be given more than once.
|
|
<DT id="85"><B>--strip-symbols=</B><I>filename</I><DD>
|
|
|
|
|
|
Apply <B>--strip-symbol</B> option to each symbol listed in the file
|
|
<I>filename</I>. <I>filename</I> is simply a flat file, with one symbol
|
|
name per line. Line comments may be introduced by the hash character.
|
|
This option may be given more than once.
|
|
<DT id="86"><B>--strip-unneeded-symbols=</B><I>filename</I><DD>
|
|
|
|
|
|
Apply <B>--strip-unneeded-symbol</B> option to each symbol listed in
|
|
the file <I>filename</I>. <I>filename</I> is simply a flat file, with one
|
|
symbol name per line. Line comments may be introduced by the hash
|
|
character. This option may be given more than once.
|
|
<DT id="87"><B>--keep-global-symbols=</B><I>filename</I><DD>
|
|
|
|
|
|
Apply <B>--keep-global-symbol</B> option to each symbol listed in the
|
|
file <I>filename</I>. <I>filename</I> is simply a flat file, with one
|
|
symbol name per line. Line comments may be introduced by the hash
|
|
character. This option may be given more than once.
|
|
<DT id="88"><B>--localize-symbols=</B><I>filename</I><DD>
|
|
|
|
|
|
Apply <B>--localize-symbol</B> option to each symbol listed in the file
|
|
<I>filename</I>. <I>filename</I> is simply a flat file, with one symbol
|
|
name per line. Line comments may be introduced by the hash character.
|
|
This option may be given more than once.
|
|
<DT id="89"><B>--globalize-symbols=</B><I>filename</I><DD>
|
|
|
|
|
|
Apply <B>--globalize-symbol</B> option to each symbol listed in the file
|
|
<I>filename</I>. <I>filename</I> is simply a flat file, with one symbol
|
|
name per line. Line comments may be introduced by the hash character.
|
|
This option may be given more than once. Note: this option cannot be
|
|
used in conjunction with the <B>-G</B> or <B>--keep-global-symbol</B>
|
|
options.
|
|
<DT id="90"><B>--weaken-symbols=</B><I>filename</I><DD>
|
|
|
|
|
|
Apply <B>--weaken-symbol</B> option to each symbol listed in the file
|
|
<I>filename</I>. <I>filename</I> is simply a flat file, with one symbol
|
|
name per line. Line comments may be introduced by the hash character.
|
|
This option may be given more than once.
|
|
<DT id="91"><B>--alt-machine-code=</B><I>index</I><DD>
|
|
|
|
|
|
If the output architecture has alternate machine codes, use the
|
|
<I>index</I>th code instead of the default one. This is useful in case
|
|
a machine is assigned an official code and the tool-chain adopts the
|
|
new code, but other applications still depend on the original code
|
|
being used. For <FONT SIZE="-1">ELF</FONT> based architectures if the <I>index</I>
|
|
alternative does not exist then the value is treated as an absolute
|
|
number to be stored in the e_machine field of the <FONT SIZE="-1">ELF</FONT> header.
|
|
<DT id="92"><B>--writable-text</B><DD>
|
|
|
|
|
|
Mark the output text as writable. This option isn't meaningful for all
|
|
object file formats.
|
|
<DT id="93"><B>--readonly-text</B><DD>
|
|
|
|
|
|
Make the output text write protected. This option isn't meaningful for all
|
|
object file formats.
|
|
<DT id="94"><B>--pure</B><DD>
|
|
|
|
|
|
Mark the output file as demand paged. This option isn't meaningful for all
|
|
object file formats.
|
|
<DT id="95"><B>--impure</B><DD>
|
|
|
|
|
|
Mark the output file as impure. This option isn't meaningful for all
|
|
object file formats.
|
|
<DT id="96"><B>--prefix-symbols=</B><I>string</I><DD>
|
|
|
|
|
|
Prefix all symbols in the output file with <I>string</I>.
|
|
<DT id="97"><B>--prefix-sections=</B><I>string</I><DD>
|
|
|
|
|
|
Prefix all section names in the output file with <I>string</I>.
|
|
<DT id="98"><B>--prefix-alloc-sections=</B><I>string</I><DD>
|
|
|
|
|
|
Prefix all the names of all allocated sections in the output file with
|
|
<I>string</I>.
|
|
<DT id="99"><B>--add-gnu-debuglink=</B><I>path-to-file</I><DD>
|
|
|
|
|
|
Creates a .gnu_debuglink section which contains a reference to
|
|
<I>path-to-file</I> and adds it to the output file. Note: the file at
|
|
<I>path-to-file</I> must exist. Part of the process of adding the
|
|
.gnu_debuglink section involves embedding a checksum of the contents
|
|
of the debug info file into the section.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the debug info file is built in one location but it is going to be
|
|
installed at a later time into a different location then do not use
|
|
the path to the installed location. The <B>--add-gnu-debuglink</B>
|
|
option will fail because the installed file does not exist yet.
|
|
Instead put the debug info file in the current directory and use the
|
|
<B>--add-gnu-debuglink</B> option without any directory components,
|
|
like this:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
objcopy --add-gnu-debuglink=foo.debug
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
At debug time the debugger will attempt to look for the separate debug
|
|
info file in a set of known locations. The exact set of these
|
|
locations varies depending upon the distribution being used, but it
|
|
typically includes:
|
|
<DL COMPACT><DT id="100"><DD>
|
|
<DL COMPACT>
|
|
<DT id="101">"* The same directory as the executable."<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="102">"* A sub-directory of the directory containing the executable"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
called .debug
|
|
<DT id="103">"* A global debug directory such as /usr/lib/debug."<DD>
|
|
|
|
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="104"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
As long as the debug info file has been installed into one of these
|
|
locations before the debugger is run everything should work
|
|
correctly.
|
|
</DL>
|
|
|
|
<DT id="105"><B>--keep-file-symbols</B><DD>
|
|
|
|
|
|
When stripping a file, perhaps with <B>--strip-debug</B> or
|
|
<B>--strip-unneeded</B>, retain any symbols specifying source file names,
|
|
which would otherwise get stripped.
|
|
<DT id="106"><B>--only-keep-debug</B><DD>
|
|
|
|
|
|
Strip a file, removing contents of any sections that would not be
|
|
stripped by <B>--strip-debug</B> and leaving the debugging sections
|
|
intact. In <FONT SIZE="-1">ELF</FONT> files, this preserves all note sections in the output.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The intention is that this option will be used in conjunction with
|
|
<B>--add-gnu-debuglink</B> to create a two part executable. One a
|
|
stripped binary which will occupy less space in <FONT SIZE="-1">RAM</FONT> 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:
|
|
<DL COMPACT><DT id="107"><DD>
|
|
<DL COMPACT>
|
|
<DT id="108">1.<Link the executable as normal. Assuming that it is called><DD>
|
|
|
|
|
|
<TT>"foo"</TT> then...
|
|
<DT id="109">1.<Run "objcopy --only-keep-debug foo foo.dbg" to><DD>
|
|
|
|
|
|
|
|
|
|
create a file containing the debugging info.
|
|
<DT id="110">1.<Run "objcopy --strip-debug foo" to create a><DD>
|
|
|
|
|
|
|
|
|
|
stripped executable.
|
|
<DT id="111">1.<Run "objcopy --add-gnu-debuglink=foo.dbg foo"><DD>
|
|
|
|
|
|
|
|
|
|
to add a link to the debugging info into the stripped executable.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="112"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note---the choice of <TT>".dbg"</TT> as an extension for the debug info
|
|
file is arbitrary. Also the <TT>"--only-keep-debug"</TT> step is
|
|
optional. You could instead do this:
|
|
<DL COMPACT>
|
|
<DT id="113">1.<Link the executable as normal.><DD>
|
|
|
|
|
|
|
|
<DT id="114">1.<Copy "foo" to "foo.full"><DD>
|
|
|
|
|
|
|
|
|
|
<DT id="115">1.<Run "objcopy --strip-debug foo"><DD>
|
|
|
|
|
|
|
|
|
|
<DT id="116">1.<Run "objcopy --add-gnu-debuglink=foo.full foo"><DD>
|
|
|
|
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="117"><DD>
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
i.e., the file pointed to by the <B>--add-gnu-debuglink</B> can be the
|
|
full executable. It does not have to be a file created by the
|
|
<B>--only-keep-debug</B> switch.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
</DL>
|
|
|
|
<DT id="118"><B>--strip-dwo</B><DD>
|
|
|
|
|
|
Remove the contents of all <FONT SIZE="-1">DWARF</FONT> .dwo sections, leaving the
|
|
remaining debugging sections and all symbols intact.
|
|
This option is intended for use by the compiler as part of
|
|
the <B>-gsplit-dwarf</B> option, which splits debug information
|
|
between the .o file and a separate .dwo file. The compiler
|
|
generates all debug information in the same file, then uses
|
|
the <B>--extract-dwo</B> option to copy the .dwo sections to
|
|
the .dwo file, then the <B>--strip-dwo</B> option to remove
|
|
those sections from the original .o file.
|
|
<DT id="119"><B>--extract-dwo</B><DD>
|
|
|
|
|
|
Extract the contents of all <FONT SIZE="-1">DWARF</FONT> .dwo sections. See the
|
|
<B>--strip-dwo</B> option for more information.
|
|
<DT id="120"><B>--file-alignment</B> <I>num</I><DD>
|
|
|
|
|
|
Specify the file alignment. Sections in the file will always begin at
|
|
file offsets which are multiples of this number. This defaults to
|
|
512.
|
|
[This option is specific to <FONT SIZE="-1">PE</FONT> targets.]
|
|
<DT id="121"><B>--heap</B> <I>reserve</I><DD>
|
|
|
|
|
|
|
|
<DT id="122"><B>--heap</B> <I>reserve</I><B>,</B><I>commit</I><DD>
|
|
|
|
|
|
|
|
Specify the number of bytes of memory to reserve (and optionally commit)
|
|
to be used as heap for this program.
|
|
[This option is specific to <FONT SIZE="-1">PE</FONT> targets.]
|
|
<DT id="123"><B>--image-base</B> <I>value</I><DD>
|
|
|
|
|
|
Use <I>value</I> as the base address of your program or dll. This is
|
|
the lowest memory location that will be used when your program or dll
|
|
is loaded. To reduce the need to relocate and improve performance of
|
|
your dlls, each should have a unique base address and not overlap any
|
|
other dlls. The default is 0x400000 for executables, and 0x10000000
|
|
for dlls.
|
|
[This option is specific to <FONT SIZE="-1">PE</FONT> targets.]
|
|
<DT id="124"><B>--section-alignment</B> <I>num</I><DD>
|
|
|
|
|
|
Sets the section alignment field in the <FONT SIZE="-1">PE</FONT> header. Sections in memory
|
|
will always begin at addresses which are a multiple of this number.
|
|
Defaults to 0x1000.
|
|
[This option is specific to <FONT SIZE="-1">PE</FONT> targets.]
|
|
<DT id="125"><B>--stack</B> <I>reserve</I><DD>
|
|
|
|
|
|
|
|
<DT id="126"><B>--stack</B> <I>reserve</I><B>,</B><I>commit</I><DD>
|
|
|
|
|
|
|
|
Specify the number of bytes of memory to reserve (and optionally commit)
|
|
to be used as stack for this program.
|
|
[This option is specific to <FONT SIZE="-1">PE</FONT> targets.]
|
|
<DT id="127"><B>--subsystem</B> <I>which</I><DD>
|
|
|
|
|
|
|
|
<DT id="128"><B>--subsystem</B> <I>which</I><B>:</B><I>major</I><DD>
|
|
|
|
|
|
<DT id="129"><B>--subsystem</B> <I>which</I><B>:</B><I>major</I><B>.</B><I>minor</I><DD>
|
|
|
|
|
|
|
|
Specifies the subsystem under which your program will execute. The
|
|
legal values for <I>which</I> are <TT>"native"</TT>, <TT>"windows"</TT>,
|
|
<TT>"console"</TT>, <TT>"posix"</TT>, <TT>"efi-app"</TT>, <TT>"efi-bsd"</TT>,
|
|
<TT>"efi-rtd"</TT>, <TT>"sal-rtd"</TT>, and <TT>"xbox"</TT>. You may optionally set
|
|
the subsystem version also. Numeric values are also accepted for
|
|
<I>which</I>.
|
|
[This option is specific to <FONT SIZE="-1">PE</FONT> targets.]
|
|
<DT id="130"><B>--extract-symbol</B><DD>
|
|
|
|
|
|
Keep the file's section flags and symbols but remove all section data.
|
|
Specifically, the option:
|
|
<DL COMPACT><DT id="131"><DD>
|
|
<DL COMPACT>
|
|
<DT id="132">*<removes the contents of all sections;><DD>
|
|
|
|
|
|
|
|
<DT id="133">*<sets the size of every section to zero; and><DD>
|
|
|
|
|
|
<DT id="134">*<sets the file's start address to zero.><DD>
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="135"><DD>
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option is used to build a <I>.sym</I> file for a VxWorks kernel.
|
|
It can also be a useful way of reducing the size of a <B>--just-symbols</B>
|
|
linker input file.
|
|
</DL>
|
|
|
|
<DT id="136"><B>--compress-debug-sections</B><DD>
|
|
|
|
|
|
Compress <FONT SIZE="-1">DWARF</FONT> debug sections using zlib with <FONT SIZE="-1">SHF_COMPRESSED</FONT> from the
|
|
<FONT SIZE="-1">ELF ABI.</FONT> Note - if compression would actually make a section
|
|
<I>larger</I>, then it is not compressed.
|
|
<DT id="137"><B>--compress-debug-sections=none</B><DD>
|
|
|
|
|
|
|
|
<DT id="138"><B>--compress-debug-sections=zlib</B><DD>
|
|
|
|
|
|
<DT id="139"><B>--compress-debug-sections=zlib-gnu</B><DD>
|
|
|
|
|
|
<DT id="140"><B>--compress-debug-sections=zlib-gabi</B><DD>
|
|
|
|
|
|
|
|
For <FONT SIZE="-1">ELF</FONT> files, these options control how <FONT SIZE="-1">DWARF</FONT> debug sections are
|
|
compressed. <B>--compress-debug-sections=none</B> is equivalent
|
|
to <B>--decompress-debug-sections</B>.
|
|
<B>--compress-debug-sections=zlib</B> and
|
|
<B>--compress-debug-sections=zlib-gabi</B> are equivalent to
|
|
<B>--compress-debug-sections</B>.
|
|
<B>--compress-debug-sections=zlib-gnu</B> compresses <FONT SIZE="-1">DWARF</FONT> debug
|
|
sections using zlib. The debug sections are renamed to begin with
|
|
<B>.zdebug</B> instead of <B>.debug</B>. Note - if compression would
|
|
actually make a section <I>larger</I>, then it is not compressed nor
|
|
renamed.
|
|
<DT id="141"><B>--decompress-debug-sections</B><DD>
|
|
|
|
|
|
Decompress <FONT SIZE="-1">DWARF</FONT> debug sections using zlib. The original section
|
|
names of the compressed sections are restored.
|
|
<DT id="142"><B>--elf-stt-common=yes</B><DD>
|
|
|
|
|
|
|
|
<DT id="143"><B>--elf-stt-common=no</B><DD>
|
|
|
|
|
|
|
|
For <FONT SIZE="-1">ELF</FONT> files, these options control whether common symbols should be
|
|
converted to the <TT>"STT_COMMON"</TT> or <TT>"STT_OBJECT"</TT> type.
|
|
<B>--elf-stt-common=yes</B> converts common symbol type to
|
|
<TT>"STT_COMMON"</TT>. <B>--elf-stt-common=no</B> converts common symbol
|
|
type to <TT>"STT_OBJECT"</TT>.
|
|
<DT id="144"><B>--merge-notes</B><DD>
|
|
|
|
|
|
|
|
<DT id="145"><B>--no-merge-notes</B><DD>
|
|
|
|
|
|
|
|
For <FONT SIZE="-1">ELF</FONT> files, attempt (or do not attempt) to reduce the size of any
|
|
<FONT SIZE="-1">SHT_NOTE</FONT> type sections by removing duplicate notes.
|
|
<DT id="146"><B>-V</B><DD>
|
|
|
|
|
|
|
|
<DT id="147"><B>--version</B><DD>
|
|
|
|
|
|
|
|
Show the version number of <B>objcopy</B>.
|
|
<DT id="148"><B>--verilog-data-width=</B><I>bytes</I><DD>
|
|
|
|
|
|
For Verilog output, this options controls the number of bytes
|
|
converted for each output data element. The input target controls the
|
|
endianness of the conversion.
|
|
<DT id="149"><B>-v</B><DD>
|
|
|
|
|
|
|
|
<DT id="150"><B>--verbose</B><DD>
|
|
|
|
|
|
|
|
Verbose output: list all object files modified. In the case of
|
|
archives, <B>objcopy -V</B> lists all members of the archive.
|
|
<DT id="151"><B>--help</B><DD>
|
|
|
|
|
|
Show a summary of the options to <B>objcopy</B>.
|
|
<DT id="152"><B>--info</B><DD>
|
|
|
|
|
|
Display a list showing all architectures and object formats available.
|
|
<DT id="153"><B>@</B><I>file</I><DD>
|
|
|
|
|
|
Read command-line options from <I>file</I>. The options read are
|
|
inserted in place of the original @<I>file</I> option. If <I>file</I>
|
|
does not exist, or cannot be read, then the option will be treated
|
|
literally, and not removed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Options in <I>file</I> 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 <I>file</I> may itself contain additional
|
|
@<I>file</I> options; any such options will be processed recursively.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ld">ld</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+objdump">objdump</A></B>(1), and the Info entries for <I>binutils</I>.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
|
|
Copyright (c) 1991-2020 Free Software Foundation, Inc.
|
|
<P>
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the <FONT SIZE="-1">GNU</FONT> 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 ``<FONT SIZE="-1">GNU</FONT> Free Documentation License''.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="154"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="155"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="156"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="157"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="158"><A HREF="#lbAF">SEE ALSO</A><DD>
|
|
<DT id="159"><A HREF="#lbAG">COPYRIGHT</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:20 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|