547 lines
37 KiB
HTML
547 lines
37 KiB
HTML
|
<html lang="en">
|
||
|
|
<head>
|
||
|
|
<title>objcopy - GNU Binary Utilities</title>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html">
|
||
|
|
<meta name="description" content="GNU Binary Utilities">
|
||
|
|
<meta name="generator" content="makeinfo 4.7">
|
||
|
|
<link title="Top" rel="start" href="index.html#Top">
|
||
|
|
<link rel="prev" href="nm.html#nm" title="nm">
|
||
|
|
<link rel="next" href="objdump.html#objdump" title="objdump">
|
||
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
||
|
|
<!--
|
||
|
|
Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
|
||
|
|
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.2
|
||
|
|
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''.
|
||
|
|
|
||
|
|
man end-->
|
||
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
||
|
|
<style type="text/css"><!--
|
||
|
|
pre.display { font-family:inherit }
|
||
|
|
pre.format { font-family:inherit }
|
||
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallexample { font-size:smaller }
|
||
|
|
pre.smalllisp { font-size:smaller }
|
||
|
|
span.sc { font-variant:small-caps }
|
||
|
|
span.roman { font-family: serif; font-weight: normal; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class="node">
|
||
|
|
<p>
|
||
|
|
<a name="objcopy"></a>Next: <a rel="next" accesskey="n" href="objdump.html#objdump">objdump</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="nm.html#nm">nm</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
|
||
|
|
<hr><br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h2 class="chapter">3 objcopy</h2>
|
||
|
|
|
||
|
|
<!-- man title objcopy copy and translate object files -->
|
||
|
|
<pre class="smallexample"> <!-- man begin SYNOPSIS objcopy -->
|
||
|
|
objcopy [<span class="option">-F</span> <var>bfdname</var>|<span class="option">--target=</span><var>bfdname</var>]
|
||
|
|
[<span class="option">-I</span> <var>bfdname</var>|<span class="option">--input-target=</span><var>bfdname</var>]
|
||
|
|
[<span class="option">-O</span> <var>bfdname</var>|<span class="option">--output-target=</span><var>bfdname</var>]
|
||
|
|
[<span class="option">-B</span> <var>bfdarch</var>|<span class="option">--binary-architecture=</span><var>bfdarch</var>]
|
||
|
|
[<span class="option">-S</span>|<span class="option">--strip-all</span>]
|
||
|
|
[<span class="option">-g</span>|<span class="option">--strip-debug</span>]
|
||
|
|
[<span class="option">-K</span> <var>symbolname</var>|<span class="option">--keep-symbol=</span><var>symbolname</var>]
|
||
|
|
[<span class="option">-N</span> <var>symbolname</var>|<span class="option">--strip-symbol=</span><var>symbolname</var>]
|
||
|
|
[<span class="option">--strip-unneeded-symbol=</span><var>symbolname</var>]
|
||
|
|
[<span class="option">-G</span> <var>symbolname</var>|<span class="option">--keep-global-symbol=</span><var>symbolname</var>]
|
||
|
|
[<span class="option">--localize-hidden</span>]
|
||
|
|
[<span class="option">-L</span> <var>symbolname</var>|<span class="option">--localize-symbol=</span><var>symbolname</var>]
|
||
|
|
[<span class="option">--globalize-symbol=</span><var>symbolname</var>]
|
||
|
|
[<span class="option">-W</span> <var>symbolname</var>|<span class="option">--weaken-symbol=</span><var>symbolname</var>]
|
||
|
|
[<span class="option">-w</span>|<span class="option">--wildcard</span>]
|
||
|
|
[<span class="option">-x</span>|<span class="option">--discard-all</span>]
|
||
|
|
[<span class="option">-X</span>|<span class="option">--discard-locals</span>]
|
||
|
|
[<span class="option">-b</span> <var>byte</var>|<span class="option">--byte=</span><var>byte</var>]
|
||
|
|
[<span class="option">-i</span> <var>interleave</var>|<span class="option">--interleave=</span><var>interleave</var>]
|
||
|
|
[<span class="option">-j</span> <var>sectionname</var>|<span class="option">--only-section=</span><var>sectionname</var>]
|
||
|
|
[<span class="option">-R</span> <var>sectionname</var>|<span class="option">--remove-section=</span><var>sectionname</var>]
|
||
|
|
[<span class="option">-p</span>|<span class="option">--preserve-dates</span>]
|
||
|
|
[<span class="option">--debugging</span>]
|
||
|
|
[<span class="option">--gap-fill=</span><var>val</var>]
|
||
|
|
[<span class="option">--pad-to=</span><var>address</var>]
|
||
|
|
[<span class="option">--set-start=</span><var>val</var>]
|
||
|
|
[<span class="option">--adjust-start=</span><var>incr</var>]
|
||
|
|
[<span class="option">--change-addresses=</span><var>incr</var>]
|
||
|
|
[<span class="option">--change-section-address</span> <var>section</var>{=,+,-}<var>val</var>]
|
||
|
|
[<span class="option">--change-section-lma</span> <var>section</var>{=,+,-}<var>val</var>]
|
||
|
|
[<span class="option">--change-section-vma</span> <var>section</var>{=,+,-}<var>val</var>]
|
||
|
|
[<span class="option">--change-warnings</span>] [<span class="option">--no-change-warnings</span>]
|
||
|
|
[<span class="option">--set-section-flags</span> <var>section</var>=<var>flags</var>]
|
||
|
|
[<span class="option">--add-section</span> <var>sectionname</var>=<var>filename</var>]
|
||
|
|
[<span class="option">--rename-section</span> <var>oldname</var>=<var>newname</var>[,<var>flags</var>]]
|
||
|
|
[<span class="option">--change-leading-char</span>] [<span class="option">--remove-leading-char</span>]
|
||
|
|
[<span class="option">--reverse-bytes=</span><var>num</var>]
|
||
|
|
[<span class="option">--srec-len=</span><var>ival</var>] [<span class="option">--srec-forceS3</span>]
|
||
|
|
[<span class="option">--redefine-sym</span> <var>old</var>=<var>new</var>]
|
||
|
|
[<span class="option">--redefine-syms=</span><var>filename</var>]
|
||
|
|
[<span class="option">--weaken</span>]
|
||
|
|
[<span class="option">--keep-symbols=</span><var>filename</var>]
|
||
|
|
[<span class="option">--strip-symbols=</span><var>filename</var>]
|
||
|
|
[<span class="option">--strip-unneeded-symbols=</span><var>filename</var>]
|
||
|
|
[<span class="option">--keep-global-symbols=</span><var>filename</var>]
|
||
|
|
[<span class="option">--localize-symbols=</span><var>filename</var>]
|
||
|
|
[<span class="option">--globalize-symbols=</span><var>filename</var>]
|
||
|
|
[<span class="option">--weaken-symbols=</span><var>filename</var>]
|
||
|
|
[<span class="option">--alt-machine-code=</span><var>index</var>]
|
||
|
|
[<span class="option">--prefix-symbols=</span><var>string</var>]
|
||
|
|
[<span class="option">--prefix-sections=</span><var>string</var>]
|
||
|
|
[<span class="option">--prefix-alloc-sections=</span><var>string</var>]
|
||
|
|
[<span class="option">--add-gnu-debuglink=</span><var>path-to-file</var>]
|
||
|
|
[<span class="option">--keep-file-symbols</span>]
|
||
|
|
[<span class="option">--only-keep-debug</span>]
|
||
|
|
[<span class="option">--extract-symbol</span>]
|
||
|
|
[<span class="option">--writable-text</span>]
|
||
|
|
[<span class="option">--readonly-text</span>]
|
||
|
|
[<span class="option">--pure</span>]
|
||
|
|
[<span class="option">--impure</span>]
|
||
|
|
[<span class="option">-v</span>|<span class="option">--verbose</span>]
|
||
|
|
[<span class="option">-V</span>|<span class="option">--version</span>]
|
||
|
|
[<span class="option">--help</span>] [<span class="option">--info</span>]
|
||
|
|
<var>infile</var> [<var>outfile</var>]
|
||
|
|
<!-- man end -->
|
||
|
|
</pre>
|
||
|
|
<!-- man begin DESCRIPTION objcopy -->
|
||
|
|
<p>The <span class="sc">gnu</span> <span class="command">objcopy</span> utility copies the contents of an object
|
||
|
|
file to another. <span class="command">objcopy</span> uses the <span class="sc">gnu</span> <span class="sc">bfd</span> 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 <span class="command">objcopy</span> is controlled by command-line options.
|
||
|
|
Note that <span class="command">objcopy</span> 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><span class="command">objcopy</span> creates temporary files to do its translations and
|
||
|
|
deletes them afterward. <span class="command">objcopy</span> uses <span class="sc">bfd</span> to do all its
|
||
|
|
translation work; it has access to all the formats described in <span class="sc">bfd</span>
|
||
|
|
and thus is able to recognize most formats without being told
|
||
|
|
explicitly. See <a href="../ld/BFD.html#BFD">BFD (Using LD)</a>.
|
||
|
|
|
||
|
|
<p><span class="command">objcopy</span> can be used to generate S-records by using an output
|
||
|
|
target of <span class="samp">srec</span> (e.g., use <span class="samp">-O srec</span>).
|
||
|
|
|
||
|
|
<p><span class="command">objcopy</span> can be used to generate a raw binary file by using an
|
||
|
|
output target of <span class="samp">binary</span> (e.g., use <span class="option">-O binary</span>). When
|
||
|
|
<span class="command">objcopy</span> 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 <span class="option">-S</span> to remove sections containing debugging information. In
|
||
|
|
some cases <span class="option">-R</span> will be useful to remove sections which contain
|
||
|
|
information that is not needed by the binary file.
|
||
|
|
|
||
|
|
<p>Note—<span class="command">objcopy</span> is not able to change the endianness of its input
|
||
|
|
files. If the input format has an endianness (some formats do not),
|
||
|
|
<span class="command">objcopy</span> can only copy the inputs into file formats that have the
|
||
|
|
same endianness or which have no endianness (e.g., <span class="samp">srec</span>).
|
||
|
|
(However, see the <span class="option">--reverse-bytes</span> option.)
|
||
|
|
|
||
|
|
<!-- man end -->
|
||
|
|
<!-- man begin OPTIONS objcopy -->
|
||
|
|
<dl>
|
||
|
|
<dt><var>infile</var><dt><var>outfile</var><dd>The input and output files, respectively.
|
||
|
|
If you do not specify <var>outfile</var>, <span class="command">objcopy</span> creates a
|
||
|
|
temporary file and destructively renames the result with
|
||
|
|
the name of <var>infile</var>.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-I </span><var>bfdname</var><dt><span class="env">--input-target=</span><var>bfdname</var><dd>Consider the source file's object format to be <var>bfdname</var>, rather than
|
||
|
|
attempting to deduce it. See <a href="Target-Selection.html#Target-Selection">Target Selection</a>, for more information.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-O </span><var>bfdname</var><dt><span class="env">--output-target=</span><var>bfdname</var><dd>Write the output file using the object format <var>bfdname</var>.
|
||
|
|
See <a href="Target-Selection.html#Target-Selection">Target Selection</a>, for more information.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-F </span><var>bfdname</var><dt><span class="env">--target=</span><var>bfdname</var><dd>Use <var>bfdname</var> as the object format for both the input and the output
|
||
|
|
file; i.e., simply transfer data from source to destination with no
|
||
|
|
translation. See <a href="Target-Selection.html#Target-Selection">Target Selection</a>, for more information.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-B </span><var>bfdarch</var><dt><span class="env">--binary-architecture=</span><var>bfdarch</var><dd>Useful when transforming a raw binary input file into an object file.
|
||
|
|
In this case the output architecture can be set to <var>bfdarch</var>. This
|
||
|
|
option will be ignored if the input file has a known <var>bfdarch</var>. 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_<var>objfile</var>_start, _binary_<var>objfile</var>_end and
|
||
|
|
_binary_<var>objfile</var>_size. e.g. you can transform a picture file into
|
||
|
|
an object file and then access it in your code using these symbols.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-j </span><var>sectionname</var><dt><span class="env">--only-section=</span><var>sectionname</var><dd>Copy only the named section 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-R </span><var>sectionname</var><dt><span class="env">--remove-section=</span><var>sectionname</var><dd>Remove any section named <var>sectionname</var> from the output file. This
|
||
|
|
option may be given more than once. Note that using this option
|
||
|
|
inappropriately may make the output file unusable.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-S</span><dt><span class="env">--strip-all</span><dd>Do not copy relocation and symbol information from the source file.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-g</span><dt><span class="env">--strip-debug</span><dd>Do not copy debugging symbols or sections from the source file.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--strip-unneeded</span><dd>Strip all symbols that are not needed for relocation processing.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-K </span><var>symbolname</var><dt><span class="env">--keep-symbol=</span><var>symbolname</var><dd>When stripping symbols, keep symbol <var>symbolname</var> even if it would
|
||
|
|
normally be stripped. This option may be given more than once.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-N </span><var>symbolname</var><dt><span class="env">--strip-symbol=</span><var>symbolname</var><dd>Do not copy symbol <var>symbolname</var> from the source file. This option
|
||
|
|
may be given more than once.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--strip-unneeded-symbol=</span><var>symbolname</var><dd>Do not copy symbol <var>symbolname</var> from the source file unless it is needed
|
||
|
|
by a relocation. This option may be given more than once.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-G </span><var>symbolname</var><dt><span class="env">--keep-global-symbol=</span><var>symbolname</var><dd>Keep only symbol <var>symbolname</var> global. Make all other symbols local
|
||
|
|
to the file, so that they are not visible externally. This option may
|
||
|
|
be given more than once.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--localize-hidden</span><dd>In an ELF object, mark all symbols that have hidden or internal visibility
|
||
|
|
as local. This option applies on top of symbol-specific localization options
|
||
|
|
such as <span class="option">-L</span>.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-L </span><var>symbolname</var><dt><span class="env">--localize-symbol=</span><var>symbolname</var><dd>Make symbol <var>symbolname</var> local to the file, so that it is not
|
||
|
|
visible externally. This option may be given more than once.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-W </span><var>symbolname</var><dt><span class="env">--weaken-symbol=</span><var>symbolname</var><dd>Make symbol <var>symbolname</var> weak. This option may be given more than once.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--globalize-symbol=</span><var>symbolname</var><dd>Give symbol <var>symbolname</var> global scoping so that it is visible
|
||
|
|
outside of the file in which it is defined. This option may be given
|
||
|
|
more than once.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-w</span><dt><span class="env">--wildcard</span><dd>Permit regular expressions in <var>symbolname</var>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:
|
||
|
|
|
||
|
|
<pre class="smallexample"> -w -W !foo -W fo*
|
||
|
|
</pre>
|
||
|
|
<p>would cause objcopy to weaken all symbols that start with “fo”
|
||
|
|
except for the symbol “foo”.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-x</span><dt><span class="env">--discard-all</span><dd>Do not copy non-global symbols from the source file.
|
||
|
|
<!-- FIXME any reason to prefer "non-global" to "local" here? -->
|
||
|
|
|
||
|
|
<br><dt><span class="env">-X</span><dt><span class="env">--discard-locals</span><dd>Do not copy compiler-generated local symbols.
|
||
|
|
(These usually start with <span class="samp">L</span> or <span class="samp">.</span>.)
|
||
|
|
|
||
|
|
<br><dt><span class="env">-b </span><var>byte</var><dt><span class="env">--byte=</span><var>byte</var><dd>Keep only every <var>byte</var>th byte of the input file (header data is not
|
||
|
|
affected). <var>byte</var> can be in the range from 0 to <var>interleave</var>-1,
|
||
|
|
where <var>interleave</var> is given by the <span class="option">-i</span> or <span class="option">--interleave</span>
|
||
|
|
option, or the default of 4. This option is useful for creating files
|
||
|
|
to program <span class="sc">rom</span>. It is typically used with an <code>srec</code> output
|
||
|
|
target.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-i </span><var>interleave</var><dt><span class="env">--interleave=</span><var>interleave</var><dd>Only copy one out of every <var>interleave</var> bytes. Select which byte to
|
||
|
|
copy with the <span class="option">-b</span> or <span class="option">--byte</span> option. The default is 4.
|
||
|
|
<span class="command">objcopy</span> ignores this option if you do not specify either <span class="option">-b</span> or
|
||
|
|
<span class="option">--byte</span>.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-p</span><dt><span class="env">--preserve-dates</span><dd>Set the access and modification dates of the output file to be the same
|
||
|
|
as those of the input file.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--debugging</span><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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--gap-fill </span><var>val</var><dd>Fill gaps between sections with <var>val</var>. This operation applies to
|
||
|
|
the <em>load address</em> (LMA) 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 <var>val</var>.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--pad-to </span><var>address</var><dd>Pad the output file up to the load address <var>address</var>. This is
|
||
|
|
done by increasing the size of the last section. The extra space is
|
||
|
|
filled in with the value specified by <span class="option">--gap-fill</span> (default zero).
|
||
|
|
|
||
|
|
<br><dt><span class="env">--set-start </span><var>val</var><dd>Set the start address of the new file to <var>val</var>. Not all object file
|
||
|
|
formats support setting the start address.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--change-start </span><var>incr</var><dt><span class="env">--adjust-start </span><var>incr</var><dd><a name="index-changing-start-address-52"></a>Change the start address by adding <var>incr</var>. Not all object file
|
||
|
|
formats support setting the start address.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--change-addresses </span><var>incr</var><dt><span class="env">--adjust-vma </span><var>incr</var><dd><a name="index-changing-object-addresses-53"></a>Change the VMA and LMA addresses of all sections, as well as the start
|
||
|
|
address, by adding <var>incr</var>. 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--change-section-address </span><var>section</var><span class="env">{=,+,-}</span><var>val</var><dt><span class="env">--adjust-section-vma </span><var>section</var><span class="env">{=,+,-}</span><var>val</var><dd><a name="index-changing-section-address-54"></a>Set or change both the VMA address and the LMA address of the named
|
||
|
|
<var>section</var>. If <span class="samp">=</span> is used, the section address is set to
|
||
|
|
<var>val</var>. Otherwise, <var>val</var> is added to or subtracted from the
|
||
|
|
section address. See the comments under <span class="option">--change-addresses</span>,
|
||
|
|
above. If <var>section</var> does not exist in the input file, a warning will
|
||
|
|
be issued, unless <span class="option">--no-change-warnings</span> is used.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--change-section-lma </span><var>section</var><span class="env">{=,+,-}</span><var>val</var><dd><a name="index-changing-section-LMA-55"></a>Set or change the LMA address of the named <var>section</var>. The LMA
|
||
|
|
address is the address where the section will be loaded into memory at
|
||
|
|
program load time. Normally this is the same as the VMA address, which
|
||
|
|
is the address of the section at program run time, but on some systems,
|
||
|
|
especially those where a program is held in ROM, the two can be
|
||
|
|
different. If <span class="samp">=</span> is used, the section address is set to
|
||
|
|
<var>val</var>. Otherwise, <var>val</var> is added to or subtracted from the
|
||
|
|
section address. See the comments under <span class="option">--change-addresses</span>,
|
||
|
|
above. If <var>section</var> does not exist in the input file, a warning
|
||
|
|
will be issued, unless <span class="option">--no-change-warnings</span> is used.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--change-section-vma </span><var>section</var><span class="env">{=,+,-}</span><var>val</var><dd><a name="index-changing-section-VMA-56"></a>Set or change the VMA address of the named <var>section</var>. The VMA
|
||
|
|
address is the address where the section will be located once the
|
||
|
|
program has started executing. Normally this is the same as the LMA
|
||
|
|
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
|
||
|
|
ROM, the two can be different. If <span class="samp">=</span> is used, the section address
|
||
|
|
is set to <var>val</var>. Otherwise, <var>val</var> is added to or subtracted
|
||
|
|
from the section address. See the comments under
|
||
|
|
<span class="option">--change-addresses</span>, above. If <var>section</var> does not exist in
|
||
|
|
the input file, a warning will be issued, unless
|
||
|
|
<span class="option">--no-change-warnings</span> is used.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--change-warnings</span><dt><span class="env">--adjust-warnings</span><dd>If <span class="option">--change-section-address</span> or <span class="option">--change-section-lma</span> or
|
||
|
|
<span class="option">--change-section-vma</span> is used, and the named section does not
|
||
|
|
exist, issue a warning. This is the default.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--no-change-warnings</span><dt><span class="env">--no-adjust-warnings</span><dd>Do not issue a warning if <span class="option">--change-section-address</span> or
|
||
|
|
<span class="option">--adjust-section-lma</span> or <span class="option">--adjust-section-vma</span> is used, even
|
||
|
|
if the named section does not exist.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--set-section-flags </span><var>section</var><span class="env">=</span><var>flags</var><dd>Set the flags for the named section. The <var>flags</var> argument is a
|
||
|
|
comma separated string of flag names. The recognized names are
|
||
|
|
<span class="samp">alloc</span>, <span class="samp">contents</span>, <span class="samp">load</span>, <span class="samp">noload</span>,
|
||
|
|
<span class="samp">readonly</span>, <span class="samp">code</span>, <span class="samp">data</span>, <span class="samp">rom</span>, <span class="samp">share</span>, and
|
||
|
|
<span class="samp">debug</span>. You can set the <span class="samp">contents</span> flag for a section which
|
||
|
|
does not have contents, but it is not meaningful to clear the
|
||
|
|
<span class="samp">contents</span> flag of a section which does have contents–just remove
|
||
|
|
the section instead. Not all flags are meaningful for all object file
|
||
|
|
formats.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--add-section </span><var>sectionname</var><span class="env">=</span><var>filename</var><dd>Add a new section named <var>sectionname</var> while copying the file. The
|
||
|
|
contents of the new section are taken from the file <var>filename</var>. 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--rename-section </span><var>oldname</var><span class="env">=</span><var>newname</var><span class="env">[,</span><var>flags</var><span class="env">]</span><dd>Rename a section from <var>oldname</var> to <var>newname</var>, optionally
|
||
|
|
changing the section's flags to <var>flags</var> in the process. This has
|
||
|
|
the advantage over usng 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:
|
||
|
|
|
||
|
|
<pre class="smallexample"> objcopy -I binary -O <output_format> -B <architecture> \
|
||
|
|
--rename-section .data=.rodata,alloc,load,readonly,data,contents \
|
||
|
|
<input_binary_file> <output_object_file>
|
||
|
|
</pre>
|
||
|
|
<br><dt><span class="env">--change-leading-char</span><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 <span class="command">objcopy</span> 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--remove-leading-char</span><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
|
||
|
|
<span class="option">--change-leading-char</span> because it always changes the symbol name
|
||
|
|
when appropriate, regardless of the object file format of the output
|
||
|
|
file.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--reverse-bytes=</span><var>num</var><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 ROM 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 CPU byte order. Depending on the programming model, the
|
||
|
|
endianness of the ROM may need to be modified.
|
||
|
|
|
||
|
|
<p>Consider a simple file with a section containing the following eight
|
||
|
|
bytes: <code>12345678</code>.
|
||
|
|
|
||
|
|
<p>Using <span class="samp">--reverse-bytes=2</span> for the above example, the bytes in the
|
||
|
|
output file would be ordered <code>21436587</code>.
|
||
|
|
|
||
|
|
<p>Using <span class="samp">--reverse-bytes=4</span> for the above example, the bytes in the
|
||
|
|
output file would be ordered <code>43218765</code>.
|
||
|
|
|
||
|
|
<p>By using <span class="samp">--reverse-bytes=2</span> for the above example, followed by
|
||
|
|
<span class="samp">--reverse-bytes=4</span> on the output file, the bytes in the second
|
||
|
|
output file would be ordered <code>34127856</code>.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--srec-len=</span><var>ival</var><dd>Meaningful only for srec output. Set the maximum length of the Srecords
|
||
|
|
being produced to <var>ival</var>. This length covers both address, data and
|
||
|
|
crc fields.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--srec-forceS3</span><dd>Meaningful only for srec output. Avoid generation of S1/S2 records,
|
||
|
|
creating S3-only record format.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--redefine-sym </span><var>old</var><span class="env">=</span><var>new</var><dd>Change the name of a symbol <var>old</var>, to <var>new</var>. This can be useful
|
||
|
|
when one is trying link two things together for which you have no
|
||
|
|
source, and there are name collisions.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--redefine-syms=</span><var>filename</var><dd>Apply <span class="option">--redefine-sym</span> to each symbol pair "<var>old</var> <var>new</var>"
|
||
|
|
listed in the file <var>filename</var>. <var>filename</var> 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--weaken</span><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 <span class="option">-R</span> option to the linker. This option is only effective when
|
||
|
|
using an object file format which supports weak symbols.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--keep-symbols=</span><var>filename</var><dd>Apply <span class="option">--keep-symbol</span> option to each symbol listed in the file
|
||
|
|
<var>filename</var>. <var>filename</var> 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--strip-symbols=</span><var>filename</var><dd>Apply <span class="option">--strip-symbol</span> option to each symbol listed in the file
|
||
|
|
<var>filename</var>. <var>filename</var> 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--strip-unneeded-symbols=</span><var>filename</var><dd>Apply <span class="option">--strip-unneeded-symbol</span> option to each symbol listed in
|
||
|
|
the file <var>filename</var>. <var>filename</var> 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--keep-global-symbols=</span><var>filename</var><dd>Apply <span class="option">--keep-global-symbol</span> option to each symbol listed in the
|
||
|
|
file <var>filename</var>. <var>filename</var> 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--localize-symbols=</span><var>filename</var><dd>Apply <span class="option">--localize-symbol</span> option to each symbol listed in the file
|
||
|
|
<var>filename</var>. <var>filename</var> 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--globalize-symbols=</span><var>filename</var><dd>Apply <span class="option">--globalize-symbol</span> option to each symbol listed in the file
|
||
|
|
<var>filename</var>. <var>filename</var> 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--weaken-symbols=</span><var>filename</var><dd>Apply <span class="option">--weaken-symbol</span> option to each symbol listed in the file
|
||
|
|
<var>filename</var>. <var>filename</var> 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--alt-machine-code=</span><var>index</var><dd>If the output architecture has alternate machine codes, use the
|
||
|
|
<var>index</var>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 ELF based architectures if the <var>index</var>
|
||
|
|
alternative does not exist then the value is treated as an absolute
|
||
|
|
number to be stored in the e_machine field of the ELF header.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--writable-text</span><dd>Mark the output text as writable. This option isn't meaningful for all
|
||
|
|
object file formats.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--readonly-text</span><dd>Make the output text write protected. This option isn't meaningful for all
|
||
|
|
object file formats.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--pure</span><dd>Mark the output file as demand paged. This option isn't meaningful for all
|
||
|
|
object file formats.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--impure</span><dd>Mark the output file as impure. This option isn't meaningful for all
|
||
|
|
object file formats.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--prefix-symbols=</span><var>string</var><dd>Prefix all symbols in the output file with <var>string</var>.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--prefix-sections=</span><var>string</var><dd>Prefix all section names in the output file with <var>string</var>.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--prefix-alloc-sections=</span><var>string</var><dd>Prefix all the names of all allocated sections in the output file with
|
||
|
|
<var>string</var>.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--add-gnu-debuglink=</span><var>path-to-file</var><dd>Creates a .gnu_debuglink section which contains a reference to <var>path-to-file</var>
|
||
|
|
and adds it to the output file.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--keep-file-symbols</span><dd>When stripping a file, perhaps with <span class="option">--strip-debug</span> or
|
||
|
|
<span class="option">--strip-unneeded</span>, retain any symbols specifying source file names,
|
||
|
|
which would otherwise get stripped.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--only-keep-debug</span><dd>Strip a file, removing contents of any sections that would not be
|
||
|
|
stripped by <span class="option">--strip-debug</span> and leaving the debugging sections
|
||
|
|
intact. In ELF files, this preserves all note sections in the output.
|
||
|
|
|
||
|
|
<p>The intention is that this option will be used in conjunction with
|
||
|
|
<span class="option">--add-gnu-debuglink</span> 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:
|
||
|
|
|
||
|
|
<ol type=1 start=1>
|
||
|
|
<li>Link the executable as normal. Assuming that is is called
|
||
|
|
<code>foo</code> then...
|
||
|
|
<li>Run <code>objcopy --only-keep-debug foo foo.dbg</code> to
|
||
|
|
create a file containing the debugging info.
|
||
|
|
<li>Run <code>objcopy --strip-debug foo</code> to create a
|
||
|
|
stripped executable.
|
||
|
|
<li>Run <code>objcopy --add-gnu-debuglink=foo.dbg foo</code>
|
||
|
|
to add a link to the debugging info into the stripped executable.
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>Note—the choice of <code>.dbg</code> as an extension for the debug info
|
||
|
|
file is arbitrary. Also the <code>--only-keep-debug</code> step is
|
||
|
|
optional. You could instead do this:
|
||
|
|
|
||
|
|
<ol type=1 start=1>
|
||
|
|
<li>Link the executable as normal.
|
||
|
|
<li>Copy <code>foo</code> to <code>foo.full</code>
|
||
|
|
<li>Run <code>objcopy --strip-debug foo</code>
|
||
|
|
<li>Run <code>objcopy --add-gnu-debuglink=foo.full foo</code>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>i.e., the file pointed to by the <span class="option">--add-gnu-debuglink</span> can be the
|
||
|
|
full executable. It does not have to be a file created by the
|
||
|
|
<span class="option">--only-keep-debug</span> 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.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--extract-symbol</span><dd>Keep the file's section flags and symbols but remove all section data.
|
||
|
|
Specifically, the option:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>removes the contents of all sections;
|
||
|
|
<li>sets the size of every section to zero; and
|
||
|
|
<li>sets the file's start address to zero.
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>This option is used to build a <span class="file">.sym</span> file for a VxWorks kernel.
|
||
|
|
It can also be a useful way of reducing the size of a <span class="option">--just-symbols</span>
|
||
|
|
linker input file.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-V</span><dt><span class="env">--version</span><dd>Show the version number of <span class="command">objcopy</span>.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-v</span><dt><span class="env">--verbose</span><dd>Verbose output: list all object files modified. In the case of
|
||
|
|
archives, <span class="samp">objcopy -V</span> lists all members of the archive.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--help</span><dd>Show a summary of the options to <span class="command">objcopy</span>.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--info</span><dd>Display a list showing all architectures and object formats available.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<!-- man end -->
|
||
|
|
</body></html>
|
||
|
|
|