You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1094 lines
52 KiB
HTML
1094 lines
52 KiB
HTML
4 years ago
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- Copyright (C) 1991-2019 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.3
|
||
|
|
or any later version published by the Free Software Foundation;
|
||
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
||
|
|
Back-Cover Texts. A copy of the license is included in the
|
||
|
|
section entitled "GNU Free Documentation License".
|
||
|
|
-->
|
||
|
|
<!-- Created by GNU Texinfo 6.4, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>objcopy (GNU Binary Utilities)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="objcopy (GNU Binary Utilities)">
|
||
|
|
<meta name="keywords" content="objcopy (GNU Binary Utilities)">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content="makeinfo">
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<link href="index.html#Top" rel="start" title="Top">
|
||
|
|
<link href="Binutils-Index.html#Binutils-Index" rel="index" title="Binutils Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="index.html#Top" rel="up" title="Top">
|
||
|
|
<link href="objdump.html#objdump" rel="next" title="objdump">
|
||
|
|
<link href="nm.html#nm" rel="prev" title="nm">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.summary-letter {text-decoration: none}
|
||
|
|
blockquote.indentedblock {margin-right: 0em}
|
||
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
div.smalllisp {margin-left: 3.2em}
|
||
|
|
kbd {font-style: oblique}
|
||
|
|
pre.display {font-family: inherit}
|
||
|
|
pre.format {font-family: inherit}
|
||
|
|
pre.menu-comment {font-family: serif}
|
||
|
|
pre.menu-preformatted {font-family: serif}
|
||
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smallexample {font-size: smaller}
|
||
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smalllisp {font-size: smaller}
|
||
|
|
span.nolinebreak {white-space: nowrap}
|
||
|
|
span.roman {font-family: initial; font-weight: normal}
|
||
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<a name="objcopy"></a>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="objdump.html#objdump" accesskey="n" rel="next">objdump</a>, Previous: <a href="nm.html#nm" accesskey="p" rel="prev">nm</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Binutils-Index.html#Binutils-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<a name="objcopy-1"></a>
|
||
|
|
<h2 class="chapter">3 objcopy</h2>
|
||
|
|
|
||
|
|
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">objcopy [<samp>-F</samp> <var>bfdname</var>|<samp>--target=</samp><var>bfdname</var>]
|
||
|
|
[<samp>-I</samp> <var>bfdname</var>|<samp>--input-target=</samp><var>bfdname</var>]
|
||
|
|
[<samp>-O</samp> <var>bfdname</var>|<samp>--output-target=</samp><var>bfdname</var>]
|
||
|
|
[<samp>-B</samp> <var>bfdarch</var>|<samp>--binary-architecture=</samp><var>bfdarch</var>]
|
||
|
|
[<samp>-S</samp>|<samp>--strip-all</samp>]
|
||
|
|
[<samp>-g</samp>|<samp>--strip-debug</samp>]
|
||
|
|
[<samp>--strip-unneeded</samp>]
|
||
|
|
[<samp>-K</samp> <var>symbolname</var>|<samp>--keep-symbol=</samp><var>symbolname</var>]
|
||
|
|
[<samp>-N</samp> <var>symbolname</var>|<samp>--strip-symbol=</samp><var>symbolname</var>]
|
||
|
|
[<samp>--strip-unneeded-symbol=</samp><var>symbolname</var>]
|
||
|
|
[<samp>-G</samp> <var>symbolname</var>|<samp>--keep-global-symbol=</samp><var>symbolname</var>]
|
||
|
|
[<samp>--localize-hidden</samp>]
|
||
|
|
[<samp>-L</samp> <var>symbolname</var>|<samp>--localize-symbol=</samp><var>symbolname</var>]
|
||
|
|
[<samp>--globalize-symbol=</samp><var>symbolname</var>]
|
||
|
|
[<samp>--globalize-symbols=</samp><var>filename</var>]
|
||
|
|
[<samp>-W</samp> <var>symbolname</var>|<samp>--weaken-symbol=</samp><var>symbolname</var>]
|
||
|
|
[<samp>-w</samp>|<samp>--wildcard</samp>]
|
||
|
|
[<samp>-x</samp>|<samp>--discard-all</samp>]
|
||
|
|
[<samp>-X</samp>|<samp>--discard-locals</samp>]
|
||
|
|
[<samp>-b</samp> <var>byte</var>|<samp>--byte=</samp><var>byte</var>]
|
||
|
|
[<samp>-i</samp> [<var>breadth</var>]|<samp>--interleave</samp>[=<var>breadth</var>]]
|
||
|
|
[<samp>--interleave-width=</samp><var>width</var>]
|
||
|
|
[<samp>-j</samp> <var>sectionpattern</var>|<samp>--only-section=</samp><var>sectionpattern</var>]
|
||
|
|
[<samp>-R</samp> <var>sectionpattern</var>|<samp>--remove-section=</samp><var>sectionpattern</var>]
|
||
|
|
[<samp>--remove-relocations=</samp><var>sectionpattern</var>]
|
||
|
|
[<samp>-p</samp>|<samp>--preserve-dates</samp>]
|
||
|
|
[<samp>-D</samp>|<samp>--enable-deterministic-archives</samp>]
|
||
|
|
[<samp>-U</samp>|<samp>--disable-deterministic-archives</samp>]
|
||
|
|
[<samp>--debugging</samp>]
|
||
|
|
[<samp>--gap-fill=</samp><var>val</var>]
|
||
|
|
[<samp>--pad-to=</samp><var>address</var>]
|
||
|
|
[<samp>--set-start=</samp><var>val</var>]
|
||
|
|
[<samp>--adjust-start=</samp><var>incr</var>]
|
||
|
|
[<samp>--change-addresses=</samp><var>incr</var>]
|
||
|
|
[<samp>--change-section-address</samp> <var>sectionpattern</var>{=,+,-}<var>val</var>]
|
||
|
|
[<samp>--change-section-lma</samp> <var>sectionpattern</var>{=,+,-}<var>val</var>]
|
||
|
|
[<samp>--change-section-vma</samp> <var>sectionpattern</var>{=,+,-}<var>val</var>]
|
||
|
|
[<samp>--change-warnings</samp>] [<samp>--no-change-warnings</samp>]
|
||
|
|
[<samp>--set-section-flags</samp> <var>sectionpattern</var>=<var>flags</var>]
|
||
|
|
[<samp>--add-section</samp> <var>sectionname</var>=<var>filename</var>]
|
||
|
|
[<samp>--dump-section</samp> <var>sectionname</var>=<var>filename</var>]
|
||
|
|
[<samp>--update-section</samp> <var>sectionname</var>=<var>filename</var>]
|
||
|
|
[<samp>--rename-section</samp> <var>oldname</var>=<var>newname</var>[,<var>flags</var>]]
|
||
|
|
[<samp>--long-section-names</samp> {enable,disable,keep}]
|
||
|
|
[<samp>--change-leading-char</samp>] [<samp>--remove-leading-char</samp>]
|
||
|
|
[<samp>--reverse-bytes=</samp><var>num</var>]
|
||
|
|
[<samp>--srec-len=</samp><var>ival</var>] [<samp>--srec-forceS3</samp>]
|
||
|
|
[<samp>--redefine-sym</samp> <var>old</var>=<var>new</var>]
|
||
|
|
[<samp>--redefine-syms=</samp><var>filename</var>]
|
||
|
|
[<samp>--weaken</samp>]
|
||
|
|
[<samp>--keep-symbols=</samp><var>filename</var>]
|
||
|
|
[<samp>--strip-symbols=</samp><var>filename</var>]
|
||
|
|
[<samp>--strip-unneeded-symbols=</samp><var>filename</var>]
|
||
|
|
[<samp>--keep-global-symbols=</samp><var>filename</var>]
|
||
|
|
[<samp>--localize-symbols=</samp><var>filename</var>]
|
||
|
|
[<samp>--weaken-symbols=</samp><var>filename</var>]
|
||
|
|
[<samp>--add-symbol</samp> <var>name</var>=[<var>section</var>:]<var>value</var>[,<var>flags</var>]]
|
||
|
|
[<samp>--alt-machine-code=</samp><var>index</var>]
|
||
|
|
[<samp>--prefix-symbols=</samp><var>string</var>]
|
||
|
|
[<samp>--prefix-sections=</samp><var>string</var>]
|
||
|
|
[<samp>--prefix-alloc-sections=</samp><var>string</var>]
|
||
|
|
[<samp>--add-gnu-debuglink=</samp><var>path-to-file</var>]
|
||
|
|
[<samp>--keep-file-symbols</samp>]
|
||
|
|
[<samp>--only-keep-debug</samp>]
|
||
|
|
[<samp>--strip-dwo</samp>]
|
||
|
|
[<samp>--extract-dwo</samp>]
|
||
|
|
[<samp>--extract-symbol</samp>]
|
||
|
|
[<samp>--writable-text</samp>]
|
||
|
|
[<samp>--readonly-text</samp>]
|
||
|
|
[<samp>--pure</samp>]
|
||
|
|
[<samp>--impure</samp>]
|
||
|
|
[<samp>--file-alignment=</samp><var>num</var>]
|
||
|
|
[<samp>--heap=</samp><var>size</var>]
|
||
|
|
[<samp>--image-base=</samp><var>address</var>]
|
||
|
|
[<samp>--section-alignment=</samp><var>num</var>]
|
||
|
|
[<samp>--stack=</samp><var>size</var>]
|
||
|
|
[<samp>--subsystem=</samp><var>which</var>:<var>major</var>.<var>minor</var>]
|
||
|
|
[<samp>--compress-debug-sections</samp>]
|
||
|
|
[<samp>--decompress-debug-sections</samp>]
|
||
|
|
[<samp>--elf-stt-common=<var>val</var></samp>]
|
||
|
|
[<samp>--merge-notes</samp>]
|
||
|
|
[<samp>--no-merge-notes</samp>]
|
||
|
|
[<samp>-v</samp>|<samp>--verbose</samp>]
|
||
|
|
[<samp>-V</samp>|<samp>--version</samp>]
|
||
|
|
[<samp>--help</samp>] [<samp>--info</samp>]
|
||
|
|
<var>infile</var> [<var>outfile</var>]
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The <small>GNU</small> <code>objcopy</code> utility copies the contents of an object
|
||
|
|
file to another. <code>objcopy</code> uses the <small>GNU</small> <small>BFD</small> 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 <code>objcopy</code> is controlled by command-line options.
|
||
|
|
Note that <code>objcopy</code> 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>
|
||
|
|
<p><code>objcopy</code> creates temporary files to do its translations and
|
||
|
|
deletes them afterward. <code>objcopy</code> uses <small>BFD</small> to do all its
|
||
|
|
translation work; it has access to all the formats described in <small>BFD</small>
|
||
|
|
and thus is able to recognize most formats without being told
|
||
|
|
explicitly. See <a href="http://sourceware.org/binutils/docs/ld/BFD.html#BFD">BFD</a> in <cite>Using LD</cite>.
|
||
|
|
</p>
|
||
|
|
<p><code>objcopy</code> can be used to generate S-records by using an output
|
||
|
|
target of ‘<samp>srec</samp>’ (e.g., use ‘<samp>-O srec</samp>’).
|
||
|
|
</p>
|
||
|
|
<p><code>objcopy</code> can be used to generate a raw binary file by using an
|
||
|
|
output target of ‘<samp>binary</samp>’ (e.g., use <samp>-O binary</samp>). When
|
||
|
|
<code>objcopy</code> 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>
|
||
|
|
<p>When generating an S-record or a raw binary file, it may be helpful to
|
||
|
|
use <samp>-S</samp> to remove sections containing debugging information. In
|
||
|
|
some cases <samp>-R</samp> will be useful to remove sections which contain
|
||
|
|
information that is not needed by the binary file.
|
||
|
|
</p>
|
||
|
|
<p>Note—<code>objcopy</code> is not able to change the endianness of its input
|
||
|
|
files. If the input format has an endianness (some formats do not),
|
||
|
|
<code>objcopy</code> can only copy the inputs into file formats that have the
|
||
|
|
same endianness or which have no endianness (e.g., ‘<samp>srec</samp>’).
|
||
|
|
(However, see the <samp>--reverse-bytes</samp> option.)
|
||
|
|
</p>
|
||
|
|
|
||
|
|
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code><var>infile</var></code></dt>
|
||
|
|
<dt><code><var>outfile</var></code></dt>
|
||
|
|
<dd><p>The input and output files, respectively.
|
||
|
|
If you do not specify <var>outfile</var>, <code>objcopy</code> creates a
|
||
|
|
temporary file and destructively renames the result with
|
||
|
|
the name of <var>infile</var>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-I <var>bfdname</var></code></dt>
|
||
|
|
<dt><code>--input-target=<var>bfdname</var></code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-O <var>bfdname</var></code></dt>
|
||
|
|
<dt><code>--output-target=<var>bfdname</var></code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-F <var>bfdname</var></code></dt>
|
||
|
|
<dt><code>--target=<var>bfdname</var></code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-B <var>bfdarch</var></code></dt>
|
||
|
|
<dt><code>--binary-architecture=<var>bfdarch</var></code></dt>
|
||
|
|
<dd><p>Useful when transforming a architecture-less 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-j <var>sectionpattern</var></code></dt>
|
||
|
|
<dt><code>--only-section=<var>sectionpattern</var></code></dt>
|
||
|
|
<dd><p>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 <var>sectionpattern</var>.
|
||
|
|
</p>
|
||
|
|
<p>If the first character of <var>sectionpattern</var> is the exclamation
|
||
|
|
point (!) then matching sections will not be copied, even if earlier
|
||
|
|
use of <samp>--only-section</samp> on the same command line would
|
||
|
|
otherwise copy it. For example:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"> --only-section=.text.* --only-section=!.text.foo
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>will copy all sectinos maching ’.text.*’ but not the section
|
||
|
|
’.text.foo’.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-R <var>sectionpattern</var></code></dt>
|
||
|
|
<dt><code>--remove-section=<var>sectionpattern</var></code></dt>
|
||
|
|
<dd><p>Remove any section matching <var>sectionpattern</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. Wildcard
|
||
|
|
characters are accepted in <var>sectionpattern</var>. Using both the
|
||
|
|
<samp>-j</samp> and <samp>-R</samp> options together results in undefined
|
||
|
|
behaviour.
|
||
|
|
</p>
|
||
|
|
<p>If the first character of <var>sectionpattern</var> is the exclamation
|
||
|
|
point (!) then matching sections will not be removed even if an
|
||
|
|
earlier use of <samp>--remove-section</samp> on the same command line
|
||
|
|
would otherwise remove it. For example:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"> --remove-section=.text.* --remove-section=!.text.foo
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>will remove all sections matching the pattern ’.text.*’, but will not
|
||
|
|
remove the section ’.text.foo’.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--remove-relocations=<var>sectionpattern</var></code></dt>
|
||
|
|
<dd><p>Remove non-dynamic relocations from the output file for any section
|
||
|
|
matching <var>sectionpattern</var>. 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 ‘<samp>.rela.plt</samp>’ from an executable or shared library with
|
||
|
|
<samp>--remove-relocations=.plt</samp> will not work. Wildcard characters
|
||
|
|
are accepted in <var>sectionpattern</var>.
|
||
|
|
For example:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"> --remove-relocations=.text.*
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>will remove the relocations for all sections matching the pattern
|
||
|
|
’.text.*’.
|
||
|
|
</p>
|
||
|
|
<p>If the first character of <var>sectionpattern</var> is the exclamation
|
||
|
|
point (!) then matching sections will not have their relocation
|
||
|
|
removed even if an earlier use of <samp>--remove-relocations</samp> on the
|
||
|
|
same command line would otherwise cause the relocations to be removed.
|
||
|
|
For example:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"> --remove-relocations=.text.* --remove-relocations=!.text.foo
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>will remove all relocations for sections matching the pattern
|
||
|
|
’.text.*’, but will not remove relocations for the section
|
||
|
|
’.text.foo’.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-S</code></dt>
|
||
|
|
<dt><code>--strip-all</code></dt>
|
||
|
|
<dd><p>Do not copy relocation and symbol information from the source file.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-g</code></dt>
|
||
|
|
<dt><code>--strip-debug</code></dt>
|
||
|
|
<dd><p>Do not copy debugging symbols or sections from the source file.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--strip-unneeded</code></dt>
|
||
|
|
<dd><p>Strip all symbols that are not needed for relocation processing.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-K <var>symbolname</var></code></dt>
|
||
|
|
<dt><code>--keep-symbol=<var>symbolname</var></code></dt>
|
||
|
|
<dd><p>When stripping symbols, keep symbol <var>symbolname</var> even if it would
|
||
|
|
normally be stripped. This option may be given more than once.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-N <var>symbolname</var></code></dt>
|
||
|
|
<dt><code>--strip-symbol=<var>symbolname</var></code></dt>
|
||
|
|
<dd><p>Do not copy symbol <var>symbolname</var> from the source file. This option
|
||
|
|
may be given more than once.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--strip-unneeded-symbol=<var>symbolname</var></code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-G <var>symbolname</var></code></dt>
|
||
|
|
<dt><code>--keep-global-symbol=<var>symbolname</var></code></dt>
|
||
|
|
<dd><p>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. Note: this option cannot be used in
|
||
|
|
conjunction with the <samp>--globalize-symbol</samp> or
|
||
|
|
<samp>--globalize-symbols</samp> options.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--localize-hidden</code></dt>
|
||
|
|
<dd><p>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 <samp>-L</samp>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-L <var>symbolname</var></code></dt>
|
||
|
|
<dt><code>--localize-symbol=<var>symbolname</var></code></dt>
|
||
|
|
<dd><p>Convert a global or weak symbol called <var>symbolname</var> 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-W <var>symbolname</var></code></dt>
|
||
|
|
<dt><code>--weaken-symbol=<var>symbolname</var></code></dt>
|
||
|
|
<dd><p>Make symbol <var>symbolname</var> weak. This option may be given more than once.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--globalize-symbol=<var>symbolname</var></code></dt>
|
||
|
|
<dd><p>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. Note: this option cannot be used in conjunction with
|
||
|
|
the <samp>-G</samp> or <samp>--keep-global-symbol</samp> options.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-w</code></dt>
|
||
|
|
<dt><code>--wildcard</code></dt>
|
||
|
|
<dd><p>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:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"> -w -W !foo -W fo*
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>would cause objcopy to weaken all symbols that start with “fo”
|
||
|
|
except for the symbol “foo”.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-x</code></dt>
|
||
|
|
<dt><code>--discard-all</code></dt>
|
||
|
|
<dd><p>Do not copy non-global symbols from the source file.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-X</code></dt>
|
||
|
|
<dt><code>--discard-locals</code></dt>
|
||
|
|
<dd><p>Do not copy compiler-generated local symbols.
|
||
|
|
(These usually start with ‘<samp>L</samp>’ or ‘<samp>.</samp>’.)
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-b <var>byte</var></code></dt>
|
||
|
|
<dt><code>--byte=<var>byte</var></code></dt>
|
||
|
|
<dd><p>If interleaving has been enabled via the <samp>--interleave</samp> option
|
||
|
|
then start the range of bytes to keep at the <var>byte</var>th byte.
|
||
|
|
<var>byte</var> can be in the range from 0 to <var>breadth</var>-1, where
|
||
|
|
<var>breadth</var> is the value given by the <samp>--interleave</samp> option.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-i [<var>breadth</var>]</code></dt>
|
||
|
|
<dt><code>--interleave[=<var>breadth</var>]</code></dt>
|
||
|
|
<dd><p>Only copy a range out of every <var>breadth</var> bytes. (Header data is
|
||
|
|
not affected). Select which byte in the range begins the copy with
|
||
|
|
the <samp>--byte</samp> option. Select the width of the range with the
|
||
|
|
<samp>--interleave-width</samp> option.
|
||
|
|
</p>
|
||
|
|
<p>This option is useful for creating files to program <small>ROM</small>. It is
|
||
|
|
typically used with an <code>srec</code> output target. Note that
|
||
|
|
<code>objcopy</code> will complain if you do not specify the
|
||
|
|
<samp>--byte</samp> option as well.
|
||
|
|
</p>
|
||
|
|
<p>The default interleave breadth is 4, so with <samp>--byte</samp> set to 0,
|
||
|
|
<code>objcopy</code> would copy the first byte out of every four bytes
|
||
|
|
from the input to the output.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--interleave-width=<var>width</var></code></dt>
|
||
|
|
<dd><p>When used with the <samp>--interleave</samp> option, copy <var>width</var>
|
||
|
|
bytes at a time. The start of the range of bytes to be copied is set
|
||
|
|
by the <samp>--byte</samp> option, and the extent of the range is set with
|
||
|
|
the <samp>--interleave</samp> option.
|
||
|
|
</p>
|
||
|
|
<p>The default value for this option is 1. The value of <var>width</var> plus
|
||
|
|
the <var>byte</var> value set by the <samp>--byte</samp> option must not exceed
|
||
|
|
the interleave breadth set by the <samp>--interleave</samp> option.
|
||
|
|
</p>
|
||
|
|
<p>This option can be used to create images for two 16-bit flashes interleaved
|
||
|
|
in a 32-bit bus by passing <samp>-b 0 -i 4 --interleave-width=2</samp>
|
||
|
|
and <samp>-b 2 -i 4 --interleave-width=2</samp> to two <code>objcopy</code>
|
||
|
|
commands. If the input was ’12345678’ then the outputs would be
|
||
|
|
’1256’ and ’3478’ respectively.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-p</code></dt>
|
||
|
|
<dt><code>--preserve-dates</code></dt>
|
||
|
|
<dd><p>Set the access and modification dates of the output file to be the same
|
||
|
|
as those of the input file.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-D</code></dt>
|
||
|
|
<dt><code>--enable-deterministic-archives</code></dt>
|
||
|
|
<dd><a name="index-deterministic-archives-2"></a>
|
||
|
|
<a name="index-_002d_002denable_002ddeterministic_002darchives-2"></a>
|
||
|
|
<p>Operate in <em>deterministic</em> 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>
|
||
|
|
<p>If <samp>binutils</samp> was configured with
|
||
|
|
<samp>--enable-deterministic-archives</samp>, then this mode is on by default.
|
||
|
|
It can be disabled with the ‘<samp>-U</samp>’ option, below.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-U</code></dt>
|
||
|
|
<dt><code>--disable-deterministic-archives</code></dt>
|
||
|
|
<dd><a name="index-deterministic-archives-3"></a>
|
||
|
|
<a name="index-_002d_002denable_002ddeterministic_002darchives-3"></a>
|
||
|
|
<p>Do <em>not</em> operate in <em>deterministic</em> mode. This is the
|
||
|
|
inverse of the <samp>-D</samp> option, above: when copying archive members
|
||
|
|
and writing the archive index, use their actual UID, GID, timestamp,
|
||
|
|
and file mode values.
|
||
|
|
</p>
|
||
|
|
<p>This is the default unless <samp>binutils</samp> was configured with
|
||
|
|
<samp>--enable-deterministic-archives</samp>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--debugging</code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--gap-fill <var>val</var></code></dt>
|
||
|
|
<dd><p>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>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--pad-to <var>address</var></code></dt>
|
||
|
|
<dd><p>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 <samp>--gap-fill</samp> (default zero).
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--set-start <var>val</var></code></dt>
|
||
|
|
<dd><p>Set the start address of the new file to <var>val</var>. Not all object file
|
||
|
|
formats support setting the start address.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--change-start <var>incr</var></code></dt>
|
||
|
|
<dt><code>--adjust-start <var>incr</var></code></dt>
|
||
|
|
<dd><a name="index-changing-start-address"></a>
|
||
|
|
<p>Change the start address by adding <var>incr</var>. Not all object file
|
||
|
|
formats support setting the start address.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--change-addresses <var>incr</var></code></dt>
|
||
|
|
<dt><code>--adjust-vma <var>incr</var></code></dt>
|
||
|
|
<dd><a name="index-changing-object-addresses"></a>
|
||
|
|
<p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--change-section-address <var>sectionpattern</var>{=,+,-}<var>val</var></code></dt>
|
||
|
|
<dt><code>--adjust-section-vma <var>sectionpattern</var>{=,+,-}<var>val</var></code></dt>
|
||
|
|
<dd><a name="index-changing-section-address"></a>
|
||
|
|
<p>Set or change both the VMA address and the LMA address of any section
|
||
|
|
matching <var>sectionpattern</var>. If ‘<samp>=</samp>’ 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
|
||
|
|
<samp>--change-addresses</samp>, above. If <var>sectionpattern</var> does not
|
||
|
|
match any sections in the input file, a warning will be issued, unless
|
||
|
|
<samp>--no-change-warnings</samp> is used.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--change-section-lma <var>sectionpattern</var>{=,+,-}<var>val</var></code></dt>
|
||
|
|
<dd><a name="index-changing-section-LMA"></a>
|
||
|
|
<p>Set or change the LMA address of any sections matching
|
||
|
|
<var>sectionpattern</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 ‘<samp>=</samp>’
|
||
|
|
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 <samp>--change-addresses</samp>, above. If
|
||
|
|
<var>sectionpattern</var> does not match any sections in the input file, a
|
||
|
|
warning will be issued, unless <samp>--no-change-warnings</samp> is used.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--change-section-vma <var>sectionpattern</var>{=,+,-}<var>val</var></code></dt>
|
||
|
|
<dd><a name="index-changing-section-VMA"></a>
|
||
|
|
<p>Set or change the VMA address of any section matching
|
||
|
|
<var>sectionpattern</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 ‘<samp>=</samp>’ 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 <samp>--change-addresses</samp>,
|
||
|
|
above. If <var>sectionpattern</var> does not match any sections in the
|
||
|
|
input file, a warning will be issued, unless
|
||
|
|
<samp>--no-change-warnings</samp> is used.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--change-warnings</code></dt>
|
||
|
|
<dt><code>--adjust-warnings</code></dt>
|
||
|
|
<dd><p>If <samp>--change-section-address</samp> or <samp>--change-section-lma</samp> or
|
||
|
|
<samp>--change-section-vma</samp> is used, and the section pattern does not
|
||
|
|
match any sections, issue a warning. This is the default.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-change-warnings</code></dt>
|
||
|
|
<dt><code>--no-adjust-warnings</code></dt>
|
||
|
|
<dd><p>Do not issue a warning if <samp>--change-section-address</samp> or
|
||
|
|
<samp>--adjust-section-lma</samp> or <samp>--adjust-section-vma</samp> is used, even
|
||
|
|
if the section pattern does not match any sections.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--set-section-flags <var>sectionpattern</var>=<var>flags</var></code></dt>
|
||
|
|
<dd><p>Set the flags for any sections matching <var>sectionpattern</var>. The
|
||
|
|
<var>flags</var> argument is a comma separated string of flag names. The
|
||
|
|
recognized names are ‘<samp>alloc</samp>’, ‘<samp>contents</samp>’, ‘<samp>load</samp>’,
|
||
|
|
‘<samp>noload</samp>’, ‘<samp>readonly</samp>’, ‘<samp>code</samp>’, ‘<samp>data</samp>’, ‘<samp>rom</samp>’,
|
||
|
|
‘<samp>share</samp>’, and ‘<samp>debug</samp>’. You can set the ‘<samp>contents</samp>’ flag
|
||
|
|
for a section which does not have contents, but it is not meaningful
|
||
|
|
to clear the ‘<samp>contents</samp>’ flag of a section which does have
|
||
|
|
contents–just remove the section instead. Not all flags are
|
||
|
|
meaningful for all object file formats.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--add-section <var>sectionname</var>=<var>filename</var></code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
Note - it may be necessary to use the <samp>--set-section-flags</samp>
|
||
|
|
option to set the attributes of the newly created section.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--dump-section <var>sectionname</var>=<var>filename</var></code></dt>
|
||
|
|
<dd><p>Place the contents of section named <var>sectionname</var> into the file
|
||
|
|
<var>filename</var>, overwriting any contents that may have been there
|
||
|
|
previously. This option is the inverse of <samp>--add-section</samp>.
|
||
|
|
This option is similar to the <samp>--only-section</samp> 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--update-section <var>sectionname</var>=<var>filename</var></code></dt>
|
||
|
|
<dd><p>Replace the existing contents of a section named <var>sectionname</var>
|
||
|
|
with the contents of file <var>filename</var>. The size of the section
|
||
|
|
will be adjusted to the size of the file. The section flags for
|
||
|
|
<var>sectionname</var> will be unchanged. For ELF format files the section
|
||
|
|
to segment mapping will also remain unchanged, something which is not
|
||
|
|
possible using <samp>--remove-section</samp> followed by
|
||
|
|
<samp>--add-section</samp>. The option can be specified more than once.
|
||
|
|
</p>
|
||
|
|
<p>Note - it is possible to use <samp>--rename-section</samp> and
|
||
|
|
<samp>--update-section</samp> to both update and rename a section from one
|
||
|
|
command line. In this case, pass the original section name to
|
||
|
|
<samp>--update-section</samp>, and the original and new section names to
|
||
|
|
<samp>--rename-section</samp>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--add-symbol <var>name</var>=[<var>section</var>:]<var>value</var>[,<var>flags</var>]</code></dt>
|
||
|
|
<dd><p>Add a new symbol named <var>name</var> while copying the file. This option may be
|
||
|
|
specified multiple times. If the <var>section</var> is given, the symbol will be
|
||
|
|
associated with and relative to that section, otherwise it will be an ABS
|
||
|
|
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=<var>othersym</var>’ will insert the new symbol in front of the specified
|
||
|
|
<var>othersym</var>, otherwise the symbol(s) will be added at the end of the
|
||
|
|
symbol table in the order they appear.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--rename-section <var>oldname</var>=<var>newname</var>[,<var>flags</var>]</code></dt>
|
||
|
|
<dd><p>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 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>
|
||
|
|
<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>
|
||
|
|
<div class="smallexample">
|
||
|
|
<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></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code>--long-section-names {enable,disable,keep}</code></dt>
|
||
|
|
<dd><p>Controls the handling of long section names when processing <code>COFF</code>
|
||
|
|
and <code>PE-COFF</code> object formats. The default behaviour, ‘<samp>keep</samp>’,
|
||
|
|
is to preserve long section names if any are present in the input file.
|
||
|
|
The ‘<samp>enable</samp>’ and ‘<samp>disable</samp>’ options forcibly enable or disable
|
||
|
|
the use of long section names in the output object; when ‘<samp>disable</samp>’
|
||
|
|
is in effect, any long section names in the input object will be truncated.
|
||
|
|
The ‘<samp>enable</samp>’ option will only emit long section names if any are
|
||
|
|
present in the inputs; this is mostly the same as ‘<samp>keep</samp>’, but it
|
||
|
|
is left undefined whether the ‘<samp>enable</samp>’ option might force the
|
||
|
|
creation of an empty string table in the output file.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--change-leading-char</code></dt>
|
||
|
|
<dd><p>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 <code>objcopy</code> 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--remove-leading-char</code></dt>
|
||
|
|
<dd><p>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
|
||
|
|
<samp>--change-leading-char</samp> because it always changes the symbol name
|
||
|
|
when appropriate, regardless of the object file format of the output
|
||
|
|
file.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--reverse-bytes=<var>num</var></code></dt>
|
||
|
|
<dd><p>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>
|
||
|
|
<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>
|
||
|
|
<p>Consider a simple file with a section containing the following eight
|
||
|
|
bytes: <code>12345678</code>.
|
||
|
|
</p>
|
||
|
|
<p>Using ‘<samp>--reverse-bytes=2</samp>’ for the above example, the bytes in the
|
||
|
|
output file would be ordered <code>21436587</code>.
|
||
|
|
</p>
|
||
|
|
<p>Using ‘<samp>--reverse-bytes=4</samp>’ for the above example, the bytes in the
|
||
|
|
output file would be ordered <code>43218765</code>.
|
||
|
|
</p>
|
||
|
|
<p>By using ‘<samp>--reverse-bytes=2</samp>’ for the above example, followed by
|
||
|
|
‘<samp>--reverse-bytes=4</samp>’ on the output file, the bytes in the second
|
||
|
|
output file would be ordered <code>34127856</code>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--srec-len=<var>ival</var></code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--srec-forceS3</code></dt>
|
||
|
|
<dd><p>Meaningful only for srec output. Avoid generation of S1/S2 records,
|
||
|
|
creating S3-only record format.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--redefine-sym <var>old</var>=<var>new</var></code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--redefine-syms=<var>filename</var></code></dt>
|
||
|
|
<dd><p>Apply <samp>--redefine-sym</samp> 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--weaken</code></dt>
|
||
|
|
<dd><p>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 <samp>-R</samp> option to the linker. This option is only effective when
|
||
|
|
using an object file format which supports weak symbols.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--keep-symbols=<var>filename</var></code></dt>
|
||
|
|
<dd><p>Apply <samp>--keep-symbol</samp> 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--strip-symbols=<var>filename</var></code></dt>
|
||
|
|
<dd><p>Apply <samp>--strip-symbol</samp> 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--strip-unneeded-symbols=<var>filename</var></code></dt>
|
||
|
|
<dd><p>Apply <samp>--strip-unneeded-symbol</samp> 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--keep-global-symbols=<var>filename</var></code></dt>
|
||
|
|
<dd><p>Apply <samp>--keep-global-symbol</samp> 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--localize-symbols=<var>filename</var></code></dt>
|
||
|
|
<dd><p>Apply <samp>--localize-symbol</samp> 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--globalize-symbols=<var>filename</var></code></dt>
|
||
|
|
<dd><p>Apply <samp>--globalize-symbol</samp> 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. Note: this option cannot be
|
||
|
|
used in conjunction with the <samp>-G</samp> or <samp>--keep-global-symbol</samp>
|
||
|
|
options.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--weaken-symbols=<var>filename</var></code></dt>
|
||
|
|
<dd><p>Apply <samp>--weaken-symbol</samp> 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--alt-machine-code=<var>index</var></code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--writable-text</code></dt>
|
||
|
|
<dd><p>Mark the output text as writable. This option isn’t meaningful for all
|
||
|
|
object file formats.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--readonly-text</code></dt>
|
||
|
|
<dd><p>Make the output text write protected. This option isn’t meaningful for all
|
||
|
|
object file formats.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--pure</code></dt>
|
||
|
|
<dd><p>Mark the output file as demand paged. This option isn’t meaningful for all
|
||
|
|
object file formats.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--impure</code></dt>
|
||
|
|
<dd><p>Mark the output file as impure. This option isn’t meaningful for all
|
||
|
|
object file formats.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--prefix-symbols=<var>string</var></code></dt>
|
||
|
|
<dd><p>Prefix all symbols in the output file with <var>string</var>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--prefix-sections=<var>string</var></code></dt>
|
||
|
|
<dd><p>Prefix all section names in the output file with <var>string</var>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--prefix-alloc-sections=<var>string</var></code></dt>
|
||
|
|
<dd><p>Prefix all the names of all allocated sections in the output file with
|
||
|
|
<var>string</var>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--add-gnu-debuglink=<var>path-to-file</var></code></dt>
|
||
|
|
<dd><p>Creates a .gnu_debuglink section which contains a reference to
|
||
|
|
<var>path-to-file</var> and adds it to the output file. Note: the file at
|
||
|
|
<var>path-to-file</var> 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>
|
||
|
|
<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 <samp>--add-gnu-debuglink</samp>
|
||
|
|
option will fail because the installed file does not exist yet.
|
||
|
|
Instead put the debug info file in the current directory and use the
|
||
|
|
<samp>--add-gnu-debuglink</samp> option without any directory components,
|
||
|
|
like this:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"> objcopy --add-gnu-debuglink=foo.debug
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<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:
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>* The same directory as the executable.</code></dt>
|
||
|
|
<dt><code>* A sub-directory of the directory containing the executable</code></dt>
|
||
|
|
<dd><p>called .debug
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>* A global debug directory such as /usr/lib/debug.</code></dt>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--keep-file-symbols</code></dt>
|
||
|
|
<dd><p>When stripping a file, perhaps with <samp>--strip-debug</samp> or
|
||
|
|
<samp>--strip-unneeded</samp>, retain any symbols specifying source file names,
|
||
|
|
which would otherwise get stripped.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--only-keep-debug</code></dt>
|
||
|
|
<dd><p>Strip a file, removing contents of any sections that would not be
|
||
|
|
stripped by <samp>--strip-debug</samp> and leaving the debugging sections
|
||
|
|
intact. In ELF files, this preserves all note sections in the output.
|
||
|
|
</p>
|
||
|
|
<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>
|
||
|
|
<p>The intention is that this option will be used in conjunction with
|
||
|
|
<samp>--add-gnu-debuglink</samp> 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:
|
||
|
|
</p>
|
||
|
|
<ol>
|
||
|
|
<li> Link the executable as normal. Assuming that it is called
|
||
|
|
<code>foo</code> then...
|
||
|
|
</li><li> Run <code>objcopy --only-keep-debug foo foo.dbg</code> to
|
||
|
|
create a file containing the debugging info.
|
||
|
|
</li><li> Run <code>objcopy --strip-debug foo</code> to create a
|
||
|
|
stripped executable.
|
||
|
|
</li><li> Run <code>objcopy --add-gnu-debuglink=foo.dbg foo</code>
|
||
|
|
to add a link to the debugging info into the stripped executable.
|
||
|
|
</li></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:
|
||
|
|
</p>
|
||
|
|
<ol>
|
||
|
|
<li> Link the executable as normal.
|
||
|
|
</li><li> Copy <code>foo</code> to <code>foo.full</code>
|
||
|
|
</li><li> Run <code>objcopy --strip-debug foo</code>
|
||
|
|
</li><li> Run <code>objcopy --add-gnu-debuglink=foo.full foo</code>
|
||
|
|
</li></ol>
|
||
|
|
|
||
|
|
<p>i.e., the file pointed to by the <samp>--add-gnu-debuglink</samp> can be the
|
||
|
|
full executable. It does not have to be a file created by the
|
||
|
|
<samp>--only-keep-debug</samp> switch.
|
||
|
|
</p>
|
||
|
|
<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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--strip-dwo</code></dt>
|
||
|
|
<dd><p>Remove the contents of all DWARF .dwo sections, leaving the
|
||
|
|
remaining debugging sections and all symbols intact.
|
||
|
|
This option is intended for use by the compiler as part of
|
||
|
|
the <samp>-gsplit-dwarf</samp> 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 <samp>--extract-dwo</samp> option to copy the .dwo sections to
|
||
|
|
the .dwo file, then the <samp>--strip-dwo</samp> option to remove
|
||
|
|
those sections from the original .o file.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--extract-dwo</code></dt>
|
||
|
|
<dd><p>Extract the contents of all DWARF .dwo sections. See the
|
||
|
|
<samp>--strip-dwo</samp> option for more information.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--file-alignment <var>num</var></code></dt>
|
||
|
|
<dd><p>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 PE targets.]
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--heap <var>reserve</var></code></dt>
|
||
|
|
<dt><code>--heap <var>reserve</var>,<var>commit</var></code></dt>
|
||
|
|
<dd><p>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 PE targets.]
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--image-base <var>value</var></code></dt>
|
||
|
|
<dd><p>Use <var>value</var> 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 PE targets.]
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--section-alignment <var>num</var></code></dt>
|
||
|
|
<dd><p>Sets the section alignment. Sections in memory will always begin at
|
||
|
|
addresses which are a multiple of this number. Defaults to 0x1000.
|
||
|
|
[This option is specific to PE targets.]
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--stack <var>reserve</var></code></dt>
|
||
|
|
<dt><code>--stack <var>reserve</var>,<var>commit</var></code></dt>
|
||
|
|
<dd><p>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 PE targets.]
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--subsystem <var>which</var></code></dt>
|
||
|
|
<dt><code>--subsystem <var>which</var>:<var>major</var></code></dt>
|
||
|
|
<dt><code>--subsystem <var>which</var>:<var>major</var>.<var>minor</var></code></dt>
|
||
|
|
<dd><p>Specifies the subsystem under which your program will execute. The
|
||
|
|
legal values for <var>which</var> are <code>native</code>, <code>windows</code>,
|
||
|
|
<code>console</code>, <code>posix</code>, <code>efi-app</code>, <code>efi-bsd</code>,
|
||
|
|
<code>efi-rtd</code>, <code>sal-rtd</code>, and <code>xbox</code>. You may optionally set
|
||
|
|
the subsystem version also. Numeric values are also accepted for
|
||
|
|
<var>which</var>.
|
||
|
|
[This option is specific to PE targets.]
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--extract-symbol</code></dt>
|
||
|
|
<dd><p>Keep the file’s section flags and symbols but remove all section data.
|
||
|
|
Specifically, the option:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li> removes the contents of all sections;
|
||
|
|
</li><li> sets the size of every section to zero; and
|
||
|
|
</li><li> sets the file’s start address to zero.
|
||
|
|
</li></ul>
|
||
|
|
|
||
|
|
<p>This option is used to build a <samp>.sym</samp> file for a VxWorks kernel.
|
||
|
|
It can also be a useful way of reducing the size of a <samp>--just-symbols</samp>
|
||
|
|
linker input file.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--compress-debug-sections</code></dt>
|
||
|
|
<dd><p>Compress DWARF debug sections using zlib with SHF_COMPRESSED from the
|
||
|
|
ELF ABI. Note - if compression would actually make a section
|
||
|
|
<em>larger</em>, then it is not compressed.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--compress-debug-sections=none</code></dt>
|
||
|
|
<dt><code>--compress-debug-sections=zlib</code></dt>
|
||
|
|
<dt><code>--compress-debug-sections=zlib-gnu</code></dt>
|
||
|
|
<dt><code>--compress-debug-sections=zlib-gabi</code></dt>
|
||
|
|
<dd><p>For ELF files, these options control how DWARF debug sections are
|
||
|
|
compressed. <samp>--compress-debug-sections=none</samp> is equivalent
|
||
|
|
to <samp>--decompress-debug-sections</samp>.
|
||
|
|
<samp>--compress-debug-sections=zlib</samp> and
|
||
|
|
<samp>--compress-debug-sections=zlib-gabi</samp> are equivalent to
|
||
|
|
<samp>--compress-debug-sections</samp>.
|
||
|
|
<samp>--compress-debug-sections=zlib-gnu</samp> compresses DWARF debug
|
||
|
|
sections using zlib. The debug sections are renamed to begin with
|
||
|
|
‘<samp>.zdebug</samp>’ instead of ‘<samp>.debug</samp>’. Note - if compression would
|
||
|
|
actually make a section <em>larger</em>, then it is not compressed nor
|
||
|
|
renamed.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--decompress-debug-sections</code></dt>
|
||
|
|
<dd><p>Decompress DWARF debug sections using zlib. The original section
|
||
|
|
names of the compressed sections are restored.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--elf-stt-common=yes</code></dt>
|
||
|
|
<dt><code>--elf-stt-common=no</code></dt>
|
||
|
|
<dd><p>For ELF files, these options control whether common symbols should be
|
||
|
|
converted to the <code>STT_COMMON</code> or <code>STT_OBJECT</code> type.
|
||
|
|
<samp>--elf-stt-common=yes</samp> converts common symbol type to
|
||
|
|
<code>STT_COMMON</code>. <samp>--elf-stt-common=no</samp> converts common symbol
|
||
|
|
type to <code>STT_OBJECT</code>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--merge-notes</code></dt>
|
||
|
|
<dt><code>--no-merge-notes</code></dt>
|
||
|
|
<dd><p>For ELF files, attempt (or do not attempt) to reduce the size of any
|
||
|
|
SHT_NOTE type sections by removing duplicate notes.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-V</code></dt>
|
||
|
|
<dt><code>--version</code></dt>
|
||
|
|
<dd><p>Show the version number of <code>objcopy</code>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-v</code></dt>
|
||
|
|
<dt><code>--verbose</code></dt>
|
||
|
|
<dd><p>Verbose output: list all object files modified. In the case of
|
||
|
|
archives, ‘<samp>objcopy -V</samp>’ lists all members of the archive.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--help</code></dt>
|
||
|
|
<dd><p>Show a summary of the options to <code>objcopy</code>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--info</code></dt>
|
||
|
|
<dd><p>Display a list showing all architectures and object formats available.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="objdump.html#objdump" accesskey="n" rel="next">objdump</a>, Previous: <a href="nm.html#nm" accesskey="p" rel="prev">nm</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Binutils-Index.html#Binutils-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|