| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "OBJCOPY 1" |
| 58 |
.TH OBJCOPY 1 2026-03-05 binutils-2.46 "GNU Development Tools" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
objcopy \- copy and translate object files |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
objcopy [\fB\-F\fR \fIbfdname\fR|\fB\-\-target=\fR\fIbfdname\fR] |
| 68 |
[\fB\-I\fR \fIbfdname\fR|\fB\-\-input\-target=\fR\fIbfdname\fR] |
| 69 |
[\fB\-O\fR \fIbfdname\fR|\fB\-\-output\-target=\fR\fIbfdname\fR] |
| 70 |
[\fB\-B\fR \fIbfdarch\fR|\fB\-\-binary\-architecture=\fR\fIbfdarch\fR] |
| 71 |
[\fB\-S\fR|\fB\-\-strip\-all\fR] |
| 72 |
[\fB\-g\fR|\fB\-\-strip\-debug\fR] |
| 73 |
[\fB\-\-strip\-unneeded\fR] |
| 74 |
[\fB\-K\fR \fIsymbolname\fR|\fB\-\-keep\-symbol=\fR\fIsymbolname\fR] |
| 75 |
[\fB\-\-keep\-file\-symbols\fR] |
| 76 |
[\fB\-\-keep\-section\-symbols\fR] |
| 77 |
[\fB\-N\fR \fIsymbolname\fR|\fB\-\-strip\-symbol=\fR\fIsymbolname\fR] |
| 78 |
[\fB\-\-strip\-unneeded\-symbol=\fR\fIsymbolname\fR] |
| 79 |
[\fB\-G\fR \fIsymbolname\fR|\fB\-\-keep\-global\-symbol=\fR\fIsymbolname\fR] |
| 80 |
[\fB\-\-localize\-hidden\fR] |
| 81 |
[\fB\-L\fR \fIsymbolname\fR|\fB\-\-localize\-symbol=\fR\fIsymbolname\fR] |
| 82 |
[\fB\-\-globalize\-symbol=\fR\fIsymbolname\fR] |
| 83 |
[\fB\-\-globalize\-symbols=\fR\fIfilename\fR] |
| 84 |
[\fB\-W\fR \fIsymbolname\fR|\fB\-\-weaken\-symbol=\fR\fIsymbolname\fR] |
| 85 |
[\fB\-w\fR|\fB\-\-wildcard\fR] |
| 86 |
[\fB\-x\fR|\fB\-\-discard\-all\fR] |
| 87 |
[\fB\-X\fR|\fB\-\-discard\-locals\fR] |
| 88 |
[\fB\-b\fR \fIbyte\fR|\fB\-\-byte=\fR\fIbyte\fR] |
| 89 |
[\fB\-i\fR [\fIbreadth\fR]|\fB\-\-interleave\fR[=\fIbreadth\fR]] |
| 90 |
[\fB\-\-interleave\-width=\fR\fIwidth\fR] |
| 91 |
[\fB\-j\fR \fIsectionpattern\fR|\fB\-\-only\-section=\fR\fIsectionpattern\fR] |
| 92 |
[\fB\-R\fR \fIsectionpattern\fR|\fB\-\-remove\-section=\fR\fIsectionpattern\fR] |
| 93 |
[\fB\-\-keep\-section=\fR\fIsectionpattern\fR] |
| 94 |
[\fB\-\-remove\-relocations=\fR\fIsectionpattern\fR] |
| 95 |
[\fB\-\-strip\-section\-headers\fR] |
| 96 |
[\fB\-p\fR|\fB\-\-preserve\-dates\fR] |
| 97 |
[\fB\-D\fR|\fB\-\-enable\-deterministic\-archives\fR] |
| 98 |
[\fB\-U\fR|\fB\-\-disable\-deterministic\-archives\fR] |
| 99 |
[\fB\-\-debugging\fR] |
| 100 |
[\fB\-\-gap\-fill=\fR\fIval\fR] |
| 101 |
[\fB\-\-pad\-to=\fR\fIaddress\fR] |
| 102 |
[\fB\-\-set\-start=\fR\fIval\fR] |
| 103 |
[\fB\-\-adjust\-start=\fR\fIincr\fR] |
| 104 |
[\fB\-\-change\-addresses=\fR\fIincr\fR] |
| 105 |
[\fB\-\-change\-section\-address\fR \fIsectionpattern\fR{=,+,\-}\fIval\fR] |
| 106 |
[\fB\-\-change\-section\-lma\fR \fIsectionpattern\fR{=,+,\-}\fIval\fR] |
| 107 |
[\fB\-\-change\-section\-vma\fR \fIsectionpattern\fR{=,+,\-}\fIval\fR] |
| 108 |
[\fB\-\-change\-warnings\fR] [\fB\-\-no\-change\-warnings\fR] |
| 109 |
[\fB\-\-set\-section\-flags\fR \fIsectionpattern\fR=\fIflags\fR] |
| 110 |
[\fB\-\-set\-section\-alignment\fR \fIsectionpattern\fR=\fIalign\fR] |
| 111 |
[\fB\-\-add\-section\fR \fIsectionname\fR=\fIfilename\fR] |
| 112 |
[\fB\-\-dump\-section\fR \fIsectionname\fR=\fIfilename\fR] |
| 113 |
[\fB\-\-update\-section\fR \fIsectionname\fR=\fIfilename\fR] |
| 114 |
[\fB\-\-rename\-section\fR \fIoldname\fR=\fInewname\fR[,\fIflags\fR]] |
| 115 |
[\fB\-\-long\-section\-names\fR {enable,disable,keep}] |
| 116 |
[\fB\-\-change\-leading\-char\fR] [\fB\-\-remove\-leading\-char\fR] |
| 117 |
[\fB\-\-reverse\-bytes=\fR\fInum\fR] |
| 118 |
[\fB\-\-srec\-len=\fR\fIival\fR] [\fB\-\-srec\-forceS3\fR] |
| 119 |
[\fB\-\-redefine\-sym\fR \fIold\fR=\fInew\fR] |
| 120 |
[\fB\-\-redefine\-syms=\fR\fIfilename\fR] |
| 121 |
[\fB\-\-weaken\fR] |
| 122 |
[\fB\-\-keep\-symbols=\fR\fIfilename\fR] |
| 123 |
[\fB\-\-strip\-symbols=\fR\fIfilename\fR] |
| 124 |
[\fB\-\-strip\-unneeded\-symbols=\fR\fIfilename\fR] |
| 125 |
[\fB\-\-keep\-global\-symbols=\fR\fIfilename\fR] |
| 126 |
[\fB\-\-localize\-symbols=\fR\fIfilename\fR] |
| 127 |
[\fB\-\-weaken\-symbols=\fR\fIfilename\fR] |
| 128 |
[\fB\-\-binary\-symbol\-prefix\fR\fIstring\fR] |
| 129 |
[\fB\-\-add\-symbol\fR \fIname\fR=[\fIsection\fR:]\fIvalue\fR[,\fIflags\fR]] |
| 130 |
[\fB\-\-alt\-machine\-code=\fR\fIindex\fR] |
| 131 |
[\fB\-\-prefix\-symbols=\fR\fIstring\fR] |
| 132 |
[\fB\-\-prefix\-sections=\fR\fIstring\fR] |
| 133 |
[\fB\-\-prefix\-alloc\-sections=\fR\fIstring\fR] |
| 134 |
[\fB\-\-add\-gnu\-debuglink=\fR\fIpath-to-file\fR] |
| 135 |
[\fB\-\-only\-keep\-debug\fR] |
| 136 |
[\fB\-\-strip\-dwo\fR] |
| 137 |
[\fB\-\-extract\-dwo\fR] |
| 138 |
[\fB\-\-extract\-symbol\fR] |
| 139 |
[\fB\-\-writable\-text\fR] |
| 140 |
[\fB\-\-readonly\-text\fR] |
| 141 |
[\fB\-\-pure\fR] |
| 142 |
[\fB\-\-impure\fR] |
| 143 |
[\fB\-\-file\-alignment=\fR\fInum\fR] |
| 144 |
[\fB\-\-heap=\fR\fIreserve\fR[,\fIcommit\fR]] |
| 145 |
[\fB\-\-image\-base=\fR\fIaddress\fR] |
| 146 |
[\fB\-\-section\-alignment=\fR\fInum\fR] |
| 147 |
[\fB\-\-stack=\fR\fIreserve\fR[,\fIcommit\fR]] |
| 148 |
[\fB\-\-subsystem=\fR\fIwhich\fR:\fImajor\fR.\fIminor\fR] |
| 149 |
[\fB\-\-compress\-debug\-sections\fR] |
| 150 |
[\fB\-\-decompress\-debug\-sections\fR] |
| 151 |
[\fB\-\-elf\-stt\-common=\fR\fIval\fR] |
| 152 |
[\fB\-\-merge\-notes\fR] |
| 153 |
[\fB\-\-no\-merge\-notes\fR] |
| 154 |
[\fB\-\-verilog\-data\-width=\fR\fIval\fR] |
| 155 |
[\fB\-v\fR|\fB\-\-verbose\fR] |
| 156 |
[\fB\-V\fR|\fB\-\-version\fR] |
| 157 |
[\fB\-\-help\fR] [\fB\-\-info\fR] |
| 158 |
\fIinfile\fR [\fIoutfile\fR] |
| 159 |
.SH DESCRIPTION |
| 160 |
.IX Header "DESCRIPTION" |
| 161 |
The GNU \fBobjcopy\fR utility copies the contents of an object |
| 162 |
file to another. \fBobjcopy\fR uses the GNU BFD Library to |
| 163 |
read and write the object files. It can write the destination object |
| 164 |
file in a format different from that of the source object file. The |
| 165 |
exact behavior of \fBobjcopy\fR is controlled by command-line options. |
| 166 |
Note that \fBobjcopy\fR should be able to copy a fully linked file |
| 167 |
between any two formats. However, copying a relocatable object file |
| 168 |
between any two formats may not work as expected. |
| 169 |
.PP |
| 170 |
\&\fBobjcopy\fR creates temporary files to do its translations and |
| 171 |
deletes them afterward. \fBobjcopy\fR uses BFD to do all its |
| 172 |
translation work; it has access to all the formats described in BFD |
| 173 |
and thus is able to recognize most formats without being told |
| 174 |
explicitly. |
| 175 |
.PP |
| 176 |
\&\fBobjcopy\fR can be used to generate S\-records by using an output |
| 177 |
target of \fBsrec\fR (e.g., use \fB\-O srec\fR). |
| 178 |
.PP |
| 179 |
\&\fBobjcopy\fR can be used to generate a raw binary file by using an |
| 180 |
output target of \fBbinary\fR (e.g., use \fB\-O binary\fR). When |
| 181 |
\&\fBobjcopy\fR generates a raw binary file, it will essentially produce |
| 182 |
a memory dump of the contents of the input object file. All symbols and |
| 183 |
relocation information will be discarded. The memory dump will start at |
| 184 |
the load address of the lowest section copied into the output file. |
| 185 |
.PP |
| 186 |
When generating an S\-record or a raw binary file, it may be helpful to |
| 187 |
use \fB\-S\fR to remove sections containing debugging information. In |
| 188 |
some cases \fB\-R\fR will be useful to remove sections which contain |
| 189 |
information that is not needed by the binary file. |
| 190 |
.PP |
| 191 |
Note\-\-\-\fBobjcopy\fR is not able to change the endianness of its input |
| 192 |
files. If the input format has an endianness (some formats do not), |
| 193 |
\&\fBobjcopy\fR can only copy the inputs into file formats that have the |
| 194 |
same endianness or which have no endianness (e.g., \fBsrec\fR). |
| 195 |
(However, see the \fB\-\-reverse\-bytes\fR option.) |
| 196 |
.SH OPTIONS |
| 197 |
.IX Header "OPTIONS" |
| 198 |
.IP \fIinfile\fR 4 |
| 199 |
.IX Item "infile" |
| 200 |
.PD 0 |
| 201 |
.IP \fIoutfile\fR 4 |
| 202 |
.IX Item "outfile" |
| 203 |
.PD |
| 204 |
The input and output files, respectively. |
| 205 |
If you do not specify \fIoutfile\fR, \fBobjcopy\fR creates a |
| 206 |
temporary file and destructively renames the result with |
| 207 |
the name of \fIinfile\fR. |
| 208 |
.IP "\fB\-I\fR \fIbfdname\fR" 4 |
| 209 |
.IX Item "-I bfdname" |
| 210 |
.PD 0 |
| 211 |
.IP \fB\-\-input\-target=\fR\fIbfdname\fR 4 |
| 212 |
.IX Item "--input-target=bfdname" |
| 213 |
.PD |
| 214 |
Consider the source file's object format to be \fIbfdname\fR, rather than |
| 215 |
attempting to deduce it. |
| 216 |
.IP "\fB\-O\fR \fIbfdname\fR" 4 |
| 217 |
.IX Item "-O bfdname" |
| 218 |
.PD 0 |
| 219 |
.IP \fB\-\-output\-target=\fR\fIbfdname\fR 4 |
| 220 |
.IX Item "--output-target=bfdname" |
| 221 |
.PD |
| 222 |
Write the output file using the object format \fIbfdname\fR. |
| 223 |
.IP "\fB\-F\fR \fIbfdname\fR" 4 |
| 224 |
.IX Item "-F bfdname" |
| 225 |
.PD 0 |
| 226 |
.IP \fB\-\-target=\fR\fIbfdname\fR 4 |
| 227 |
.IX Item "--target=bfdname" |
| 228 |
.PD |
| 229 |
Use \fIbfdname\fR as the object format for both the input and the output |
| 230 |
file; i.e., simply transfer data from source to destination with no |
| 231 |
translation. |
| 232 |
.IP "\fB\-B\fR \fIbfdarch\fR" 4 |
| 233 |
.IX Item "-B bfdarch" |
| 234 |
.PD 0 |
| 235 |
.IP \fB\-\-binary\-architecture=\fR\fIbfdarch\fR 4 |
| 236 |
.IX Item "--binary-architecture=bfdarch" |
| 237 |
.PD |
| 238 |
Useful when transforming a architecture-less input file into an object file. |
| 239 |
In this case the output architecture can be set to \fIbfdarch\fR. This |
| 240 |
option will be ignored if the input file has a known \fIbfdarch\fR. You |
| 241 |
can access this binary data inside a program by referencing the special |
| 242 |
symbols that are created by the conversion process. These symbols are |
| 243 |
called _binary_\fIobjfile\fR_start, _binary_\fIobjfile\fR_end and |
| 244 |
_binary_\fIobjfile\fR_size. e.g. you can transform a picture file into |
| 245 |
an object file and then access it in your code using these symbols. |
| 246 |
.IP "\fB\-j\fR \fIsectionpattern\fR" 4 |
| 247 |
.IX Item "-j sectionpattern" |
| 248 |
.PD 0 |
| 249 |
.IP \fB\-\-only\-section=\fR\fIsectionpattern\fR 4 |
| 250 |
.IX Item "--only-section=sectionpattern" |
| 251 |
.PD |
| 252 |
Copy only the indicated sections from the input file to the output file. |
| 253 |
This option may be given more than once. Note that using this option |
| 254 |
inappropriately may make the output file unusable. Wildcard |
| 255 |
characters are accepted in \fIsectionpattern\fR. |
| 256 |
.Sp |
| 257 |
If the first character of \fIsectionpattern\fR is the exclamation |
| 258 |
point (!) then matching sections will not be copied, even if earlier |
| 259 |
use of \fB\-\-only\-section\fR on the same command line would |
| 260 |
otherwise copy it. For example: |
| 261 |
.Sp |
| 262 |
.Vb 1 |
| 263 |
\& \-\-only\-section=.text.* \-\-only\-section=!.text.foo |
| 264 |
.Ve |
| 265 |
.Sp |
| 266 |
will copy all sectinos matching '.text.*' but not the section |
| 267 |
\&'.text.foo'. |
| 268 |
.IP "\fB\-R\fR \fIsectionpattern\fR" 4 |
| 269 |
.IX Item "-R sectionpattern" |
| 270 |
.PD 0 |
| 271 |
.IP \fB\-\-remove\-section=\fR\fIsectionpattern\fR 4 |
| 272 |
.IX Item "--remove-section=sectionpattern" |
| 273 |
.PD |
| 274 |
Remove any section matching \fIsectionpattern\fR from the output file. |
| 275 |
This option may be given more than once. Note that using this option |
| 276 |
inappropriately may make the output file unusable. Wildcard |
| 277 |
characters are accepted in \fIsectionpattern\fR. Using both the |
| 278 |
\&\fB\-j\fR and \fB\-R\fR options together results in undefined |
| 279 |
behaviour. |
| 280 |
.Sp |
| 281 |
If the first character of \fIsectionpattern\fR is the exclamation |
| 282 |
point (!) then matching sections will not be removed even if an |
| 283 |
earlier use of \fB\-\-remove\-section\fR on the same command line |
| 284 |
would otherwise remove it. For example: |
| 285 |
.Sp |
| 286 |
.Vb 1 |
| 287 |
\& \-\-remove\-section=.text.* \-\-remove\-section=!.text.foo |
| 288 |
.Ve |
| 289 |
.Sp |
| 290 |
will remove all sections matching the pattern '.text.*', but will not |
| 291 |
remove the section '.text.foo'. |
| 292 |
.IP \fB\-\-keep\-section=\fR\fIsectionpattern\fR 4 |
| 293 |
.IX Item "--keep-section=sectionpattern" |
| 294 |
When removing sections from the output file, keep sections that match |
| 295 |
\&\fIsectionpattern\fR. |
| 296 |
.IP \fB\-\-remove\-relocations=\fR\fIsectionpattern\fR 4 |
| 297 |
.IX Item "--remove-relocations=sectionpattern" |
| 298 |
Remove non-dynamic relocations from the output file for any section |
| 299 |
matching \fIsectionpattern\fR. This option may be given more than |
| 300 |
once. Note that using this option inappropriately may make the output |
| 301 |
file unusable, and attempting to remove a dynamic relocation section |
| 302 |
such as \fB.rela.plt\fR from an executable or shared library with |
| 303 |
\&\fB\-\-remove\-relocations=.plt\fR will not work. Wildcard characters |
| 304 |
are accepted in \fIsectionpattern\fR. |
| 305 |
For example: |
| 306 |
.Sp |
| 307 |
.Vb 1 |
| 308 |
\& \-\-remove\-relocations=.text.* |
| 309 |
.Ve |
| 310 |
.Sp |
| 311 |
will remove the relocations for all sections matching the pattern |
| 312 |
\&'.text.*'. |
| 313 |
.Sp |
| 314 |
If the first character of \fIsectionpattern\fR is the exclamation |
| 315 |
point (!) then matching sections will not have their relocation |
| 316 |
removed even if an earlier use of \fB\-\-remove\-relocations\fR on the |
| 317 |
same command line would otherwise cause the relocations to be removed. |
| 318 |
For example: |
| 319 |
.Sp |
| 320 |
.Vb 1 |
| 321 |
\& \-\-remove\-relocations=.text.* \-\-remove\-relocations=!.text.foo |
| 322 |
.Ve |
| 323 |
.Sp |
| 324 |
will remove all relocations for sections matching the pattern |
| 325 |
\&'.text.*', but will not remove relocations for the section |
| 326 |
\&'.text.foo'. |
| 327 |
.IP \fB\-\-strip\-section\-headers\fR 4 |
| 328 |
.IX Item "--strip-section-headers" |
| 329 |
Strip section header This option is specific to ELF files. |
| 330 |
Implies \fB\-\-strip\-all\fR and \fB\-\-merge\-notes\fR. |
| 331 |
.IP \fB\-S\fR 4 |
| 332 |
.IX Item "-S" |
| 333 |
.PD 0 |
| 334 |
.IP \fB\-\-strip\-all\fR 4 |
| 335 |
.IX Item "--strip-all" |
| 336 |
.PD |
| 337 |
Do not copy relocation and symbol information from the source file. |
| 338 |
Also deletes debug sections. |
| 339 |
.IP \fB\-g\fR 4 |
| 340 |
.IX Item "-g" |
| 341 |
.PD 0 |
| 342 |
.IP \fB\-\-strip\-debug\fR 4 |
| 343 |
.IX Item "--strip-debug" |
| 344 |
.PD |
| 345 |
Do not copy debugging symbols or sections from the source file. |
| 346 |
.IP \fB\-\-strip\-unneeded\fR 4 |
| 347 |
.IX Item "--strip-unneeded" |
| 348 |
Remove all symbols that are not needed for relocation processing in |
| 349 |
addition to debugging symbols and sections stripped by |
| 350 |
\&\fB\-\-strip\-debug\fR. |
| 351 |
.IP "\fB\-K\fR \fIsymbolname\fR" 4 |
| 352 |
.IX Item "-K symbolname" |
| 353 |
.PD 0 |
| 354 |
.IP \fB\-\-keep\-symbol=\fR\fIsymbolname\fR 4 |
| 355 |
.IX Item "--keep-symbol=symbolname" |
| 356 |
.PD |
| 357 |
When stripping symbols, keep symbol \fIsymbolname\fR even if it would |
| 358 |
normally be stripped. This option may be given more than once. |
| 359 |
.IP "\fB\-N\fR \fIsymbolname\fR" 4 |
| 360 |
.IX Item "-N symbolname" |
| 361 |
.PD 0 |
| 362 |
.IP \fB\-\-strip\-symbol=\fR\fIsymbolname\fR 4 |
| 363 |
.IX Item "--strip-symbol=symbolname" |
| 364 |
.PD |
| 365 |
Do not copy symbol \fIsymbolname\fR from the source file. This option |
| 366 |
may be given more than once. |
| 367 |
.IP \fB\-\-strip\-unneeded\-symbol=\fR\fIsymbolname\fR 4 |
| 368 |
.IX Item "--strip-unneeded-symbol=symbolname" |
| 369 |
Do not copy symbol \fIsymbolname\fR from the source file unless it is needed |
| 370 |
by a relocation. This option may be given more than once. |
| 371 |
.IP "\fB\-G\fR \fIsymbolname\fR" 4 |
| 372 |
.IX Item "-G symbolname" |
| 373 |
.PD 0 |
| 374 |
.IP \fB\-\-keep\-global\-symbol=\fR\fIsymbolname\fR 4 |
| 375 |
.IX Item "--keep-global-symbol=symbolname" |
| 376 |
.PD |
| 377 |
Keep only symbol \fIsymbolname\fR global. Make all other symbols local |
| 378 |
to the file, so that they are not visible externally. This option may |
| 379 |
be given more than once. Note: this option cannot be used in |
| 380 |
conjunction with the \fB\-\-globalize\-symbol\fR or |
| 381 |
\&\fB\-\-globalize\-symbols\fR options. |
| 382 |
.IP \fB\-\-localize\-hidden\fR 4 |
| 383 |
.IX Item "--localize-hidden" |
| 384 |
In an ELF object, mark all symbols that have hidden or internal visibility |
| 385 |
as local. This option applies on top of symbol-specific localization options |
| 386 |
such as \fB\-L\fR. |
| 387 |
.IP "\fB\-L\fR \fIsymbolname\fR" 4 |
| 388 |
.IX Item "-L symbolname" |
| 389 |
.PD 0 |
| 390 |
.IP \fB\-\-localize\-symbol=\fR\fIsymbolname\fR 4 |
| 391 |
.IX Item "--localize-symbol=symbolname" |
| 392 |
.PD |
| 393 |
Convert a global or weak symbol called \fIsymbolname\fR into a local |
| 394 |
symbol, so that it is not visible externally. This option may be |
| 395 |
given more than once. Note \- unique symbols are not converted. |
| 396 |
.IP "\fB\-W\fR \fIsymbolname\fR" 4 |
| 397 |
.IX Item "-W symbolname" |
| 398 |
.PD 0 |
| 399 |
.IP \fB\-\-weaken\-symbol=\fR\fIsymbolname\fR 4 |
| 400 |
.IX Item "--weaken-symbol=symbolname" |
| 401 |
.PD |
| 402 |
Make symbol \fIsymbolname\fR weak. This option may be given more than once. |
| 403 |
.IP \fB\-\-binary\-symbol\-prefix=\fR\fIstring\fR 4 |
| 404 |
.IX Item "--binary-symbol-prefix=string" |
| 405 |
When used with \fB\-\-input\-target=binary\fR, sets \fIstring\fR as the |
| 406 |
base name for the symbols generated for the input file. These symbols are: |
| 407 |
.Sp |
| 408 |
.Vb 3 |
| 409 |
\& <string>_start |
| 410 |
\& <string>_end |
| 411 |
\& <string>_size |
| 412 |
.Ve |
| 413 |
.Sp |
| 414 |
By default, the binary input handler derives the prefix symbol name from a |
| 415 |
mangled version of the input file name and _binary prefix. This option |
| 416 |
allows specifying it explicitly. |
| 417 |
.IP \fB\-\-globalize\-symbol=\fR\fIsymbolname\fR 4 |
| 418 |
.IX Item "--globalize-symbol=symbolname" |
| 419 |
Give symbol \fIsymbolname\fR global scoping so that it is visible |
| 420 |
outside of the file in which it is defined. This option may be given |
| 421 |
more than once. Note: this option cannot be used in conjunction with |
| 422 |
the \fB\-G\fR or \fB\-\-keep\-global\-symbol\fR options. |
| 423 |
.IP \fB\-w\fR 4 |
| 424 |
.IX Item "-w" |
| 425 |
.PD 0 |
| 426 |
.IP \fB\-\-wildcard\fR 4 |
| 427 |
.IX Item "--wildcard" |
| 428 |
.PD |
| 429 |
Permit regular expressions in \fIsymbolname\fRs used in other command |
| 430 |
line options. The question mark (?), asterisk (*), backslash (\e) and |
| 431 |
square brackets ([]) operators can be used anywhere in the symbol |
| 432 |
name. If the first character of the symbol name is the exclamation |
| 433 |
point (!) then the sense of the switch is reversed for that symbol. |
| 434 |
For example: |
| 435 |
.Sp |
| 436 |
.Vb 1 |
| 437 |
\& \-w \-W !foo \-W fo* |
| 438 |
.Ve |
| 439 |
.Sp |
| 440 |
would cause objcopy to weaken all symbols that start with "fo" |
| 441 |
except for the symbol "foo". |
| 442 |
.IP \fB\-x\fR 4 |
| 443 |
.IX Item "-x" |
| 444 |
.PD 0 |
| 445 |
.IP \fB\-\-discard\-all\fR 4 |
| 446 |
.IX Item "--discard-all" |
| 447 |
.PD |
| 448 |
Do not copy non-global symbols from the source file. |
| 449 |
.IP \fB\-X\fR 4 |
| 450 |
.IX Item "-X" |
| 451 |
.PD 0 |
| 452 |
.IP \fB\-\-discard\-locals\fR 4 |
| 453 |
.IX Item "--discard-locals" |
| 454 |
.PD |
| 455 |
Do not copy compiler-generated local symbols. |
| 456 |
(These usually start with \fBL\fR or \fB.\fR.) |
| 457 |
.IP "\fB\-b\fR \fIbyte\fR" 4 |
| 458 |
.IX Item "-b byte" |
| 459 |
.PD 0 |
| 460 |
.IP \fB\-\-byte=\fR\fIbyte\fR 4 |
| 461 |
.IX Item "--byte=byte" |
| 462 |
.PD |
| 463 |
If interleaving has been enabled via the \fB\-\-interleave\fR option |
| 464 |
then start the range of bytes to keep at the \fIbyte\fRth byte. |
| 465 |
\&\fIbyte\fR can be in the range from 0 to \fIbreadth\fR\-1, where |
| 466 |
\&\fIbreadth\fR is the value given by the \fB\-\-interleave\fR option. |
| 467 |
.IP "\fB\-i [\fR\fIbreadth\fR\fB]\fR" 4 |
| 468 |
.IX Item "-i [breadth]" |
| 469 |
.PD 0 |
| 470 |
.IP \fB\-\-interleave[=\fR\fIbreadth\fR\fB]\fR 4 |
| 471 |
.IX Item "--interleave[=breadth]" |
| 472 |
.PD |
| 473 |
Only copy a range out of every \fIbreadth\fR bytes. (Header data is |
| 474 |
not affected). Select which byte in the range begins the copy with |
| 475 |
the \fB\-\-byte\fR option. Select the width of the range with the |
| 476 |
\&\fB\-\-interleave\-width\fR option. |
| 477 |
.Sp |
| 478 |
This option is useful for creating files to program ROM. It is |
| 479 |
typically used with an \f(CW\*(C`srec\*(C'\fR output target. Note that |
| 480 |
\&\fBobjcopy\fR will complain if you do not specify the |
| 481 |
\&\fB\-\-byte\fR option as well. |
| 482 |
.Sp |
| 483 |
The default interleave breadth is 4, so with \fB\-\-byte\fR set to 0, |
| 484 |
\&\fBobjcopy\fR would copy the first byte out of every four bytes |
| 485 |
from the input to the output. |
| 486 |
.IP \fB\-\-interleave\-width=\fR\fIwidth\fR 4 |
| 487 |
.IX Item "--interleave-width=width" |
| 488 |
When used with the \fB\-\-interleave\fR option, copy \fIwidth\fR |
| 489 |
bytes at a time. The start of the range of bytes to be copied is set |
| 490 |
by the \fB\-\-byte\fR option, and the extent of the range is set with |
| 491 |
the \fB\-\-interleave\fR option. |
| 492 |
.Sp |
| 493 |
The default value for this option is 1. The value of \fIwidth\fR plus |
| 494 |
the \fIbyte\fR value set by the \fB\-\-byte\fR option must not exceed |
| 495 |
the interleave breadth set by the \fB\-\-interleave\fR option. |
| 496 |
.Sp |
| 497 |
This option can be used to create images for two 16\-bit flashes interleaved |
| 498 |
in a 32\-bit bus by passing \fB\-b 0 \-i 4 \-\-interleave\-width=2\fR |
| 499 |
and \fB\-b 2 \-i 4 \-\-interleave\-width=2\fR to two \fBobjcopy\fR |
| 500 |
commands. If the input was '12345678' then the outputs would be |
| 501 |
\&'1256' and '3478' respectively. |
| 502 |
.IP \fB\-p\fR 4 |
| 503 |
.IX Item "-p" |
| 504 |
.PD 0 |
| 505 |
.IP \fB\-\-preserve\-dates\fR 4 |
| 506 |
.IX Item "--preserve-dates" |
| 507 |
.PD |
| 508 |
Set the access and modification dates of the output file to be the same |
| 509 |
as those of the input file. |
| 510 |
.Sp |
| 511 |
This option also copies the date stored in a PE format file's header, |
| 512 |
unless the SOURCE_DATE_EPOCH environment variable is defined. If it |
| 513 |
is defined then this variable will be used as the date stored in the |
| 514 |
header, interpreted as the number of seconds since the Unix epoch. |
| 515 |
.IP \fB\-D\fR 4 |
| 516 |
.IX Item "-D" |
| 517 |
.PD 0 |
| 518 |
.IP \fB\-\-enable\-deterministic\-archives\fR 4 |
| 519 |
.IX Item "--enable-deterministic-archives" |
| 520 |
.PD |
| 521 |
Operate in \fIdeterministic\fR mode. When copying archive members |
| 522 |
and writing the archive index, use zero for UIDs, GIDs, timestamps, |
| 523 |
and use consistent file modes for all files. |
| 524 |
.Sp |
| 525 |
If \fIbinutils\fR was configured with |
| 526 |
\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default. |
| 527 |
It can be disabled with the \fB\-U\fR option, below. |
| 528 |
.IP \fB\-U\fR 4 |
| 529 |
.IX Item "-U" |
| 530 |
.PD 0 |
| 531 |
.IP \fB\-\-disable\-deterministic\-archives\fR 4 |
| 532 |
.IX Item "--disable-deterministic-archives" |
| 533 |
.PD |
| 534 |
Do \fInot\fR operate in \fIdeterministic\fR mode. This is the |
| 535 |
inverse of the \fB\-D\fR option, above: when copying archive members |
| 536 |
and writing the archive index, use their actual UID, GID, timestamp, |
| 537 |
and file mode values. |
| 538 |
.Sp |
| 539 |
This is the default unless \fIbinutils\fR was configured with |
| 540 |
\&\fB\-\-enable\-deterministic\-archives\fR. |
| 541 |
.IP \fB\-\-debugging\fR 4 |
| 542 |
.IX Item "--debugging" |
| 543 |
Convert debugging information, if possible. This is not the default |
| 544 |
because only certain debugging formats are supported, and the |
| 545 |
conversion process can be time consuming. |
| 546 |
.IP "\fB\-\-gap\-fill\fR \fIval\fR" 4 |
| 547 |
.IX Item "--gap-fill val" |
| 548 |
Fill gaps between sections with \fIval\fR. This operation applies to |
| 549 |
the \fIload address\fR (LMA) of the sections. It is done by increasing |
| 550 |
the size of the section with the lower address, and filling in the extra |
| 551 |
space created with \fIval\fR. |
| 552 |
.IP "\fB\-\-pad\-to\fR \fIaddress\fR" 4 |
| 553 |
.IX Item "--pad-to address" |
| 554 |
Pad the output file up to the load address \fIaddress\fR. This is |
| 555 |
done by increasing the size of the last section. The extra space is |
| 556 |
filled in with the value specified by \fB\-\-gap\-fill\fR (default zero). |
| 557 |
.IP "\fB\-\-set\-start\fR \fIval\fR" 4 |
| 558 |
.IX Item "--set-start val" |
| 559 |
Set the start address (also known as the entry address) of the new |
| 560 |
file to \fIval\fR. Not all object file formats support setting the |
| 561 |
start address. |
| 562 |
.IP "\fB\-\-change\-start\fR \fIincr\fR" 4 |
| 563 |
.IX Item "--change-start incr" |
| 564 |
.PD 0 |
| 565 |
.IP "\fB\-\-adjust\-start\fR \fIincr\fR" 4 |
| 566 |
.IX Item "--adjust-start incr" |
| 567 |
.PD |
| 568 |
Change the start address (also known as the entry address) by adding |
| 569 |
\&\fIincr\fR. Not all object file formats support setting the start |
| 570 |
address. |
| 571 |
.IP "\fB\-\-change\-addresses\fR \fIincr\fR" 4 |
| 572 |
.IX Item "--change-addresses incr" |
| 573 |
.PD 0 |
| 574 |
.IP "\fB\-\-adjust\-vma\fR \fIincr\fR" 4 |
| 575 |
.IX Item "--adjust-vma incr" |
| 576 |
.PD |
| 577 |
Change the VMA and LMA addresses of all sections, as well as the start |
| 578 |
address, by adding \fIincr\fR. Some object file formats do not permit |
| 579 |
section addresses to be changed arbitrarily. Note that this does not |
| 580 |
relocate the sections; if the program expects sections to be loaded at a |
| 581 |
certain address, and this option is used to change the sections such |
| 582 |
that they are loaded at a different address, the program may fail. |
| 583 |
.IP "\fB\-\-change\-section\-address\fR \fIsectionpattern\fR\fB{=,+,\-}\fR\fIval\fR" 4 |
| 584 |
.IX Item "--change-section-address sectionpattern{=,+,-}val" |
| 585 |
.PD 0 |
| 586 |
.IP "\fB\-\-adjust\-section\-vma\fR \fIsectionpattern\fR\fB{=,+,\-}\fR\fIval\fR" 4 |
| 587 |
.IX Item "--adjust-section-vma sectionpattern{=,+,-}val" |
| 588 |
.PD |
| 589 |
Set or change both the VMA address and the LMA address of any section |
| 590 |
matching \fIsectionpattern\fR. If \fB=\fR is used, the section |
| 591 |
address is set to \fIval\fR. Otherwise, \fIval\fR is added to or |
| 592 |
subtracted from the section address. See the comments under |
| 593 |
\&\fB\-\-change\-addresses\fR, above. If \fIsectionpattern\fR does not |
| 594 |
match any sections in the input file, a warning will be issued, unless |
| 595 |
\&\fB\-\-no\-change\-warnings\fR is used. |
| 596 |
.IP "\fB\-\-change\-section\-lma\fR \fIsectionpattern\fR\fB{=,+,\-}\fR\fIval\fR" 4 |
| 597 |
.IX Item "--change-section-lma sectionpattern{=,+,-}val" |
| 598 |
Set or change the LMA address of any sections matching |
| 599 |
\&\fIsectionpattern\fR. The LMA address is the address where the |
| 600 |
section will be loaded into memory at program load time. Normally |
| 601 |
this is the same as the VMA address, which is the address of the |
| 602 |
section at program run time, but on some systems, especially those |
| 603 |
where a program is held in ROM, the two can be different. If \fB=\fR |
| 604 |
is used, the section address is set to \fIval\fR. Otherwise, |
| 605 |
\&\fIval\fR is added to or subtracted from the section address. See the |
| 606 |
comments under \fB\-\-change\-addresses\fR, above. If |
| 607 |
\&\fIsectionpattern\fR does not match any sections in the input file, a |
| 608 |
warning will be issued, unless \fB\-\-no\-change\-warnings\fR is used. |
| 609 |
.IP "\fB\-\-change\-section\-vma\fR \fIsectionpattern\fR\fB{=,+,\-}\fR\fIval\fR" 4 |
| 610 |
.IX Item "--change-section-vma sectionpattern{=,+,-}val" |
| 611 |
Set or change the VMA address of any section matching |
| 612 |
\&\fIsectionpattern\fR. The VMA address is the address where the |
| 613 |
section will be located once the program has started executing. |
| 614 |
Normally this is the same as the LMA address, which is the address |
| 615 |
where the section will be loaded into memory, but on some systems, |
| 616 |
especially those where a program is held in ROM, the two can be |
| 617 |
different. If \fB=\fR is used, the section address is set to |
| 618 |
\&\fIval\fR. Otherwise, \fIval\fR is added to or subtracted from the |
| 619 |
section address. See the comments under \fB\-\-change\-addresses\fR, |
| 620 |
above. If \fIsectionpattern\fR does not match any sections in the |
| 621 |
input file, a warning will be issued, unless |
| 622 |
\&\fB\-\-no\-change\-warnings\fR is used. |
| 623 |
.Sp |
| 624 |
Note \- changing the VMA of sections in a fully linked binary can be |
| 625 |
dangerous since there may be code that expects the sections to be |
| 626 |
located at their old address. |
| 627 |
.IP \fB\-\-change\-warnings\fR 4 |
| 628 |
.IX Item "--change-warnings" |
| 629 |
.PD 0 |
| 630 |
.IP \fB\-\-adjust\-warnings\fR 4 |
| 631 |
.IX Item "--adjust-warnings" |
| 632 |
.PD |
| 633 |
If \fB\-\-change\-section\-address\fR or \fB\-\-change\-section\-lma\fR or |
| 634 |
\&\fB\-\-change\-section\-vma\fR is used, and the section pattern does not |
| 635 |
match any sections, issue a warning. This is the default. |
| 636 |
.IP \fB\-\-no\-change\-warnings\fR 4 |
| 637 |
.IX Item "--no-change-warnings" |
| 638 |
.PD 0 |
| 639 |
.IP \fB\-\-no\-adjust\-warnings\fR 4 |
| 640 |
.IX Item "--no-adjust-warnings" |
| 641 |
.PD |
| 642 |
Do not issue a warning if \fB\-\-change\-section\-address\fR or |
| 643 |
\&\fB\-\-adjust\-section\-lma\fR or \fB\-\-adjust\-section\-vma\fR is used, even |
| 644 |
if the section pattern does not match any sections. |
| 645 |
.IP "\fB\-\-set\-section\-flags\fR \fIsectionpattern\fR\fB=\fR\fIflags\fR" 4 |
| 646 |
.IX Item "--set-section-flags sectionpattern=flags" |
| 647 |
Set the flags for any sections matching \fIsectionpattern\fR. The |
| 648 |
\&\fIflags\fR argument is a comma separated string of flag names. The |
| 649 |
recognized names are \fBalloc\fR, \fBcontents\fR, \fBload\fR, |
| 650 |
\&\fBnoload\fR, \fBreadonly\fR, \fBcode\fR, \fBdata\fR, \fBrom\fR, |
| 651 |
\&\fBexclude\fR, \fBshare\fR, \fBdebug\fR, and \fBlarge\fR. |
| 652 |
You can set the \fBcontents\fR flag for a section which does not have |
| 653 |
contents, but it is not meaningful to clear the \fBcontents\fR flag of a |
| 654 |
section which does have contents\-\-just remove the section instead. Not all |
| 655 |
flags are meaningful for all object file formats. In particular the |
| 656 |
\&\fBshare\fR flag is only meaningful for COFF format files and not for ELF |
| 657 |
format files. The ELF x86\-64 specific flag \fBlarge\fR corresponds to |
| 658 |
SHF_X86_64_LARGE. |
| 659 |
.IP "\fB\-\-set\-section\-alignment\fR \fIsectionpattern\fR\fB=\fR\fIalign\fR" 4 |
| 660 |
.IX Item "--set-section-alignment sectionpattern=align" |
| 661 |
Set the alignment for any sections matching \fIsectionpattern\fR. |
| 662 |
\&\fIalign\fR specifies the alignment in bytes and must be a power of |
| 663 |
two, i.e. 1, 2, 4, 8.... |
| 664 |
.Sp |
| 665 |
Note \- setting a section's alignment will not automatically align its |
| 666 |
LMA or VMA addresses. If those need to be changed as well then the |
| 667 |
\&\fB\-\-change\-section\-lma\fR and/or \fB\-\-change\-section\-vma\fR |
| 668 |
options should be used. Also note that changing VMAs can cause |
| 669 |
problems in fully linked binaries where there may be code that expects |
| 670 |
the contents of the sections to be located at their old address. |
| 671 |
.IP "\fB\-\-add\-section\fR \fIsectionname\fR\fB=\fR\fIfilename\fR" 4 |
| 672 |
.IX Item "--add-section sectionname=filename" |
| 673 |
Add a new section named \fIsectionname\fR while copying the file. The |
| 674 |
contents of the new section are taken from the file \fIfilename\fR. The |
| 675 |
size of the section will be the size of the file. This option only |
| 676 |
works on file formats which can support sections with arbitrary names. |
| 677 |
Note \- it may be necessary to use the \fB\-\-set\-section\-flags\fR |
| 678 |
option to set the attributes of the newly created section. |
| 679 |
.IP "\fB\-\-dump\-section\fR \fIsectionname\fR\fB=\fR\fIfilename\fR" 4 |
| 680 |
.IX Item "--dump-section sectionname=filename" |
| 681 |
Place the contents of section named \fIsectionname\fR into the file |
| 682 |
\&\fIfilename\fR, overwriting any contents that may have been there |
| 683 |
previously. This option is the inverse of \fB\-\-add\-section\fR. |
| 684 |
This option is similar to the \fB\-\-only\-section\fR option except |
| 685 |
that it does not create a formatted file, it just dumps the contents |
| 686 |
as raw binary data, without applying any relocations. The option can |
| 687 |
be specified more than once. |
| 688 |
.IP "\fB\-\-update\-section\fR \fIsectionname\fR\fB=\fR\fIfilename\fR" 4 |
| 689 |
.IX Item "--update-section sectionname=filename" |
| 690 |
Replace the existing contents of a section named \fIsectionname\fR |
| 691 |
with the contents of file \fIfilename\fR. The size of the section |
| 692 |
will be adjusted to the size of the file. The section flags for |
| 693 |
\&\fIsectionname\fR will be unchanged. For ELF format files the section |
| 694 |
to segment mapping will also remain unchanged, something which is not |
| 695 |
possible using \fB\-\-remove\-section\fR followed by |
| 696 |
\&\fB\-\-add\-section\fR. The option can be specified more than once. |
| 697 |
.Sp |
| 698 |
Note \- it is possible to use \fB\-\-rename\-section\fR and |
| 699 |
\&\fB\-\-update\-section\fR to both update and rename a section from one |
| 700 |
command line. In this case, pass the original section name to |
| 701 |
\&\fB\-\-update\-section\fR, and the original and new section names to |
| 702 |
\&\fB\-\-rename\-section\fR. |
| 703 |
.IP "\fB\-\-add\-symbol\fR \fIname\fR\fB=[\fR\fIsection\fR\fB:]\fR\fIvalue\fR\fB[,\fR\fIflags\fR\fB]\fR" 4 |
| 704 |
.IX Item "--add-symbol name=[section:]value[,flags]" |
| 705 |
Add a new symbol named \fIname\fR while copying the file. This option may be |
| 706 |
specified multiple times. If the \fIsection\fR is given, the symbol will be |
| 707 |
associated with and relative to that section, otherwise it will be an ABS |
| 708 |
symbol. Specifying an undefined section will result in a fatal error. There |
| 709 |
is no check for the value, it will be taken as specified. Symbol flags can |
| 710 |
be specified and not all flags will be meaningful for all object file |
| 711 |
formats. By default, the symbol will be global. The special flag |
| 712 |
\&'before=\fIothersym\fR' will insert the new symbol in front of the specified |
| 713 |
\&\fIothersym\fR, otherwise the symbol(s) will be added at the end of the |
| 714 |
symbol table in the order they appear. |
| 715 |
.IP "\fB\-\-rename\-section\fR \fIoldname\fR\fB=\fR\fInewname\fR\fB[,\fR\fIflags\fR\fB]\fR" 4 |
| 716 |
.IX Item "--rename-section oldname=newname[,flags]" |
| 717 |
Rename a section from \fIoldname\fR to \fInewname\fR, optionally |
| 718 |
changing the section's flags to \fIflags\fR in the process. This has |
| 719 |
the advantage over using a linker script to perform the rename in that |
| 720 |
the output stays as an object file and does not become a linked |
| 721 |
executable. This option accepts the same set of flags as the |
| 722 |
\&\fB\-\-set\-section\-flags\fR option. |
| 723 |
.Sp |
| 724 |
This option is particularly helpful when the input format is binary, |
| 725 |
since this will always create a section called .data. If for example, |
| 726 |
you wanted instead to create a section called .rodata containing binary |
| 727 |
data you could use the following command line to achieve it: |
| 728 |
.Sp |
| 729 |
.Vb 3 |
| 730 |
\& objcopy \-I binary \-O <output_format> \-B <architecture> \e |
| 731 |
\& \-\-rename\-section .data=.rodata,alloc,load,readonly,data,contents \e |
| 732 |
\& <input_binary_file> <output_object_file> |
| 733 |
.Ve |
| 734 |
.IP "\fB\-\-long\-section\-names {enable,disable,keep}\fR" 4 |
| 735 |
.IX Item "--long-section-names {enable,disable,keep}" |
| 736 |
Controls the handling of long section names when processing \f(CW\*(C`COFF\*(C'\fR |
| 737 |
and \f(CW\*(C`PE\-COFF\*(C'\fR object formats. The default behaviour, \fBkeep\fR, |
| 738 |
is to preserve long section names if any are present in the input file. |
| 739 |
The \fBenable\fR and \fBdisable\fR options forcibly enable or disable |
| 740 |
the use of long section names in the output object; when \fBdisable\fR |
| 741 |
is in effect, any long section names in the input object will be truncated. |
| 742 |
The \fBenable\fR option will only emit long section names if any are |
| 743 |
present in the inputs; this is mostly the same as \fBkeep\fR, but it |
| 744 |
is left undefined whether the \fBenable\fR option might force the |
| 745 |
creation of an empty string table in the output file. |
| 746 |
.IP \fB\-\-change\-leading\-char\fR 4 |
| 747 |
.IX Item "--change-leading-char" |
| 748 |
Some object file formats use special characters at the start of |
| 749 |
symbols. The most common such character is underscore, which compilers |
| 750 |
often add before every symbol. This option tells \fBobjcopy\fR to |
| 751 |
change the leading character of every symbol when it converts between |
| 752 |
object file formats. If the object file formats use the same leading |
| 753 |
character, this option has no effect. Otherwise, it will add a |
| 754 |
character, or remove a character, or change a character, as |
| 755 |
appropriate. |
| 756 |
.IP \fB\-\-remove\-leading\-char\fR 4 |
| 757 |
.IX Item "--remove-leading-char" |
| 758 |
If the first character of a global symbol is a special symbol leading |
| 759 |
character used by the object file format, remove the character. The |
| 760 |
most common symbol leading character is underscore. This option will |
| 761 |
remove a leading underscore from all global symbols. This can be useful |
| 762 |
if you want to link together objects of different file formats with |
| 763 |
different conventions for symbol names. This is different from |
| 764 |
\&\fB\-\-change\-leading\-char\fR because it always changes the symbol name |
| 765 |
when appropriate, regardless of the object file format of the output |
| 766 |
file. |
| 767 |
.IP \fB\-\-reverse\-bytes=\fR\fInum\fR 4 |
| 768 |
.IX Item "--reverse-bytes=num" |
| 769 |
Reverse the bytes in a section with output contents. A section length must |
| 770 |
be evenly divisible by the value given in order for the swap to be able to |
| 771 |
take place. Reversing takes place before the interleaving is performed. |
| 772 |
.Sp |
| 773 |
This option is used typically in generating ROM images for problematic |
| 774 |
target systems. For example, on some target boards, the 32\-bit words |
| 775 |
fetched from 8\-bit ROMs are re-assembled in little-endian byte order |
| 776 |
regardless of the CPU byte order. Depending on the programming model, the |
| 777 |
endianness of the ROM may need to be modified. |
| 778 |
.Sp |
| 779 |
Consider a simple file with a section containing the following eight |
| 780 |
bytes: \f(CW12345678\fR. |
| 781 |
.Sp |
| 782 |
Using \fB\-\-reverse\-bytes=2\fR for the above example, the bytes in the |
| 783 |
output file would be ordered \f(CW21436587\fR. |
| 784 |
.Sp |
| 785 |
Using \fB\-\-reverse\-bytes=4\fR for the above example, the bytes in the |
| 786 |
output file would be ordered \f(CW43218765\fR. |
| 787 |
.Sp |
| 788 |
By using \fB\-\-reverse\-bytes=2\fR for the above example, followed by |
| 789 |
\&\fB\-\-reverse\-bytes=4\fR on the output file, the bytes in the second |
| 790 |
output file would be ordered \f(CW34127856\fR. |
| 791 |
.IP \fB\-\-srec\-len=\fR\fIival\fR 4 |
| 792 |
.IX Item "--srec-len=ival" |
| 793 |
Meaningful only for srec output. Set the maximum length of the Srecords |
| 794 |
being produced to \fIival\fR. This length covers both address, data and |
| 795 |
crc fields. |
| 796 |
.IP \fB\-\-srec\-forceS3\fR 4 |
| 797 |
.IX Item "--srec-forceS3" |
| 798 |
Meaningful only for srec output. Avoid generation of S1/S2 records, |
| 799 |
creating S3\-only record format. |
| 800 |
.IP "\fB\-\-redefine\-sym\fR \fIold\fR\fB=\fR\fInew\fR" 4 |
| 801 |
.IX Item "--redefine-sym old=new" |
| 802 |
Change the name of a symbol \fIold\fR, to \fInew\fR. This can be useful |
| 803 |
when one is trying link two things together for which you have no |
| 804 |
source, and there are name collisions. |
| 805 |
.IP \fB\-\-redefine\-syms=\fR\fIfilename\fR 4 |
| 806 |
.IX Item "--redefine-syms=filename" |
| 807 |
Apply \fB\-\-redefine\-sym\fR to each symbol pair "\fIold\fR \fInew\fR" |
| 808 |
listed in the file \fIfilename\fR. \fIfilename\fR is simply a flat file, |
| 809 |
with one symbol pair per line. Line comments may be introduced by the hash |
| 810 |
character. This option may be given more than once. |
| 811 |
.IP \fB\-\-weaken\fR 4 |
| 812 |
.IX Item "--weaken" |
| 813 |
Change all global symbols in the file to be weak. This can be useful |
| 814 |
when building an object which will be linked against other objects using |
| 815 |
the \fB\-R\fR option to the linker. This option is only effective when |
| 816 |
using an object file format which supports weak symbols. |
| 817 |
.IP \fB\-\-keep\-symbols=\fR\fIfilename\fR 4 |
| 818 |
.IX Item "--keep-symbols=filename" |
| 819 |
Apply \fB\-\-keep\-symbol\fR option to each symbol listed in the file |
| 820 |
\&\fIfilename\fR. \fIfilename\fR is simply a flat file, with one symbol |
| 821 |
name per line. Line comments may be introduced by the hash character. |
| 822 |
This option may be given more than once. |
| 823 |
.IP \fB\-\-strip\-symbols=\fR\fIfilename\fR 4 |
| 824 |
.IX Item "--strip-symbols=filename" |
| 825 |
Apply \fB\-\-strip\-symbol\fR option to each symbol listed in the file |
| 826 |
\&\fIfilename\fR. \fIfilename\fR is simply a flat file, with one symbol |
| 827 |
name per line. Line comments may be introduced by the hash character. |
| 828 |
This option may be given more than once. |
| 829 |
.IP \fB\-\-strip\-unneeded\-symbols=\fR\fIfilename\fR 4 |
| 830 |
.IX Item "--strip-unneeded-symbols=filename" |
| 831 |
Apply \fB\-\-strip\-unneeded\-symbol\fR option to each symbol listed in |
| 832 |
the file \fIfilename\fR. \fIfilename\fR is simply a flat file, with one |
| 833 |
symbol name per line. Line comments may be introduced by the hash |
| 834 |
character. This option may be given more than once. |
| 835 |
.IP \fB\-\-keep\-global\-symbols=\fR\fIfilename\fR 4 |
| 836 |
.IX Item "--keep-global-symbols=filename" |
| 837 |
Apply \fB\-\-keep\-global\-symbol\fR option to each symbol listed in the |
| 838 |
file \fIfilename\fR. \fIfilename\fR is simply a flat file, with one |
| 839 |
symbol name per line. Line comments may be introduced by the hash |
| 840 |
character. This option may be given more than once. |
| 841 |
.IP \fB\-\-localize\-symbols=\fR\fIfilename\fR 4 |
| 842 |
.IX Item "--localize-symbols=filename" |
| 843 |
Apply \fB\-\-localize\-symbol\fR option to each symbol listed in the file |
| 844 |
\&\fIfilename\fR. \fIfilename\fR is simply a flat file, with one symbol |
| 845 |
name per line. Line comments may be introduced by the hash character. |
| 846 |
This option may be given more than once. |
| 847 |
.IP \fB\-\-globalize\-symbols=\fR\fIfilename\fR 4 |
| 848 |
.IX Item "--globalize-symbols=filename" |
| 849 |
Apply \fB\-\-globalize\-symbol\fR option to each symbol listed in the file |
| 850 |
\&\fIfilename\fR. \fIfilename\fR is simply a flat file, with one symbol |
| 851 |
name per line. Line comments may be introduced by the hash character. |
| 852 |
This option may be given more than once. Note: this option cannot be |
| 853 |
used in conjunction with the \fB\-G\fR or \fB\-\-keep\-global\-symbol\fR |
| 854 |
options. |
| 855 |
.IP \fB\-\-weaken\-symbols=\fR\fIfilename\fR 4 |
| 856 |
.IX Item "--weaken-symbols=filename" |
| 857 |
Apply \fB\-\-weaken\-symbol\fR option to each symbol listed in the file |
| 858 |
\&\fIfilename\fR. \fIfilename\fR is simply a flat file, with one symbol |
| 859 |
name per line. Line comments may be introduced by the hash character. |
| 860 |
This option may be given more than once. |
| 861 |
.IP \fB\-\-alt\-machine\-code=\fR\fIindex\fR 4 |
| 862 |
.IX Item "--alt-machine-code=index" |
| 863 |
If the output architecture has alternate machine codes, use the |
| 864 |
\&\fIindex\fRth code instead of the default one. This is useful in case |
| 865 |
a machine is assigned an official code and the tool-chain adopts the |
| 866 |
new code, but other applications still depend on the original code |
| 867 |
being used. For ELF based architectures if the \fIindex\fR |
| 868 |
alternative does not exist then the value is treated as an absolute |
| 869 |
number to be stored in the e_machine field of the ELF header. |
| 870 |
.IP \fB\-\-writable\-text\fR 4 |
| 871 |
.IX Item "--writable-text" |
| 872 |
Mark the output text as writable. This option isn't meaningful for all |
| 873 |
object file formats. |
| 874 |
.IP \fB\-\-readonly\-text\fR 4 |
| 875 |
.IX Item "--readonly-text" |
| 876 |
Make the output text write protected. This option isn't meaningful for all |
| 877 |
object file formats. |
| 878 |
.IP \fB\-\-pure\fR 4 |
| 879 |
.IX Item "--pure" |
| 880 |
Mark the output file as demand paged. This option isn't meaningful for all |
| 881 |
object file formats. |
| 882 |
.IP \fB\-\-impure\fR 4 |
| 883 |
.IX Item "--impure" |
| 884 |
Mark the output file as impure. This option isn't meaningful for all |
| 885 |
object file formats. |
| 886 |
.IP \fB\-\-prefix\-symbols=\fR\fIstring\fR 4 |
| 887 |
.IX Item "--prefix-symbols=string" |
| 888 |
Prefix all symbols in the output file with \fIstring\fR. |
| 889 |
.IP \fB\-\-prefix\-sections=\fR\fIstring\fR 4 |
| 890 |
.IX Item "--prefix-sections=string" |
| 891 |
Prefix all section names in the output file with \fIstring\fR. |
| 892 |
.IP \fB\-\-prefix\-alloc\-sections=\fR\fIstring\fR 4 |
| 893 |
.IX Item "--prefix-alloc-sections=string" |
| 894 |
Prefix all the names of all allocated sections in the output file with |
| 895 |
\&\fIstring\fR. |
| 896 |
.IP \fB\-\-add\-gnu\-debuglink=\fR\fIpath-to-file\fR 4 |
| 897 |
.IX Item "--add-gnu-debuglink=path-to-file" |
| 898 |
Creates a .gnu_debuglink section which contains a reference to |
| 899 |
\&\fIpath-to-file\fR and adds it to the output file. Note: the file at |
| 900 |
\&\fIpath-to-file\fR must exist. Part of the process of adding the |
| 901 |
\&.gnu_debuglink section involves embedding a checksum of the contents |
| 902 |
of the debug info file into the section. |
| 903 |
.Sp |
| 904 |
If the debug info file is built in one location but it is going to be |
| 905 |
installed at a later time into a different location then do not use |
| 906 |
the path to the installed location. The \fB\-\-add\-gnu\-debuglink\fR |
| 907 |
option will fail because the installed file does not exist yet. |
| 908 |
Instead put the debug info file in the current directory and use the |
| 909 |
\&\fB\-\-add\-gnu\-debuglink\fR option without any directory components, |
| 910 |
like this: |
| 911 |
.Sp |
| 912 |
.Vb 1 |
| 913 |
\& objcopy \-\-add\-gnu\-debuglink=foo.debug |
| 914 |
.Ve |
| 915 |
.Sp |
| 916 |
At debug time, the debugger will attempt to look for the separate debug |
| 917 |
info file in a set of known locations. The exact set of these |
| 918 |
locations varies depending upon the distribution being used, but it |
| 919 |
typically includes: |
| 920 |
.RS 4 |
| 921 |
.IP \(bu 4 |
| 922 |
The same directory as the executable. |
| 923 |
.IP \(bu 4 |
| 924 |
A sub-directory of the directory containing the executable called |
| 925 |
\&.debug. |
| 926 |
.IP \(bu 4 |
| 927 |
A global debug directory such as /usr/lib/debug. |
| 928 |
.RE |
| 929 |
.RS 4 |
| 930 |
.Sp |
| 931 |
As long as the debug info file has been installed into one of these |
| 932 |
locations before the debugger is run everything should work |
| 933 |
correctly. |
| 934 |
.RE |
| 935 |
.IP \fB\-\-keep\-section\-symbols\fR 4 |
| 936 |
.IX Item "--keep-section-symbols" |
| 937 |
When stripping a file, perhaps with \fB\-\-strip\-debug\fR or |
| 938 |
\&\fB\-\-strip\-unneeded\fR, retain any symbols specifying section names, |
| 939 |
which would otherwise get stripped. |
| 940 |
.IP \fB\-\-keep\-file\-symbols\fR 4 |
| 941 |
.IX Item "--keep-file-symbols" |
| 942 |
When stripping a file, perhaps with \fB\-\-strip\-debug\fR or |
| 943 |
\&\fB\-\-strip\-unneeded\fR, retain any symbols specifying source file names, |
| 944 |
which would otherwise get stripped. |
| 945 |
.IP \fB\-\-only\-keep\-debug\fR 4 |
| 946 |
.IX Item "--only-keep-debug" |
| 947 |
Strip a file, removing contents of any sections that would not be |
| 948 |
stripped by \fB\-\-strip\-debug\fR and leaving the debugging sections |
| 949 |
intact. In ELF files, this preserves all note sections in the output. |
| 950 |
.Sp |
| 951 |
Note \- the section headers of the stripped sections are preserved, |
| 952 |
including their sizes, but the contents of the section are discarded. |
| 953 |
The section headers are preserved so that other tools can match up the |
| 954 |
debuginfo file with the real executable, even if that executable has |
| 955 |
been relocated to a different address space. |
| 956 |
.Sp |
| 957 |
The intention is that this option will be used in conjunction with |
| 958 |
\&\fB\-\-add\-gnu\-debuglink\fR to create a two part executable. One a |
| 959 |
stripped binary which will occupy less space in RAM and in a |
| 960 |
distribution and the second a debugging information file which is only |
| 961 |
needed if debugging abilities are required. The suggested procedure |
| 962 |
to create these files is as follows: |
| 963 |
.RS 4 |
| 964 |
.IP 1. 4 |
| 965 |
Link the executable as normal. Assuming that it is called \f(CW\*(C`foo\*(C'\fR |
| 966 |
then... |
| 967 |
.IP 2. 4 |
| 968 |
Run \f(CW\*(C`objcopy \-\-only\-keep\-debug foo foo.dbg\*(C'\fR to create a file |
| 969 |
containing the debugging info. |
| 970 |
.IP 3. 4 |
| 971 |
Run \f(CW\*(C`objcopy \-\-strip\-debug foo\*(C'\fR to create a stripped executable. |
| 972 |
.IP 4. 4 |
| 973 |
Run \f(CW\*(C`objcopy \-\-add\-gnu\-debuglink=foo.dbg foo\*(C'\fR to add a link to the |
| 974 |
debugging info into the stripped executable. |
| 975 |
.RE |
| 976 |
.RS 4 |
| 977 |
.Sp |
| 978 |
Note\-\-\-the choice of \f(CW\*(C`.dbg\*(C'\fR as an extension for the debug info |
| 979 |
file is arbitrary. Also the \f(CW\*(C`\-\-only\-keep\-debug\*(C'\fR step is |
| 980 |
optional. You could instead do this: |
| 981 |
.IP 1. 4 |
| 982 |
Link the executable as normal. |
| 983 |
.IP 2. 4 |
| 984 |
Copy \f(CW\*(C`foo\*(C'\fR to \f(CW\*(C`foo.full\*(C'\fR. |
| 985 |
.IP 3. 4 |
| 986 |
Run \f(CW\*(C`objcopy \-\-strip\-debug foo\*(C'\fR. |
| 987 |
.IP 4. 4 |
| 988 |
Run \f(CW\*(C`objcopy \-\-add\-gnu\-debuglink=foo.full foo\*(C'\fR. |
| 989 |
.RE |
| 990 |
.RS 4 |
| 991 |
.Sp |
| 992 |
i.e., the file pointed to by the \fB\-\-add\-gnu\-debuglink\fR can be the |
| 993 |
full executable. It does not have to be a file created by the |
| 994 |
\&\fB\-\-only\-keep\-debug\fR switch. |
| 995 |
.Sp |
| 996 |
Note\-\-\-this switch is only intended for use on fully linked files. It |
| 997 |
does not make sense to use it on object files where the debugging |
| 998 |
information may be incomplete. Besides the gnu_debuglink feature |
| 999 |
currently only supports the presence of one filename containing |
| 1000 |
debugging information, not multiple filenames on a one-per-object-file |
| 1001 |
basis. |
| 1002 |
.RE |
| 1003 |
.IP \fB\-\-strip\-dwo\fR 4 |
| 1004 |
.IX Item "--strip-dwo" |
| 1005 |
Remove the contents of all DWARF .dwo sections, leaving the |
| 1006 |
remaining debugging sections and all symbols intact. |
| 1007 |
This option is intended for use by the compiler as part of |
| 1008 |
the \fB\-gsplit\-dwarf\fR option, which splits debug information |
| 1009 |
between the .o file and a separate .dwo file. The compiler |
| 1010 |
generates all debug information in the same file, then uses |
| 1011 |
the \fB\-\-extract\-dwo\fR option to copy the .dwo sections to |
| 1012 |
the .dwo file, then the \fB\-\-strip\-dwo\fR option to remove |
| 1013 |
those sections from the original .o file. |
| 1014 |
.IP \fB\-\-extract\-dwo\fR 4 |
| 1015 |
.IX Item "--extract-dwo" |
| 1016 |
Extract the contents of all DWARF .dwo sections. See the |
| 1017 |
\&\fB\-\-strip\-dwo\fR option for more information. |
| 1018 |
.IP "\fB\-\-file\-alignment\fR \fInum\fR" 4 |
| 1019 |
.IX Item "--file-alignment num" |
| 1020 |
Specify the file alignment. Sections in the file will always begin at |
| 1021 |
file offsets which are multiples of this number. This defaults to |
| 1022 |
512. |
| 1023 |
[This option is specific to PE targets.] |
| 1024 |
.IP "\fB\-\-heap\fR \fIreserve\fR" 4 |
| 1025 |
.IX Item "--heap reserve" |
| 1026 |
.PD 0 |
| 1027 |
.IP "\fB\-\-heap\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4 |
| 1028 |
.IX Item "--heap reserve,commit" |
| 1029 |
.PD |
| 1030 |
Specify the number of bytes of memory to reserve (and optionally commit) |
| 1031 |
to be used as heap for this program. |
| 1032 |
[This option is specific to PE targets.] |
| 1033 |
.IP "\fB\-\-image\-base\fR \fIvalue\fR" 4 |
| 1034 |
.IX Item "--image-base value" |
| 1035 |
Use \fIvalue\fR as the base address of your program or dll. This is |
| 1036 |
the lowest memory location that will be used when your program or dll |
| 1037 |
is loaded. To reduce the need to relocate and improve performance of |
| 1038 |
your dlls, each should have a unique base address and not overlap any |
| 1039 |
other dlls. The default is 0x400000 for executables, and 0x10000000 |
| 1040 |
for dlls. |
| 1041 |
[This option is specific to PE targets.] |
| 1042 |
.IP "\fB\-\-section\-alignment\fR \fInum\fR" 4 |
| 1043 |
.IX Item "--section-alignment num" |
| 1044 |
[This option is specific to PE targets.] |
| 1045 |
.Sp |
| 1046 |
Sets the section alignment field in the PE header \- if one is present |
| 1047 |
in the binary. Sections in memory will always begin at addresses |
| 1048 |
which are a multiple of this number. Defaults to 0x1000. |
| 1049 |
.Sp |
| 1050 |
Note \- if a section's LMA or VMA addresses are no longer aligned, and |
| 1051 |
those addresses have not been set via the \fB\-\-set\-section\-lma\fR or |
| 1052 |
\&\fB\-\-set\-section\-vma\fR options, and the file has been fully |
| 1053 |
relocated then a warning message will be issued. It will then be up |
| 1054 |
to the user to decide if the LMA and VMA need updating. |
| 1055 |
.IP "\fB\-\-stack\fR \fIreserve\fR" 4 |
| 1056 |
.IX Item "--stack reserve" |
| 1057 |
.PD 0 |
| 1058 |
.IP "\fB\-\-stack\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4 |
| 1059 |
.IX Item "--stack reserve,commit" |
| 1060 |
.PD |
| 1061 |
Specify the number of bytes of memory to reserve (and optionally commit) |
| 1062 |
to be used as stack for this program. |
| 1063 |
[This option is specific to PE targets.] |
| 1064 |
.IP "\fB\-\-subsystem\fR \fIwhich\fR" 4 |
| 1065 |
.IX Item "--subsystem which" |
| 1066 |
.PD 0 |
| 1067 |
.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR" 4 |
| 1068 |
.IX Item "--subsystem which:major" |
| 1069 |
.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR\fB.\fR\fIminor\fR" 4 |
| 1070 |
.IX Item "--subsystem which:major.minor" |
| 1071 |
.PD |
| 1072 |
Specifies the subsystem under which your program will execute. The |
| 1073 |
legal values for \fIwhich\fR are \f(CW\*(C`native\*(C'\fR, \f(CW\*(C`windows\*(C'\fR, |
| 1074 |
\&\f(CW\*(C`console\*(C'\fR, \f(CW\*(C`posix\*(C'\fR, \f(CW\*(C`efi\-app\*(C'\fR, \f(CW\*(C`efi\-bsd\*(C'\fR, |
| 1075 |
\&\f(CW\*(C`efi\-rtd\*(C'\fR, \f(CW\*(C`sal\-rtd\*(C'\fR, and \f(CW\*(C`xbox\*(C'\fR. You may optionally set |
| 1076 |
the subsystem version also. Numeric values are also accepted for |
| 1077 |
\&\fIwhich\fR. |
| 1078 |
[This option is specific to PE targets.] |
| 1079 |
.IP \fB\-\-extract\-symbol\fR 4 |
| 1080 |
.IX Item "--extract-symbol" |
| 1081 |
Keep the file's section flags and symbols but remove all section data. |
| 1082 |
Specifically, this option: |
| 1083 |
.RS 4 |
| 1084 |
.IP \(bu 4 |
| 1085 |
Removes the contents of all sections. |
| 1086 |
.IP \(bu 4 |
| 1087 |
Sets the size of every section to zero. |
| 1088 |
.IP \(bu 4 |
| 1089 |
Sets the file's start address to zero. |
| 1090 |
.RE |
| 1091 |
.RS 4 |
| 1092 |
.Sp |
| 1093 |
This option is used to build a \fI.sym\fR file for a VxWorks kernel. |
| 1094 |
It can also be a useful way of reducing the size of a \fB\-\-just\-symbols\fR |
| 1095 |
linker input file. |
| 1096 |
.RE |
| 1097 |
.IP \fB\-\-compress\-debug\-sections\fR 4 |
| 1098 |
.IX Item "--compress-debug-sections" |
| 1099 |
Compress DWARF debug sections using zlib with SHF_COMPRESSED from the |
| 1100 |
ELF ABI. Note \- if compression would actually make a section |
| 1101 |
\&\fIlarger\fR, then it is not compressed. |
| 1102 |
.IP \fB\-\-compress\-debug\-sections=none\fR 4 |
| 1103 |
.IX Item "--compress-debug-sections=none" |
| 1104 |
.PD 0 |
| 1105 |
.IP \fB\-\-compress\-debug\-sections=zlib\fR 4 |
| 1106 |
.IX Item "--compress-debug-sections=zlib" |
| 1107 |
.IP \fB\-\-compress\-debug\-sections=zlib\-gnu\fR 4 |
| 1108 |
.IX Item "--compress-debug-sections=zlib-gnu" |
| 1109 |
.IP \fB\-\-compress\-debug\-sections=zlib\-gabi\fR 4 |
| 1110 |
.IX Item "--compress-debug-sections=zlib-gabi" |
| 1111 |
.IP \fB\-\-compress\-debug\-sections=zstd\fR 4 |
| 1112 |
.IX Item "--compress-debug-sections=zstd" |
| 1113 |
.PD |
| 1114 |
For ELF files, these options control how DWARF debug sections are |
| 1115 |
compressed. \fB\-\-compress\-debug\-sections=none\fR is equivalent |
| 1116 |
to \fB\-\-decompress\-debug\-sections\fR. |
| 1117 |
\&\fB\-\-compress\-debug\-sections=zlib\fR and |
| 1118 |
\&\fB\-\-compress\-debug\-sections=zlib\-gabi\fR are equivalent to |
| 1119 |
\&\fB\-\-compress\-debug\-sections\fR. |
| 1120 |
\&\fB\-\-compress\-debug\-sections=zlib\-gnu\fR compresses DWARF debug sections |
| 1121 |
using the obsoleted zlib-gnu format. The debug sections are renamed to begin |
| 1122 |
with \fB.zdebug\fR. |
| 1123 |
\&\fB\-\-compress\-debug\-sections=zstd\fR compresses DWARF debug |
| 1124 |
sections using zstd. Note \- if compression would actually make a section |
| 1125 |
\&\fIlarger\fR, then it is not compressed nor renamed. |
| 1126 |
.IP \fB\-\-decompress\-debug\-sections\fR 4 |
| 1127 |
.IX Item "--decompress-debug-sections" |
| 1128 |
Decompress DWARF debug sections. For a \fB.zdebug\fR section, the original |
| 1129 |
name is restored. |
| 1130 |
.IP \fB\-\-elf\-stt\-common=yes\fR 4 |
| 1131 |
.IX Item "--elf-stt-common=yes" |
| 1132 |
.PD 0 |
| 1133 |
.IP \fB\-\-elf\-stt\-common=no\fR 4 |
| 1134 |
.IX Item "--elf-stt-common=no" |
| 1135 |
.PD |
| 1136 |
For ELF files, these options control whether common symbols should be |
| 1137 |
converted to the \f(CW\*(C`STT_COMMON\*(C'\fR or \f(CW\*(C`STT_OBJECT\*(C'\fR type. |
| 1138 |
\&\fB\-\-elf\-stt\-common=yes\fR converts common symbol type to |
| 1139 |
\&\f(CW\*(C`STT_COMMON\*(C'\fR. \fB\-\-elf\-stt\-common=no\fR converts common symbol |
| 1140 |
type to \f(CW\*(C`STT_OBJECT\*(C'\fR. |
| 1141 |
.IP \fB\-\-merge\-notes\fR 4 |
| 1142 |
.IX Item "--merge-notes" |
| 1143 |
.PD 0 |
| 1144 |
.IP \fB\-\-no\-merge\-notes\fR 4 |
| 1145 |
.IX Item "--no-merge-notes" |
| 1146 |
.PD |
| 1147 |
For ELF files, attempt (or do not attempt) to reduce the size of any |
| 1148 |
SHT_NOTE type sections by removing duplicate notes. |
| 1149 |
.IP \fB\-V\fR 4 |
| 1150 |
.IX Item "-V" |
| 1151 |
.PD 0 |
| 1152 |
.IP \fB\-\-version\fR 4 |
| 1153 |
.IX Item "--version" |
| 1154 |
.PD |
| 1155 |
Show the version number of \fBobjcopy\fR. |
| 1156 |
.IP \fB\-\-verilog\-data\-width=\fR\fIbytes\fR 4 |
| 1157 |
.IX Item "--verilog-data-width=bytes" |
| 1158 |
For Verilog output, this options controls the number of bytes |
| 1159 |
converted for each output data element. The input target controls the |
| 1160 |
endianness of the conversion. |
| 1161 |
.IP \fB\-v\fR 4 |
| 1162 |
.IX Item "-v" |
| 1163 |
.PD 0 |
| 1164 |
.IP \fB\-\-verbose\fR 4 |
| 1165 |
.IX Item "--verbose" |
| 1166 |
.PD |
| 1167 |
Verbose output: list all object files modified. In the case of |
| 1168 |
archives, \fBobjcopy \-V\fR lists all members of the archive. |
| 1169 |
.IP \fB\-\-help\fR 4 |
| 1170 |
.IX Item "--help" |
| 1171 |
Show a summary of the options to \fBobjcopy\fR. |
| 1172 |
.IP \fB\-\-info\fR 4 |
| 1173 |
.IX Item "--info" |
| 1174 |
Display a list showing all architectures and object formats available. |
| 1175 |
.IP \fB@\fR\fIfile\fR 4 |
| 1176 |
.IX Item "@file" |
| 1177 |
Read command-line options from \fIfile\fR. The options read are |
| 1178 |
inserted in place of the original @\fIfile\fR option. If \fIfile\fR |
| 1179 |
does not exist, or cannot be read, then the option will be treated |
| 1180 |
literally, and not removed. |
| 1181 |
.Sp |
| 1182 |
Options in \fIfile\fR are separated by whitespace. A whitespace |
| 1183 |
character may be included in an option by surrounding the entire |
| 1184 |
option in either single or double quotes. Any character (including a |
| 1185 |
backslash) may be included by prefixing the character to be included |
| 1186 |
with a backslash. The \fIfile\fR may itself contain additional |
| 1187 |
@\fIfile\fR options; any such options will be processed recursively. |
| 1188 |
.SH "SEE ALSO" |
| 1189 |
.IX Header "SEE ALSO" |
| 1190 |
\&\fBld\fR\|(1), \fBobjdump\fR\|(1), and the Info entries for \fIbinutils\fR. |
| 1191 |
.SH COPYRIGHT |
| 1192 |
.IX Header "COPYRIGHT" |
| 1193 |
Copyright (c) 1991\-2026 Free Software Foundation, Inc. |
| 1194 |
.PP |
| 1195 |
Permission is granted to copy, distribute and/or modify this document |
| 1196 |
under the terms of the GNU Free Documentation License, Version 1.3 |
| 1197 |
or any later version published by the Free Software Foundation; |
| 1198 |
with no Invariant Sections, with no Front-Cover Texts, and with no |
| 1199 |
Back-Cover Texts. A copy of the license is included in the |
| 1200 |
section entitled "GNU Free Documentation License". |