1<html lang="en"> 2<head> 3<title>objcopy - GNU Binary Utilities</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="GNU Binary Utilities"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="prev" href="nm.html#nm" title="nm"> 9<link rel="next" href="objdump.html#objdump" title="objdump"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 132000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 14Free Software Foundation, Inc. 15 16Permission is granted to copy, distribute and/or modify this document 17under the terms of the GNU Free Documentation License, Version 1.3 18or any later version published by the Free Software Foundation; 19with no Invariant Sections, with no Front-Cover Texts, and with no 20Back-Cover Texts. A copy of the license is included in the 21section entitled ``GNU Free Documentation License''. 22 23--> 24<meta http-equiv="Content-Style-Type" content="text/css"> 25<style type="text/css"><!-- 26 pre.display { font-family:inherit } 27 pre.format { font-family:inherit } 28 pre.smalldisplay { font-family:inherit; font-size:smaller } 29 pre.smallformat { font-family:inherit; font-size:smaller } 30 pre.smallexample { font-size:smaller } 31 pre.smalllisp { font-size:smaller } 32 span.sc { font-variant:small-caps } 33 span.roman { font-family:serif; font-weight:normal; } 34 span.sansserif { font-family:sans-serif; font-weight:normal; } 35--></style> 36<link rel="stylesheet" type="text/css" href="../cs.css"> 37</head> 38<body> 39<div class="node"> 40<a name="objcopy"></a> 41<p> 42Next: <a rel="next" accesskey="n" href="objdump.html#objdump">objdump</a>, 43Previous: <a rel="previous" accesskey="p" href="nm.html#nm">nm</a>, 44Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a> 45<hr> 46</div> 47 48<h2 class="chapter">3 objcopy</h2> 49 50<!-- man title objcopy copy and translate object files --> 51<pre class="smallexample"> <!-- man begin SYNOPSIS objcopy --> 52 objcopy [<samp><span class="option">-F</span></samp> <var>bfdname</var>|<samp><span class="option">--target=</span></samp><var>bfdname</var>] 53 [<samp><span class="option">-I</span></samp> <var>bfdname</var>|<samp><span class="option">--input-target=</span></samp><var>bfdname</var>] 54 [<samp><span class="option">-O</span></samp> <var>bfdname</var>|<samp><span class="option">--output-target=</span></samp><var>bfdname</var>] 55 [<samp><span class="option">-B</span></samp> <var>bfdarch</var>|<samp><span class="option">--binary-architecture=</span></samp><var>bfdarch</var>] 56 [<samp><span class="option">-S</span></samp>|<samp><span class="option">--strip-all</span></samp>] 57 [<samp><span class="option">-g</span></samp>|<samp><span class="option">--strip-debug</span></samp>] 58 [<samp><span class="option">-K</span></samp> <var>symbolname</var>|<samp><span class="option">--keep-symbol=</span></samp><var>symbolname</var>] 59 [<samp><span class="option">-N</span></samp> <var>symbolname</var>|<samp><span class="option">--strip-symbol=</span></samp><var>symbolname</var>] 60 [<samp><span class="option">--strip-unneeded-symbol=</span></samp><var>symbolname</var>] 61 [<samp><span class="option">-G</span></samp> <var>symbolname</var>|<samp><span class="option">--keep-global-symbol=</span></samp><var>symbolname</var>] 62 [<samp><span class="option">--localize-hidden</span></samp>] 63 [<samp><span class="option">-L</span></samp> <var>symbolname</var>|<samp><span class="option">--localize-symbol=</span></samp><var>symbolname</var>] 64 [<samp><span class="option">--globalize-symbol=</span></samp><var>symbolname</var>] 65 [<samp><span class="option">-W</span></samp> <var>symbolname</var>|<samp><span class="option">--weaken-symbol=</span></samp><var>symbolname</var>] 66 [<samp><span class="option">-w</span></samp>|<samp><span class="option">--wildcard</span></samp>] 67 [<samp><span class="option">-x</span></samp>|<samp><span class="option">--discard-all</span></samp>] 68 [<samp><span class="option">-X</span></samp>|<samp><span class="option">--discard-locals</span></samp>] 69 [<samp><span class="option">-b</span></samp> <var>byte</var>|<samp><span class="option">--byte=</span></samp><var>byte</var>] 70 [<samp><span class="option">-i</span></samp> [<var>breadth</var>]|<samp><span class="option">--interleave</span></samp>[=<var>breadth</var>]] 71 [<samp><span class="option">--interleave-width=</span></samp><var>width</var>] 72 [<samp><span class="option">-j</span></samp> <var>sectionname</var>|<samp><span class="option">--only-section=</span></samp><var>sectionname</var>] 73 [<samp><span class="option">-R</span></samp> <var>sectionname</var>|<samp><span class="option">--remove-section=</span></samp><var>sectionname</var>] 74 [<samp><span class="option">-p</span></samp>|<samp><span class="option">--preserve-dates</span></samp>] 75 [<samp><span class="option">--debugging</span></samp>] 76 [<samp><span class="option">--gap-fill=</span></samp><var>val</var>] 77 [<samp><span class="option">--pad-to=</span></samp><var>address</var>] 78 [<samp><span class="option">--set-start=</span></samp><var>val</var>] 79 [<samp><span class="option">--adjust-start=</span></samp><var>incr</var>] 80 [<samp><span class="option">--change-addresses=</span></samp><var>incr</var>] 81 [<samp><span class="option">--change-section-address</span></samp> <var>section</var>{=,+,-}<var>val</var>] 82 [<samp><span class="option">--change-section-lma</span></samp> <var>section</var>{=,+,-}<var>val</var>] 83 [<samp><span class="option">--change-section-vma</span></samp> <var>section</var>{=,+,-}<var>val</var>] 84 [<samp><span class="option">--change-warnings</span></samp>] [<samp><span class="option">--no-change-warnings</span></samp>] 85 [<samp><span class="option">--set-section-flags</span></samp> <var>section</var>=<var>flags</var>] 86 [<samp><span class="option">--add-section</span></samp> <var>sectionname</var>=<var>filename</var>] 87 [<samp><span class="option">--rename-section</span></samp> <var>oldname</var>=<var>newname</var>[,<var>flags</var>]] 88 [<samp><span class="option">--long-section-names</span></samp> {enable,disable,keep}] 89 [<samp><span class="option">--change-leading-char</span></samp>] [<samp><span class="option">--remove-leading-char</span></samp>] 90 [<samp><span class="option">--reverse-bytes=</span></samp><var>num</var>] 91 [<samp><span class="option">--srec-len=</span></samp><var>ival</var>] [<samp><span class="option">--srec-forceS3</span></samp>] 92 [<samp><span class="option">--redefine-sym</span></samp> <var>old</var>=<var>new</var>] 93 [<samp><span class="option">--redefine-syms=</span></samp><var>filename</var>] 94 [<samp><span class="option">--weaken</span></samp>] 95 [<samp><span class="option">--keep-symbols=</span></samp><var>filename</var>] 96 [<samp><span class="option">--strip-symbols=</span></samp><var>filename</var>] 97 [<samp><span class="option">--strip-unneeded-symbols=</span></samp><var>filename</var>] 98 [<samp><span class="option">--keep-global-symbols=</span></samp><var>filename</var>] 99 [<samp><span class="option">--localize-symbols=</span></samp><var>filename</var>] 100 [<samp><span class="option">--globalize-symbols=</span></samp><var>filename</var>] 101 [<samp><span class="option">--weaken-symbols=</span></samp><var>filename</var>] 102 [<samp><span class="option">--alt-machine-code=</span></samp><var>index</var>] 103 [<samp><span class="option">--prefix-symbols=</span></samp><var>string</var>] 104 [<samp><span class="option">--prefix-sections=</span></samp><var>string</var>] 105 [<samp><span class="option">--prefix-alloc-sections=</span></samp><var>string</var>] 106 [<samp><span class="option">--add-gnu-debuglink=</span></samp><var>path-to-file</var>] 107 [<samp><span class="option">--keep-file-symbols</span></samp>] 108 [<samp><span class="option">--only-keep-debug</span></samp>] 109 [<samp><span class="option">--extract-symbol</span></samp>] 110 [<samp><span class="option">--writable-text</span></samp>] 111 [<samp><span class="option">--readonly-text</span></samp>] 112 [<samp><span class="option">--pure</span></samp>] 113 [<samp><span class="option">--impure</span></samp>] 114 [<samp><span class="option">--file-alignment=</span></samp><var>num</var>] 115 [<samp><span class="option">--heap=</span></samp><var>size</var>] 116 [<samp><span class="option">--image-base=</span></samp><var>address</var>] 117 [<samp><span class="option">--section-alignment=</span></samp><var>num</var>] 118 [<samp><span class="option">--stack=</span></samp><var>size</var>] 119 [<samp><span class="option">--subsystem=</span></samp><var>which</var>:<var>major</var>.<var>minor</var>] 120 [<samp><span class="option">--compress-debug-sections</span></samp>] 121 [<samp><span class="option">--decompress-debug-sections</span></samp>] 122 [<samp><span class="option">--dwarf-depth=</span><var>n</var></samp>] 123 [<samp><span class="option">--dwarf-start=</span><var>n</var></samp>] 124 [<samp><span class="option">-v</span></samp>|<samp><span class="option">--verbose</span></samp>] 125 [<samp><span class="option">-V</span></samp>|<samp><span class="option">--version</span></samp>] 126 [<samp><span class="option">--help</span></samp>] [<samp><span class="option">--info</span></samp>] 127 <var>infile</var> [<var>outfile</var>] 128 <!-- man end --> 129</pre> 130<!-- man begin DESCRIPTION objcopy --> 131 <p>The <span class="sc">gnu</span> <samp><span class="command">objcopy</span></samp> utility copies the contents of an object 132file to another. <samp><span class="command">objcopy</span></samp> uses the <span class="sc">gnu</span> <span class="sc">bfd</span> Library to 133read and write the object files. It can write the destination object 134file in a format different from that of the source object file. The 135exact behavior of <samp><span class="command">objcopy</span></samp> is controlled by command-line options. 136Note that <samp><span class="command">objcopy</span></samp> should be able to copy a fully linked file 137between any two formats. However, copying a relocatable object file 138between any two formats may not work as expected. 139 140 <p><samp><span class="command">objcopy</span></samp> creates temporary files to do its translations and 141deletes them afterward. <samp><span class="command">objcopy</span></samp> uses <span class="sc">bfd</span> to do all its 142translation work; it has access to all the formats described in <span class="sc">bfd</span> 143and thus is able to recognize most formats without being told 144explicitly. See <a href="../ld/BFD.html#BFD">BFD</a>. 145 146 <p><samp><span class="command">objcopy</span></samp> can be used to generate S-records by using an output 147target of ‘<samp><span class="samp">srec</span></samp>’ (e.g., use ‘<samp><span class="samp">-O srec</span></samp>’). 148 149 <p><samp><span class="command">objcopy</span></samp> can be used to generate a raw binary file by using an 150output target of ‘<samp><span class="samp">binary</span></samp>’ (e.g., use <samp><span class="option">-O binary</span></samp>). When 151<samp><span class="command">objcopy</span></samp> generates a raw binary file, it will essentially produce 152a memory dump of the contents of the input object file. All symbols and 153relocation information will be discarded. The memory dump will start at 154the load address of the lowest section copied into the output file. 155 156 <p>When generating an S-record or a raw binary file, it may be helpful to 157use <samp><span class="option">-S</span></samp> to remove sections containing debugging information. In 158some cases <samp><span class="option">-R</span></samp> will be useful to remove sections which contain 159information that is not needed by the binary file. 160 161 <p>Note—<samp><span class="command">objcopy</span></samp> is not able to change the endianness of its input 162files. If the input format has an endianness (some formats do not), 163<samp><span class="command">objcopy</span></samp> can only copy the inputs into file formats that have the 164same endianness or which have no endianness (e.g., ‘<samp><span class="samp">srec</span></samp>’). 165(However, see the <samp><span class="option">--reverse-bytes</span></samp> option.) 166 167<!-- man end --> 168<!-- man begin OPTIONS objcopy --> 169 <dl> 170<dt><samp><var>infile</var></samp><dt><samp><var>outfile</var></samp><dd>The input and output files, respectively. 171If you do not specify <var>outfile</var>, <samp><span class="command">objcopy</span></samp> creates a 172temporary file and destructively renames the result with 173the name of <var>infile</var>. 174 175 <br><dt><samp><span class="env">-I </span><var>bfdname</var></samp><dt><samp><span class="env">--input-target=</span><var>bfdname</var></samp><dd>Consider the source file's object format to be <var>bfdname</var>, rather than 176attempting to deduce it. See <a href="Target-Selection.html#Target-Selection">Target Selection</a>, for more information. 177 178 <br><dt><samp><span class="env">-O </span><var>bfdname</var></samp><dt><samp><span class="env">--output-target=</span><var>bfdname</var></samp><dd>Write the output file using the object format <var>bfdname</var>. 179See <a href="Target-Selection.html#Target-Selection">Target Selection</a>, for more information. 180 181 <br><dt><samp><span class="env">-F </span><var>bfdname</var></samp><dt><samp><span class="env">--target=</span><var>bfdname</var></samp><dd>Use <var>bfdname</var> as the object format for both the input and the output 182file; i.e., simply transfer data from source to destination with no 183translation. See <a href="Target-Selection.html#Target-Selection">Target Selection</a>, for more information. 184 185 <br><dt><samp><span class="env">-B </span><var>bfdarch</var></samp><dt><samp><span class="env">--binary-architecture=</span><var>bfdarch</var></samp><dd>Useful when transforming a architecture-less input file into an object file. 186In this case the output architecture can be set to <var>bfdarch</var>. This 187option will be ignored if the input file has a known <var>bfdarch</var>. You 188can access this binary data inside a program by referencing the special 189symbols that are created by the conversion process. These symbols are 190called _binary_<var>objfile</var>_start, _binary_<var>objfile</var>_end and 191_binary_<var>objfile</var>_size. e.g. you can transform a picture file into 192an object file and then access it in your code using these symbols. 193 194 <br><dt><samp><span class="env">-j </span><var>sectionname</var></samp><dt><samp><span class="env">--only-section=</span><var>sectionname</var></samp><dd>Copy only the named section from the input file to the output file. 195This option may be given more than once. Note that using this option 196inappropriately may make the output file unusable. 197 198 <br><dt><samp><span class="env">-R </span><var>sectionname</var></samp><dt><samp><span class="env">--remove-section=</span><var>sectionname</var></samp><dd>Remove any section named <var>sectionname</var> from the output file. This 199option may be given more than once. Note that using this option 200inappropriately may make the output file unusable. 201 202 <br><dt><samp><span class="env">-S</span></samp><dt><samp><span class="env">--strip-all</span></samp><dd>Do not copy relocation and symbol information from the source file. 203 204 <br><dt><samp><span class="env">-g</span></samp><dt><samp><span class="env">--strip-debug</span></samp><dd>Do not copy debugging symbols or sections from the source file. 205 206 <br><dt><samp><span class="env">--strip-unneeded</span></samp><dd>Strip all symbols that are not needed for relocation processing. 207 208 <br><dt><samp><span class="env">-K </span><var>symbolname</var></samp><dt><samp><span class="env">--keep-symbol=</span><var>symbolname</var></samp><dd>When stripping symbols, keep symbol <var>symbolname</var> even if it would 209normally be stripped. This option may be given more than once. 210 211 <br><dt><samp><span class="env">-N </span><var>symbolname</var></samp><dt><samp><span class="env">--strip-symbol=</span><var>symbolname</var></samp><dd>Do not copy symbol <var>symbolname</var> from the source file. This option 212may be given more than once. 213 214 <br><dt><samp><span class="env">--strip-unneeded-symbol=</span><var>symbolname</var></samp><dd>Do not copy symbol <var>symbolname</var> from the source file unless it is needed 215by a relocation. This option may be given more than once. 216 217 <br><dt><samp><span class="env">-G </span><var>symbolname</var></samp><dt><samp><span class="env">--keep-global-symbol=</span><var>symbolname</var></samp><dd>Keep only symbol <var>symbolname</var> global. Make all other symbols local 218to the file, so that they are not visible externally. This option may 219be given more than once. 220 221 <br><dt><samp><span class="env">--localize-hidden</span></samp><dd>In an ELF object, mark all symbols that have hidden or internal visibility 222as local. This option applies on top of symbol-specific localization options 223such as <samp><span class="option">-L</span></samp>. 224 225 <br><dt><samp><span class="env">-L </span><var>symbolname</var></samp><dt><samp><span class="env">--localize-symbol=</span><var>symbolname</var></samp><dd>Make symbol <var>symbolname</var> local to the file, so that it is not 226visible externally. This option may be given more than once. 227 228 <br><dt><samp><span class="env">-W </span><var>symbolname</var></samp><dt><samp><span class="env">--weaken-symbol=</span><var>symbolname</var></samp><dd>Make symbol <var>symbolname</var> weak. This option may be given more than once. 229 230 <br><dt><samp><span class="env">--globalize-symbol=</span><var>symbolname</var></samp><dd>Give symbol <var>symbolname</var> global scoping so that it is visible 231outside of the file in which it is defined. This option may be given 232more than once. 233 234 <br><dt><samp><span class="env">-w</span></samp><dt><samp><span class="env">--wildcard</span></samp><dd>Permit regular expressions in <var>symbolname</var>s used in other command 235line options. The question mark (?), asterisk (*), backslash (\) and 236square brackets ([]) operators can be used anywhere in the symbol 237name. If the first character of the symbol name is the exclamation 238point (!) then the sense of the switch is reversed for that symbol. 239For example: 240 241 <pre class="smallexample"> -w -W !foo -W fo* 242</pre> 243 <p>would cause objcopy to weaken all symbols that start with “fo” 244except for the symbol “foo”. 245 246 <br><dt><samp><span class="env">-x</span></samp><dt><samp><span class="env">--discard-all</span></samp><dd>Do not copy non-global symbols from the source file. 247<!-- FIXME any reason to prefer "non-global" to "local" here? --> 248 249 <br><dt><samp><span class="env">-X</span></samp><dt><samp><span class="env">--discard-locals</span></samp><dd>Do not copy compiler-generated local symbols. 250(These usually start with ‘<samp><span class="samp">L</span></samp>’ or ‘<samp><span class="samp">.</span></samp>’.) 251 252 <br><dt><samp><span class="env">-b </span><var>byte</var></samp><dt><samp><span class="env">--byte=</span><var>byte</var></samp><dd>If interleaving has been enabled via the <samp><span class="option">--interleave</span></samp> option 253then start the range of bytes to keep at the <var>byte</var>th byte. 254<var>byte</var> can be in the range from 0 to <var>breadth</var>-1, where 255<var>breadth</var> is the value given by the <samp><span class="option">--interleave</span></samp> option. 256 257 <br><dt><samp><span class="env">-i [</span><var>breadth</var><span class="env">]</span></samp><dt><samp><span class="env">--interleave[=</span><var>breadth</var><span class="env">]</span></samp><dd>Only copy a range out of every <var>breadth</var> bytes. (Header data is 258not affected). Select which byte in the range begins the copy with 259the <samp><span class="option">--byte</span></samp> option. Select the width of the range with the 260<samp><span class="option">--interleave-width</span></samp> option. 261 262 <p>This option is useful for creating files to program <span class="sc">rom</span>. It is 263typically used with an <code>srec</code> output target. Note that 264<samp><span class="command">objcopy</span></samp> will complain if you do not specify the 265<samp><span class="option">--byte</span></samp> option as well. 266 267 <p>The default interleave breadth is 4, so with <samp><span class="option">--byte</span></samp> set to 0, 268<samp><span class="command">objcopy</span></samp> would copy the first byte out of every four bytes 269from the input to the output. 270 271 <br><dt><samp><span class="env">--interleave-width=</span><var>width</var></samp><dd>When used with the <samp><span class="option">--interleave</span></samp> option, copy <var>width</var> 272bytes at a time. The start of the range of bytes to be copied is set 273by the <samp><span class="option">--byte</span></samp> option, and the extent of the range is set with 274the <samp><span class="option">--interleave</span></samp> option. 275 276 <p>The default value for this option is 1. The value of <var>width</var> plus 277the <var>byte</var> value set by the <samp><span class="option">--byte</span></samp> option must not exceed 278the interleave breadth set by the <samp><span class="option">--interleave</span></samp> option. 279 280 <p>This option can be used to create images for two 16-bit flashes interleaved 281in a 32-bit bus by passing <samp><span class="option">-b 0 -i 4 --interleave-width=2</span></samp> 282and <samp><span class="option">-b 2 -i 4 --interleave-width=2</span></samp> to two <samp><span class="command">objcopy</span></samp> 283commands. If the input was '12345678' then the outputs would be 284'1256' and '3478' respectively. 285 286 <br><dt><samp><span class="env">-p</span></samp><dt><samp><span class="env">--preserve-dates</span></samp><dd>Set the access and modification dates of the output file to be the same 287as those of the input file. 288 289 <br><dt><samp><span class="env">--debugging</span></samp><dd>Convert debugging information, if possible. This is not the default 290because only certain debugging formats are supported, and the 291conversion process can be time consuming. 292 293 <br><dt><samp><span class="env">--gap-fill </span><var>val</var></samp><dd>Fill gaps between sections with <var>val</var>. This operation applies to 294the <em>load address</em> (LMA) of the sections. It is done by increasing 295the size of the section with the lower address, and filling in the extra 296space created with <var>val</var>. 297 298 <br><dt><samp><span class="env">--pad-to </span><var>address</var></samp><dd>Pad the output file up to the load address <var>address</var>. This is 299done by increasing the size of the last section. The extra space is 300filled in with the value specified by <samp><span class="option">--gap-fill</span></samp> (default zero). 301 302 <br><dt><samp><span class="env">--set-start </span><var>val</var></samp><dd>Set the start address of the new file to <var>val</var>. Not all object file 303formats support setting the start address. 304 305 <br><dt><samp><span class="env">--change-start </span><var>incr</var></samp><dt><samp><span class="env">--adjust-start </span><var>incr</var></samp><dd><a name="index-changing-start-address-55"></a>Change the start address by adding <var>incr</var>. Not all object file 306formats support setting the start address. 307 308 <br><dt><samp><span class="env">--change-addresses </span><var>incr</var></samp><dt><samp><span class="env">--adjust-vma </span><var>incr</var></samp><dd><a name="index-changing-object-addresses-56"></a>Change the VMA and LMA addresses of all sections, as well as the start 309address, by adding <var>incr</var>. Some object file formats do not permit 310section addresses to be changed arbitrarily. Note that this does not 311relocate the sections; if the program expects sections to be loaded at a 312certain address, and this option is used to change the sections such 313that they are loaded at a different address, the program may fail. 314 315 <br><dt><samp><span class="env">--change-section-address </span><var>section</var><span class="env">{=,+,-}</span><var>val</var></samp><dt><samp><span class="env">--adjust-section-vma </span><var>section</var><span class="env">{=,+,-}</span><var>val</var></samp><dd><a name="index-changing-section-address-57"></a>Set or change both the VMA address and the LMA address of the named 316<var>section</var>. If ‘<samp><span class="samp">=</span></samp>’ is used, the section address is set to 317<var>val</var>. Otherwise, <var>val</var> is added to or subtracted from the 318section address. See the comments under <samp><span class="option">--change-addresses</span></samp>, 319above. If <var>section</var> does not exist in the input file, a warning will 320be issued, unless <samp><span class="option">--no-change-warnings</span></samp> is used. 321 322 <br><dt><samp><span class="env">--change-section-lma </span><var>section</var><span class="env">{=,+,-}</span><var>val</var></samp><dd><a name="index-changing-section-LMA-58"></a>Set or change the LMA address of the named <var>section</var>. The LMA 323address is the address where the section will be loaded into memory at 324program load time. Normally this is the same as the VMA address, which 325is the address of the section at program run time, but on some systems, 326especially those where a program is held in ROM, the two can be 327different. If ‘<samp><span class="samp">=</span></samp>’ is used, the section address is set to 328<var>val</var>. Otherwise, <var>val</var> is added to or subtracted from the 329section address. See the comments under <samp><span class="option">--change-addresses</span></samp>, 330above. If <var>section</var> does not exist in the input file, a warning 331will be issued, unless <samp><span class="option">--no-change-warnings</span></samp> is used. 332 333 <br><dt><samp><span class="env">--change-section-vma </span><var>section</var><span class="env">{=,+,-}</span><var>val</var></samp><dd><a name="index-changing-section-VMA-59"></a>Set or change the VMA address of the named <var>section</var>. The VMA 334address is the address where the section will be located once the 335program has started executing. Normally this is the same as the LMA 336address, which is the address where the section will be loaded into 337memory, but on some systems, especially those where a program is held in 338ROM, the two can be different. If ‘<samp><span class="samp">=</span></samp>’ is used, the section address 339is set to <var>val</var>. Otherwise, <var>val</var> is added to or subtracted 340from the section address. See the comments under 341<samp><span class="option">--change-addresses</span></samp>, above. If <var>section</var> does not exist in 342the input file, a warning will be issued, unless 343<samp><span class="option">--no-change-warnings</span></samp> is used. 344 345 <br><dt><samp><span class="env">--change-warnings</span></samp><dt><samp><span class="env">--adjust-warnings</span></samp><dd>If <samp><span class="option">--change-section-address</span></samp> or <samp><span class="option">--change-section-lma</span></samp> or 346<samp><span class="option">--change-section-vma</span></samp> is used, and the named section does not 347exist, issue a warning. This is the default. 348 349 <br><dt><samp><span class="env">--no-change-warnings</span></samp><dt><samp><span class="env">--no-adjust-warnings</span></samp><dd>Do not issue a warning if <samp><span class="option">--change-section-address</span></samp> or 350<samp><span class="option">--adjust-section-lma</span></samp> or <samp><span class="option">--adjust-section-vma</span></samp> is used, even 351if the named section does not exist. 352 353 <br><dt><samp><span class="env">--set-section-flags </span><var>section</var><span class="env">=</span><var>flags</var></samp><dd>Set the flags for the named section. The <var>flags</var> argument is a 354comma separated string of flag names. The recognized names are 355‘<samp><span class="samp">alloc</span></samp>’, ‘<samp><span class="samp">contents</span></samp>’, ‘<samp><span class="samp">load</span></samp>’, ‘<samp><span class="samp">noload</span></samp>’, 356‘<samp><span class="samp">readonly</span></samp>’, ‘<samp><span class="samp">code</span></samp>’, ‘<samp><span class="samp">data</span></samp>’, ‘<samp><span class="samp">rom</span></samp>’, ‘<samp><span class="samp">share</span></samp>’, and 357‘<samp><span class="samp">debug</span></samp>’. You can set the ‘<samp><span class="samp">contents</span></samp>’ flag for a section which 358does not have contents, but it is not meaningful to clear the 359‘<samp><span class="samp">contents</span></samp>’ flag of a section which does have contents–just remove 360the section instead. Not all flags are meaningful for all object file 361formats. 362 363 <br><dt><samp><span class="env">--add-section </span><var>sectionname</var><span class="env">=</span><var>filename</var></samp><dd>Add a new section named <var>sectionname</var> while copying the file. The 364contents of the new section are taken from the file <var>filename</var>. The 365size of the section will be the size of the file. This option only 366works on file formats which can support sections with arbitrary names. 367 368 <br><dt><samp><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></samp><dd>Rename a section from <var>oldname</var> to <var>newname</var>, optionally 369changing the section's flags to <var>flags</var> in the process. This has 370the advantage over usng a linker script to perform the rename in that 371the output stays as an object file and does not become a linked 372executable. 373 374 <p>This option is particularly helpful when the input format is binary, 375since this will always create a section called .data. If for example, 376you wanted instead to create a section called .rodata containing binary 377data you could use the following command line to achieve it: 378 379 <pre class="smallexample"> objcopy -I binary -O <output_format> -B <architecture> \ 380 --rename-section .data=.rodata,alloc,load,readonly,data,contents \ 381 <input_binary_file> <output_object_file> 382</pre> 383 <br><dt><samp><span class="env">--long-section-names {enable,disable,keep}</span></samp><dd>Controls the handling of long section names when processing <code>COFF</code> 384and <code>PE-COFF</code> object formats. The default behaviour, ‘<samp><span class="samp">keep</span></samp>’, 385is to preserve long section names if any are present in the input file. 386The ‘<samp><span class="samp">enable</span></samp>’ and ‘<samp><span class="samp">disable</span></samp>’ options forcibly enable or disable 387the use of long section names in the output object; when ‘<samp><span class="samp">disable</span></samp>’ 388is in effect, any long section names in the input object will be truncated. 389The ‘<samp><span class="samp">enable</span></samp>’ option will only emit long section names if any are 390present in the inputs; this is mostly the same as ‘<samp><span class="samp">keep</span></samp>’, but it 391is left undefined whether the ‘<samp><span class="samp">enable</span></samp>’ option might force the 392creation of an empty string table in the output file. 393 394 <br><dt><samp><span class="env">--change-leading-char</span></samp><dd>Some object file formats use special characters at the start of 395symbols. The most common such character is underscore, which compilers 396often add before every symbol. This option tells <samp><span class="command">objcopy</span></samp> to 397change the leading character of every symbol when it converts between 398object file formats. If the object file formats use the same leading 399character, this option has no effect. Otherwise, it will add a 400character, or remove a character, or change a character, as 401appropriate. 402 403 <br><dt><samp><span class="env">--remove-leading-char</span></samp><dd>If the first character of a global symbol is a special symbol leading 404character used by the object file format, remove the character. The 405most common symbol leading character is underscore. This option will 406remove a leading underscore from all global symbols. This can be useful 407if you want to link together objects of different file formats with 408different conventions for symbol names. This is different from 409<samp><span class="option">--change-leading-char</span></samp> because it always changes the symbol name 410when appropriate, regardless of the object file format of the output 411file. 412 413 <br><dt><samp><span class="env">--reverse-bytes=</span><var>num</var></samp><dd>Reverse the bytes in a section with output contents. A section length must 414be evenly divisible by the value given in order for the swap to be able to 415take place. Reversing takes place before the interleaving is performed. 416 417 <p>This option is used typically in generating ROM images for problematic 418target systems. For example, on some target boards, the 32-bit words 419fetched from 8-bit ROMs are re-assembled in little-endian byte order 420regardless of the CPU byte order. Depending on the programming model, the 421endianness of the ROM may need to be modified. 422 423 <p>Consider a simple file with a section containing the following eight 424bytes: <code>12345678</code>. 425 426 <p>Using ‘<samp><span class="samp">--reverse-bytes=2</span></samp>’ for the above example, the bytes in the 427output file would be ordered <code>21436587</code>. 428 429 <p>Using ‘<samp><span class="samp">--reverse-bytes=4</span></samp>’ for the above example, the bytes in the 430output file would be ordered <code>43218765</code>. 431 432 <p>By using ‘<samp><span class="samp">--reverse-bytes=2</span></samp>’ for the above example, followed by 433‘<samp><span class="samp">--reverse-bytes=4</span></samp>’ on the output file, the bytes in the second 434output file would be ordered <code>34127856</code>. 435 436 <br><dt><samp><span class="env">--srec-len=</span><var>ival</var></samp><dd>Meaningful only for srec output. Set the maximum length of the Srecords 437being produced to <var>ival</var>. This length covers both address, data and 438crc fields. 439 440 <br><dt><samp><span class="env">--srec-forceS3</span></samp><dd>Meaningful only for srec output. Avoid generation of S1/S2 records, 441creating S3-only record format. 442 443 <br><dt><samp><span class="env">--redefine-sym </span><var>old</var><span class="env">=</span><var>new</var></samp><dd>Change the name of a symbol <var>old</var>, to <var>new</var>. This can be useful 444when one is trying link two things together for which you have no 445source, and there are name collisions. 446 447 <br><dt><samp><span class="env">--redefine-syms=</span><var>filename</var></samp><dd>Apply <samp><span class="option">--redefine-sym</span></samp> to each symbol pair "<var>old</var> <var>new</var>" 448listed in the file <var>filename</var>. <var>filename</var> is simply a flat file, 449with one symbol pair per line. Line comments may be introduced by the hash 450character. This option may be given more than once. 451 452 <br><dt><samp><span class="env">--weaken</span></samp><dd>Change all global symbols in the file to be weak. This can be useful 453when building an object which will be linked against other objects using 454the <samp><span class="option">-R</span></samp> option to the linker. This option is only effective when 455using an object file format which supports weak symbols. 456 457 <br><dt><samp><span class="env">--keep-symbols=</span><var>filename</var></samp><dd>Apply <samp><span class="option">--keep-symbol</span></samp> option to each symbol listed in the file 458<var>filename</var>. <var>filename</var> is simply a flat file, with one symbol 459name per line. Line comments may be introduced by the hash character. 460This option may be given more than once. 461 462 <br><dt><samp><span class="env">--strip-symbols=</span><var>filename</var></samp><dd>Apply <samp><span class="option">--strip-symbol</span></samp> option to each symbol listed in the file 463<var>filename</var>. <var>filename</var> is simply a flat file, with one symbol 464name per line. Line comments may be introduced by the hash character. 465This option may be given more than once. 466 467 <br><dt><samp><span class="env">--strip-unneeded-symbols=</span><var>filename</var></samp><dd>Apply <samp><span class="option">--strip-unneeded-symbol</span></samp> option to each symbol listed in 468the file <var>filename</var>. <var>filename</var> is simply a flat file, with one 469symbol name per line. Line comments may be introduced by the hash 470character. This option may be given more than once. 471 472 <br><dt><samp><span class="env">--keep-global-symbols=</span><var>filename</var></samp><dd>Apply <samp><span class="option">--keep-global-symbol</span></samp> option to each symbol listed in the 473file <var>filename</var>. <var>filename</var> is simply a flat file, with one 474symbol name per line. Line comments may be introduced by the hash 475character. This option may be given more than once. 476 477 <br><dt><samp><span class="env">--localize-symbols=</span><var>filename</var></samp><dd>Apply <samp><span class="option">--localize-symbol</span></samp> option to each symbol listed in the file 478<var>filename</var>. <var>filename</var> is simply a flat file, with one symbol 479name per line. Line comments may be introduced by the hash character. 480This option may be given more than once. 481 482 <br><dt><samp><span class="env">--globalize-symbols=</span><var>filename</var></samp><dd>Apply <samp><span class="option">--globalize-symbol</span></samp> option to each symbol listed in the file 483<var>filename</var>. <var>filename</var> is simply a flat file, with one symbol 484name per line. Line comments may be introduced by the hash character. 485This option may be given more than once. 486 487 <br><dt><samp><span class="env">--weaken-symbols=</span><var>filename</var></samp><dd>Apply <samp><span class="option">--weaken-symbol</span></samp> option to each symbol listed in the file 488<var>filename</var>. <var>filename</var> is simply a flat file, with one symbol 489name per line. Line comments may be introduced by the hash character. 490This option may be given more than once. 491 492 <br><dt><samp><span class="env">--alt-machine-code=</span><var>index</var></samp><dd>If the output architecture has alternate machine codes, use the 493<var>index</var>th code instead of the default one. This is useful in case 494a machine is assigned an official code and the tool-chain adopts the 495new code, but other applications still depend on the original code 496being used. For ELF based architectures if the <var>index</var> 497alternative does not exist then the value is treated as an absolute 498number to be stored in the e_machine field of the ELF header. 499 500 <br><dt><samp><span class="env">--writable-text</span></samp><dd>Mark the output text as writable. This option isn't meaningful for all 501object file formats. 502 503 <br><dt><samp><span class="env">--readonly-text</span></samp><dd>Make the output text write protected. This option isn't meaningful for all 504object file formats. 505 506 <br><dt><samp><span class="env">--pure</span></samp><dd>Mark the output file as demand paged. This option isn't meaningful for all 507object file formats. 508 509 <br><dt><samp><span class="env">--impure</span></samp><dd>Mark the output file as impure. This option isn't meaningful for all 510object file formats. 511 512 <br><dt><samp><span class="env">--prefix-symbols=</span><var>string</var></samp><dd>Prefix all symbols in the output file with <var>string</var>. 513 514 <br><dt><samp><span class="env">--prefix-sections=</span><var>string</var></samp><dd>Prefix all section names in the output file with <var>string</var>. 515 516 <br><dt><samp><span class="env">--prefix-alloc-sections=</span><var>string</var></samp><dd>Prefix all the names of all allocated sections in the output file with 517<var>string</var>. 518 519 <br><dt><samp><span class="env">--add-gnu-debuglink=</span><var>path-to-file</var></samp><dd>Creates a .gnu_debuglink section which contains a reference to <var>path-to-file</var> 520and adds it to the output file. 521 522 <br><dt><samp><span class="env">--keep-file-symbols</span></samp><dd>When stripping a file, perhaps with <samp><span class="option">--strip-debug</span></samp> or 523<samp><span class="option">--strip-unneeded</span></samp>, retain any symbols specifying source file names, 524which would otherwise get stripped. 525 526 <br><dt><samp><span class="env">--only-keep-debug</span></samp><dd>Strip a file, removing contents of any sections that would not be 527stripped by <samp><span class="option">--strip-debug</span></samp> and leaving the debugging sections 528intact. In ELF files, this preserves all note sections in the output. 529 530 <p>The intention is that this option will be used in conjunction with 531<samp><span class="option">--add-gnu-debuglink</span></samp> to create a two part executable. One a 532stripped binary which will occupy less space in RAM and in a 533distribution and the second a debugging information file which is only 534needed if debugging abilities are required. The suggested procedure 535to create these files is as follows: 536 537 <ol type=1 start=1> 538<li>Link the executable as normal. Assuming that is is called 539<code>foo</code> then... 540<li>Run <code>objcopy --only-keep-debug foo foo.dbg</code> to 541create a file containing the debugging info. 542<li>Run <code>objcopy --strip-debug foo</code> to create a 543stripped executable. 544<li>Run <code>objcopy --add-gnu-debuglink=foo.dbg foo</code> 545to add a link to the debugging info into the stripped executable. 546 </ol> 547 548 <p>Note—the choice of <code>.dbg</code> as an extension for the debug info 549file is arbitrary. Also the <code>--only-keep-debug</code> step is 550optional. You could instead do this: 551 552 <ol type=1 start=1> 553<li>Link the executable as normal. 554<li>Copy <code>foo</code> to <code>foo.full</code> 555<li>Run <code>objcopy --strip-debug foo</code> 556<li>Run <code>objcopy --add-gnu-debuglink=foo.full foo</code> 557 </ol> 558 559 <p>i.e., the file pointed to by the <samp><span class="option">--add-gnu-debuglink</span></samp> can be the 560full executable. It does not have to be a file created by the 561<samp><span class="option">--only-keep-debug</span></samp> switch. 562 563 <p>Note—this switch is only intended for use on fully linked files. It 564does not make sense to use it on object files where the debugging 565information may be incomplete. Besides the gnu_debuglink feature 566currently only supports the presence of one filename containing 567debugging information, not multiple filenames on a one-per-object-file 568basis. 569 570 <br><dt><samp><span class="env">--file-alignment </span><var>num</var></samp><dd>Specify the file alignment. Sections in the file will always begin at 571file offsets which are multiples of this number. This defaults to 572512. 573[This option is specific to PE targets.] 574 575 <br><dt><samp><span class="env">--heap </span><var>reserve</var></samp><dt><samp><span class="env">--heap </span><var>reserve</var><span class="env">,</span><var>commit</var></samp><dd>Specify the number of bytes of memory to reserve (and optionally commit) 576to be used as heap for this program. 577[This option is specific to PE targets.] 578 579 <br><dt><samp><span class="env">--image-base </span><var>value</var></samp><dd>Use <var>value</var> as the base address of your program or dll. This is 580the lowest memory location that will be used when your program or dll 581is loaded. To reduce the need to relocate and improve performance of 582your dlls, each should have a unique base address and not overlap any 583other dlls. The default is 0x400000 for executables, and 0x10000000 584for dlls. 585[This option is specific to PE targets.] 586 587 <br><dt><samp><span class="env">--section-alignment </span><var>num</var></samp><dd>Sets the section alignment. Sections in memory will always begin at 588addresses which are a multiple of this number. Defaults to 0x1000. 589[This option is specific to PE targets.] 590 591 <br><dt><samp><span class="env">--stack </span><var>reserve</var></samp><dt><samp><span class="env">--stack </span><var>reserve</var><span class="env">,</span><var>commit</var></samp><dd>Specify the number of bytes of memory to reserve (and optionally commit) 592to be used as stack for this program. 593[This option is specific to PE targets.] 594 595 <br><dt><samp><span class="env">--subsystem </span><var>which</var></samp><dt><samp><span class="env">--subsystem </span><var>which</var><span class="env">:</span><var>major</var></samp><dt><samp><span class="env">--subsystem </span><var>which</var><span class="env">:</span><var>major</var><span class="env">.</span><var>minor</var></samp><dd>Specifies the subsystem under which your program will execute. The 596legal values for <var>which</var> are <code>native</code>, <code>windows</code>, 597<code>console</code>, <code>posix</code>, <code>efi-app</code>, <code>efi-bsd</code>, 598<code>efi-rtd</code>, <code>sal-rtd</code>, and <code>xbox</code>. You may optionally set 599the subsystem version also. Numeric values are also accepted for 600<var>which</var>. 601[This option is specific to PE targets.] 602 603 <br><dt><samp><span class="env">--extract-symbol</span></samp><dd>Keep the file's section flags and symbols but remove all section data. 604Specifically, the option: 605 606 <ul> 607<li>removes the contents of all sections; 608<li>sets the size of every section to zero; and 609<li>sets the file's start address to zero. 610</ul> 611 612 <p>This option is used to build a <samp><span class="file">.sym</span></samp> file for a VxWorks kernel. 613It can also be a useful way of reducing the size of a <samp><span class="option">--just-symbols</span></samp> 614linker input file. 615 616 <br><dt><samp><span class="env">--compress-debug-sections</span></samp><dd>Compress DWARF debug sections using zlib. 617 618 <br><dt><samp><span class="env">--decompress-debug-sections</span></samp><dd>Decompress DWARF debug sections using zlib. 619 620 <br><dt><samp><span class="env">-V</span></samp><dt><samp><span class="env">--version</span></samp><dd>Show the version number of <samp><span class="command">objcopy</span></samp>. 621 622 <br><dt><samp><span class="env">-v</span></samp><dt><samp><span class="env">--verbose</span></samp><dd>Verbose output: list all object files modified. In the case of 623archives, ‘<samp><span class="samp">objcopy -V</span></samp>’ lists all members of the archive. 624 625 <br><dt><samp><span class="env">--help</span></samp><dd>Show a summary of the options to <samp><span class="command">objcopy</span></samp>. 626 627 <br><dt><samp><span class="env">--info</span></samp><dd>Display a list showing all architectures and object formats available. 628</dl> 629 630<!-- man end --> 631 </body></html> 632 633