1OBJCOPY(1) GNU Development Tools OBJCOPY(1)
2
6 objcopy - copy and translate object files
7
9 objcopy [-F bfdname|--target=bfdname]
10 [-I bfdname|--input-target=bfdname]
11 [-O bfdname|--output-target=bfdname]
12 [-B bfdarch|--binary-architecture=bfdarch]
13 [-S|--strip-all]
14 [-g|--strip-debug]
15 [--strip-unneeded]
16 [-K symbolname|--keep-symbol=symbolname]
17 [--keep-file-symbols]
18 [--keep-section-symbols]
19 [-N symbolname|--strip-symbol=symbolname]
20 [--strip-unneeded-symbol=symbolname]
21 [-G symbolname|--keep-global-symbol=symbolname]
22 [--localize-hidden]
23 [-L symbolname|--localize-symbol=symbolname]
24 [--globalize-symbol=symbolname]
25 [--globalize-symbols=filename]
26 [-W symbolname|--weaken-symbol=symbolname]
27 [-w|--wildcard]
28 [-x|--discard-all]
29 [-X|--discard-locals]
30 [-b byte|--byte=byte]
31 [-i [breadth]|--interleave[=breadth]]
32 [--interleave-width=width]
33 [-j sectionpattern|--only-section=sectionpattern]
34 [-R sectionpattern|--remove-section=sectionpattern]
35 [--keep-section=sectionpattern]
36 [--remove-relocations=sectionpattern]
37 [--strip-section-headers]
38 [-p|--preserve-dates]
39 [-D|--enable-deterministic-archives]
40 [-U|--disable-deterministic-archives]
41 [--debugging]
42 [--gap-fill=val]
43 [--pad-to=address]
44 [--set-start=val]
45 [--adjust-start=incr]
46 [--change-addresses=incr]
47 [--change-section-address sectionpattern{=,+,-}val]
48 [--change-section-lma sectionpattern{=,+,-}val]
49 [--change-section-vma sectionpattern{=,+,-}val]
50 [--change-warnings] [--no-change-warnings]
51 [--set-section-flags sectionpattern=flags]
52 [--set-section-alignment sectionpattern=align]
53 [--add-section sectionname=filename]
54 [--dump-section sectionname=filename]
55 [--update-section sectionname=filename]
56 [--rename-section oldname=newname[,flags]]
57 [--long-section-names {enable,disable,keep}]
58 [--change-leading-char] [--remove-leading-char]
59 [--reverse-bytes=num]
60 [--srec-len=ival] [--srec-forceS3]
61 [--redefine-sym old=new]
62 [--redefine-syms=filename]
63 [--weaken]
64 [--keep-symbols=filename]
65 [--strip-symbols=filename]
66 [--strip-unneeded-symbols=filename]
67 [--keep-global-symbols=filename]
68 [--localize-symbols=filename]
69 [--weaken-symbols=filename]
70 [--add-symbol name=[section:]value[,flags]]
71 [--alt-machine-code=index]
72 [--prefix-symbols=string]
73 [--prefix-sections=string]
74 [--prefix-alloc-sections=string]
75 [--add-gnu-debuglink=path-to-file]
76 [--only-keep-debug]
77 [--strip-dwo]
78 [--extract-dwo]
79 [--extract-symbol]
80 [--writable-text]
81 [--readonly-text]
82 [--pure]
83 [--impure]
84 [--file-alignment=num]
85 [--heap=size]
86 [--image-base=address]
87 [--section-alignment=num]
88 [--stack=size]
89 [--subsystem=which:major.minor]
90 [--compress-debug-sections]
91 [--decompress-debug-sections]
92 [--elf-stt-common=val]
93 [--merge-notes]
94 [--no-merge-notes]
95 [--verilog-data-width=val]
96 [-v|--verbose]
97 [-V|--version]
98 [--help] [--info]
99 infile [outfile]
100
102 The GNU objcopy utility copies the contents of an object file to
103 another. objcopy uses the GNU BFD Library to read and write the object
104 files. It can write the destination object file in a format different
105 from that of the source object file. The exact behavior of objcopy is
106 controlled by command-line options. Note that objcopy should be able
107 to copy a fully linked file between any two formats. However, copying a
108 relocatable object file between any two formats may not work as
109 expected.
110 objcopy creates temporary files to do its translations and deletes them
112 afterward. objcopy uses BFD to do all its translation work; it has
113 access to all the formats described in BFD and thus is able to
114 recognize most formats without being told explicitly.
115 objcopy can be used to generate S-records by using an output target of
117 srec (e.g., use -O srec).
118 objcopy can be used to generate a raw binary file by using an output
120 target of binary (e.g., use -O binary). When objcopy generates a raw
121 binary file, it will essentially produce a memory dump of the contents
122 of the input object file. All symbols and relocation information will
123 be discarded. The memory dump will start at the load address of the
124 lowest section copied into the output file.
125 When generating an S-record or a raw binary file, it may be helpful to
127 use -S to remove sections containing debugging information. In some
128 cases -R will be useful to remove sections which contain information
129 that is not needed by the binary file.
130 Note---objcopy is not able to change the endianness of its input files.
132 If the input format has an endianness (some formats do not), objcopy
133 can only copy the inputs into file formats that have the same
134 endianness or which have no endianness (e.g., srec). (However, see the
135 --reverse-bytes option.)
136
138 infile
139 outfile
140 The input and output files, respectively. If you do not specify
141 outfile, objcopy creates a temporary file and destructively renames
142 the result with the name of infile.
143 -I bfdname
145 --input-target=bfdname
146 Consider the source file's object format to be bfdname, rather than
147 attempting to deduce it.
148 -O bfdname
150 --output-target=bfdname
151 Write the output file using the object format bfdname.
152 -F bfdname
154 --target=bfdname
155 Use bfdname as the object format for both the input and the output
156 file; i.e., simply transfer data from source to destination with no
157 translation.
158 -B bfdarch
160 --binary-architecture=bfdarch
161 Useful when transforming a architecture-less input file into an
162 object file. In this case the output architecture can be set to
163 bfdarch. This option will be ignored if the input file has a known
164 bfdarch. You can access this binary data inside a program by
165 referencing the special symbols that are created by the conversion
166 process. These symbols are called _binary_objfile_start,
167 _binary_objfile_end and _binary_objfile_size. e.g. you can
168 transform a picture file into an object file and then access it in
169 your code using these symbols.
170 -j sectionpattern
172 --only-section=sectionpattern
173 Copy only the indicated sections from the input file to the output
174 file. This option may be given more than once. Note that using
175 this option inappropriately may make the output file unusable.
176 Wildcard characters are accepted in sectionpattern.
177 If the first character of sectionpattern is the exclamation point
179 (!) then matching sections will not be copied, even if earlier use
180 of --only-section on the same command line would otherwise copy it.
181 For example:
182 --only-section=.text.* --only-section=!.text.foo
184 will copy all sectinos matching '.text.*' but not the section
186 '.text.foo'.
187 -R sectionpattern
189 --remove-section=sectionpattern
190 Remove any section matching sectionpattern from the output file.
191 This option may be given more than once. Note that using this
192 option inappropriately may make the output file unusable. Wildcard
193 characters are accepted in sectionpattern. Using both the -j and
194 -R options together results in undefined behaviour.
195 If the first character of sectionpattern is the exclamation point
197 (!) then matching sections will not be removed even if an earlier
198 use of --remove-section on the same command line would otherwise
199 remove it. For example:
200 --remove-section=.text.* --remove-section=!.text.foo
202 will remove all sections matching the pattern '.text.*', but will
204 not remove the section '.text.foo'.
205 --keep-section=sectionpattern
207 When removing sections from the output file, keep sections that
208 match sectionpattern.
209 --remove-relocations=sectionpattern
211 Remove non-dynamic relocations from the output file for any section
212 matching sectionpattern. This option may be given more than once.
213 Note that using this option inappropriately may make the output
214 file unusable, and attempting to remove a dynamic relocation
215 section such as .rela.plt from an executable or shared library with
216 --remove-relocations=.plt will not work. Wildcard characters are
217 accepted in sectionpattern. For example:
218 --remove-relocations=.text.*
220 will remove the relocations for all sections matching the pattern
222 '.text.*'.
223 If the first character of sectionpattern is the exclamation point
225 (!) then matching sections will not have their relocation removed
226 even if an earlier use of --remove-relocations on the same command
227 line would otherwise cause the relocations to be removed. For
228 example:
229 --remove-relocations=.text.* --remove-relocations=!.text.foo
231 will remove all relocations for sections matching the pattern
233 '.text.*', but will not remove relocations for the section
234 '.text.foo'.
235 --strip-section-headers
237 Strip section header This option is specific to ELF files.
238 Implies --strip-all and --merge-notes.
239 -S
241 --strip-all
242 Do not copy relocation and symbol information from the source file.
243 Also deletes debug sections.
244 -g
246 --strip-debug
247 Do not copy debugging symbols or sections from the source file.
248 --strip-unneeded
250 Remove all symbols that are not needed for relocation processing in
251 addition to debugging symbols and sections stripped by
252 --strip-debug.
253 -K symbolname
255 --keep-symbol=symbolname
256 When stripping symbols, keep symbol symbolname even if it would
257 normally be stripped. This option may be given more than once.
258 -N symbolname
260 --strip-symbol=symbolname
261 Do not copy symbol symbolname from the source file. This option
262 may be given more than once.
263 --strip-unneeded-symbol=symbolname
265 Do not copy symbol symbolname from the source file unless it is
266 needed by a relocation. This option may be given more than once.
267 -G symbolname
269 --keep-global-symbol=symbolname
270 Keep only symbol symbolname global. Make all other symbols local
271 to the file, so that they are not visible externally. This option
272 may be given more than once. Note: this option cannot be used in
273 conjunction with the --globalize-symbol or --globalize-symbols
274 options.
275 --localize-hidden
277 In an ELF object, mark all symbols that have hidden or internal
278 visibility as local. This option applies on top of symbol-specific
279 localization options such as -L.
280 -L symbolname
282 --localize-symbol=symbolname
283 Convert a global or weak symbol called symbolname into a local
284 symbol, so that it is not visible externally. This option may be
285 given more than once. Note - unique symbols are not converted.
286 -W symbolname
288 --weaken-symbol=symbolname
289 Make symbol symbolname weak. This option may be given more than
290 once.
291 --globalize-symbol=symbolname
293 Give symbol symbolname global scoping so that it is visible outside
294 of the file in which it is defined. This option may be given more
295 than once. Note: this option cannot be used in conjunction with
296 the -G or --keep-global-symbol options.
297 -w
299 --wildcard
300 Permit regular expressions in symbolnames used in other command
301 line options. The question mark (?), asterisk (*), backslash (\)
302 and square brackets ([]) operators can be used anywhere in the
303 symbol name. If the first character of the symbol name is the
304 exclamation point (!) then the sense of the switch is reversed for
305 that symbol. For example:
306 -w -W !foo -W fo*
308 would cause objcopy to weaken all symbols that start with "fo"
310 except for the symbol "foo".
311 -x
313 --discard-all
314 Do not copy non-global symbols from the source file.
315 -X
317 --discard-locals
318 Do not copy compiler-generated local symbols. (These usually start
319 with L or ..)
320 -b byte
322 --byte=byte
323 If interleaving has been enabled via the --interleave option then
324 start the range of bytes to keep at the byteth byte. byte can be
325 in the range from 0 to breadth-1, where breadth is the value given
326 by the --interleave option.
327 -i [breadth]
329 --interleave[=breadth]
330 Only copy a range out of every breadth bytes. (Header data is not
331 affected). Select which byte in the range begins the copy with the
332 --byte option. Select the width of the range with the
333 --interleave-width option.
334 This option is useful for creating files to program ROM. It is
336 typically used with an "srec" output target. Note that objcopy
337 will complain if you do not specify the --byte option as well.
338 The default interleave breadth is 4, so with --byte set to 0,
340 objcopy would copy the first byte out of every four bytes from the
341 input to the output.
342 --interleave-width=width
344 When used with the --interleave option, copy width bytes at a time.
345 The start of the range of bytes to be copied is set by the --byte
346 option, and the extent of the range is set with the --interleave
347 option.
348 The default value for this option is 1. The value of width plus
350 the byte value set by the --byte option must not exceed the
351 interleave breadth set by the --interleave option.
352 This option can be used to create images for two 16-bit flashes
354 interleaved in a 32-bit bus by passing -b 0 -i 4
355 --interleave-width=2 and -b 2 -i 4 --interleave-width=2 to two
356 objcopy commands. If the input was '12345678' then the outputs
357 would be '1256' and '3478' respectively.
358 -p
360 --preserve-dates
361 Set the access and modification dates of the output file to be the
362 same as those of the input file.
363 -D
365 --enable-deterministic-archives
366 Operate in deterministic mode. When copying archive members and
367 writing the archive index, use zero for UIDs, GIDs, timestamps, and
368 use consistent file modes for all files.
369 If binutils was configured with --enable-deterministic-archives,
371 then this mode is on by default. It can be disabled with the -U
372 option, below.
373 -U
375 --disable-deterministic-archives
376 Do not operate in deterministic mode. This is the inverse of the
377 -D option, above: when copying archive members and writing the
378 archive index, use their actual UID, GID, timestamp, and file mode
379 values.
380 This is the default unless binutils was configured with
382 --enable-deterministic-archives.
383 --debugging
385 Convert debugging information, if possible. This is not the
386 default because only certain debugging formats are supported, and
387 the conversion process can be time consuming.
388 --gap-fill val
390 Fill gaps between sections with val. This operation applies to the
391 load address (LMA) of the sections. It is done by increasing the
392 size of the section with the lower address, and filling in the
393 extra space created with val.
394 --pad-to address
396 Pad the output file up to the load address address. This is done
397 by increasing the size of the last section. The extra space is
398 filled in with the value specified by --gap-fill (default zero).
399 --set-start val
401 Set the start address (also known as the entry address) of the new
402 file to val. Not all object file formats support setting the start
403 address.
404 --change-start incr
406 --adjust-start incr
407 Change the start address (also known as the entry address) by
408 adding incr. Not all object file formats support setting the start
409 address.
410 --change-addresses incr
412 --adjust-vma incr
413 Change the VMA and LMA addresses of all sections, as well as the
414 start address, by adding incr. Some object file formats do not
415 permit section addresses to be changed arbitrarily. Note that this
416 does not relocate the sections; if the program expects sections to
417 be loaded at a certain address, and this option is used to change
418 the sections such that they are loaded at a different address, the
419 program may fail.
420 --change-section-address sectionpattern{=,+,-}val
422 --adjust-section-vma sectionpattern{=,+,-}val
423 Set or change both the VMA address and the LMA address of any
424 section matching sectionpattern. If = is used, the section address
425 is set to val. Otherwise, val is added to or subtracted from the
426 section address. See the comments under --change-addresses, above.
427 If sectionpattern does not match any sections in the input file, a
428 warning will be issued, unless --no-change-warnings is used.
429 --change-section-lma sectionpattern{=,+,-}val
431 Set or change the LMA address of any sections matching
432 sectionpattern. The LMA address is the address where the section
433 will be loaded into memory at program load time. Normally this is
434 the same as the VMA address, which is the address of the section at
435 program run time, but on some systems, especially those where a
436 program is held in ROM, the two can be different. If = is used,
437 the section address is set to val. Otherwise, val is added to or
438 subtracted from the section address. See the comments under
439 --change-addresses, above. If sectionpattern does not match any
440 sections in the input file, a warning will be issued, unless
441 --no-change-warnings is used.
442 --change-section-vma sectionpattern{=,+,-}val
444 Set or change the VMA address of any section matching
445 sectionpattern. The VMA address is the address where the section
446 will be located once the program has started executing. Normally
447 this is the same as the LMA address, which is the address where the
448 section will be loaded into memory, but on some systems, especially
449 those where a program is held in ROM, the two can be different. If
450 = is used, the section address is set to val. Otherwise, val is
451 added to or subtracted from the section address. See the comments
452 under --change-addresses, above. If sectionpattern does not match
453 any sections in the input file, a warning will be issued, unless
454 --no-change-warnings is used.
455 --change-warnings
457 --adjust-warnings
458 If --change-section-address or --change-section-lma or
459 --change-section-vma is used, and the section pattern does not
460 match any sections, issue a warning. This is the default.
461 --no-change-warnings
463 --no-adjust-warnings
464 Do not issue a warning if --change-section-address or
465 --adjust-section-lma or --adjust-section-vma is used, even if the
466 section pattern does not match any sections.
467 --set-section-flags sectionpattern=flags
469 Set the flags for any sections matching sectionpattern. The flags
470 argument is a comma separated string of flag names. The recognized
471 names are alloc, contents, load, noload, readonly, code, data, rom,
472 exclude, share, and debug. You can set the contents flag for a
473 section which does not have contents, but it is not meaningful to
474 clear the contents flag of a section which does have contents--just
475 remove the section instead. Not all flags are meaningful for all
476 object file formats. In particular the share flag is only
477 meaningful for COFF format files and not for ELF format files.
478 --set-section-alignment sectionpattern=align
480 Set the alignment for any sections matching sectionpattern. align
481 specifies the alignment in bytes and must be a power of two, i.e.
482 1, 2, 4, 8....
483 --add-section sectionname=filename
485 Add a new section named sectionname while copying the file. The
486 contents of the new section are taken from the file filename. The
487 size of the section will be the size of the file. This option only
488 works on file formats which can support sections with arbitrary
489 names. Note - it may be necessary to use the --set-section-flags
490 option to set the attributes of the newly created section.
491 --dump-section sectionname=filename
493 Place the contents of section named sectionname into the file
494 filename, overwriting any contents that may have been there
495 previously. This option is the inverse of --add-section. This
496 option is similar to the --only-section option except that it does
497 not create a formatted file, it just dumps the contents as raw
498 binary data, without applying any relocations. The option can be
499 specified more than once.
500 --update-section sectionname=filename
502 Replace the existing contents of a section named sectionname with
503 the contents of file filename. The size of the section will be
504 adjusted to the size of the file. The section flags for
505 sectionname will be unchanged. For ELF format files the section to
506 segment mapping will also remain unchanged, something which is not
507 possible using --remove-section followed by --add-section. The
508 option can be specified more than once.
509 Note - it is possible to use --rename-section and --update-section
511 to both update and rename a section from one command line. In this
512 case, pass the original section name to --update-section, and the
513 original and new section names to --rename-section.
514 --add-symbol name=[section:]value[,flags]
516 Add a new symbol named name while copying the file. This option
517 may be specified multiple times. If the section is given, the
518 symbol will be associated with and relative to that section,
519 otherwise it will be an ABS symbol. Specifying an undefined
520 section will result in a fatal error. There is no check for the
521 value, it will be taken as specified. Symbol flags can be
522 specified and not all flags will be meaningful for all object file
523 formats. By default, the symbol will be global. The special flag
524 'before=othersym' will insert the new symbol in front of the
525 specified othersym, otherwise the symbol(s) will be added at the
526 end of the symbol table in the order they appear.
527 --rename-section oldname=newname[,flags]
529 Rename a section from oldname to newname, optionally changing the
530 section's flags to flags in the process. This has the advantage
531 over using a linker script to perform the rename in that the output
532 stays as an object file and does not become a linked executable.
533 This option accepts the same set of flags as the
534 --sect-section-flags option.
535 This option is particularly helpful when the input format is
537 binary, since this will always create a section called .data. If
538 for example, you wanted instead to create a section called .rodata
539 containing binary data you could use the following command line to
540 achieve it:
541 objcopy -I binary -O <output_format> -B <architecture> \
543 --rename-section .data=.rodata,alloc,load,readonly,data,contents \
544 <input_binary_file> <output_object_file>
545 --long-section-names {enable,disable,keep}
547 Controls the handling of long section names when processing "COFF"
548 and "PE-COFF" object formats. The default behaviour, keep, is to
549 preserve long section names if any are present in the input file.
550 The enable and disable options forcibly enable or disable the use
551 of long section names in the output object; when disable is in
552 effect, any long section names in the input object will be
553 truncated. The enable option will only emit long section names if
554 any are present in the inputs; this is mostly the same as keep, but
555 it is left undefined whether the enable option might force the
556 creation of an empty string table in the output file.
557 --change-leading-char
559 Some object file formats use special characters at the start of
560 symbols. The most common such character is underscore, which
561 compilers often add before every symbol. This option tells objcopy
562 to change the leading character of every symbol when it converts
563 between object file formats. If the object file formats use the
564 same leading character, this option has no effect. Otherwise, it
565 will add a character, or remove a character, or change a character,
566 as appropriate.
567 --remove-leading-char
569 If the first character of a global symbol is a special symbol
570 leading character used by the object file format, remove the
571 character. The most common symbol leading character is underscore.
572 This option will remove a leading underscore from all global
573 symbols. This can be useful if you want to link together objects
574 of different file formats with different conventions for symbol
575 names. This is different from --change-leading-char because it
576 always changes the symbol name when appropriate, regardless of the
577 object file format of the output file.
578 --reverse-bytes=num
580 Reverse the bytes in a section with output contents. A section
581 length must be evenly divisible by the value given in order for the
582 swap to be able to take place. Reversing takes place before the
583 interleaving is performed.
584 This option is used typically in generating ROM images for
586 problematic target systems. For example, on some target boards,
587 the 32-bit words fetched from 8-bit ROMs are re-assembled in
588 little-endian byte order regardless of the CPU byte order.
589 Depending on the programming model, the endianness of the ROM may
590 need to be modified.
591 Consider a simple file with a section containing the following
593 eight bytes: 12345678.
594 Using --reverse-bytes=2 for the above example, the bytes in the
596 output file would be ordered 21436587.
597 Using --reverse-bytes=4 for the above example, the bytes in the
599 output file would be ordered 43218765.
600 By using --reverse-bytes=2 for the above example, followed by
602 --reverse-bytes=4 on the output file, the bytes in the second
603 output file would be ordered 34127856.
604 --srec-len=ival
606 Meaningful only for srec output. Set the maximum length of the
607 Srecords being produced to ival. This length covers both address,
608 data and crc fields.
609 --srec-forceS3
611 Meaningful only for srec output. Avoid generation of S1/S2
612 records, creating S3-only record format.
613 --redefine-sym old=new
615 Change the name of a symbol old, to new. This can be useful when
616 one is trying link two things together for which you have no
617 source, and there are name collisions.
618 --redefine-syms=filename
620 Apply --redefine-sym to each symbol pair "old new" listed in the
621 file filename. filename is simply a flat file, with one symbol
622 pair per line. Line comments may be introduced by the hash
623 character. This option may be given more than once.
624 --weaken
626 Change all global symbols in the file to be weak. This can be
627 useful when building an object which will be linked against other
628 objects using the -R option to the linker. This option is only
629 effective when using an object file format which supports weak
630 symbols.
631 --keep-symbols=filename
633 Apply --keep-symbol option to each symbol listed in the file
634 filename. filename is simply a flat file, with one symbol name per
635 line. Line comments may be introduced by the hash character. This
636 option may be given more than once.
637 --strip-symbols=filename
639 Apply --strip-symbol option to each symbol listed in the file
640 filename. filename is simply a flat file, with one symbol name per
641 line. Line comments may be introduced by the hash character. This
642 option may be given more than once.
643 --strip-unneeded-symbols=filename
645 Apply --strip-unneeded-symbol option to each symbol listed in the
646 file filename. filename is simply a flat file, with one symbol
647 name per line. Line comments may be introduced by the hash
648 character. This option may be given more than once.
649 --keep-global-symbols=filename
651 Apply --keep-global-symbol option to each symbol listed in the file
652 filename. filename is simply a flat file, with one symbol name per
653 line. Line comments may be introduced by the hash character. This
654 option may be given more than once.
655 --localize-symbols=filename
657 Apply --localize-symbol option to each symbol listed in the file
658 filename. filename is simply a flat file, with one symbol name per
659 line. Line comments may be introduced by the hash character. This
660 option may be given more than once.
661 --globalize-symbols=filename
663 Apply --globalize-symbol option to each symbol listed in the file
664 filename. filename is simply a flat file, with one symbol name per
665 line. Line comments may be introduced by the hash character. This
666 option may be given more than once. Note: this option cannot be
667 used in conjunction with the -G or --keep-global-symbol options.
668 --weaken-symbols=filename
670 Apply --weaken-symbol option to each symbol listed in the file
671 filename. filename is simply a flat file, with one symbol name per
672 line. Line comments may be introduced by the hash character. This
673 option may be given more than once.
674 --alt-machine-code=index
676 If the output architecture has alternate machine codes, use the
677 indexth code instead of the default one. This is useful in case a
678 machine is assigned an official code and the tool-chain adopts the
679 new code, but other applications still depend on the original code
680 being used. For ELF based architectures if the index alternative
681 does not exist then the value is treated as an absolute number to
682 be stored in the e_machine field of the ELF header.
683 --writable-text
685 Mark the output text as writable. This option isn't meaningful for
686 all object file formats.
687 --readonly-text
689 Make the output text write protected. This option isn't meaningful
690 for all object file formats.
691 --pure
693 Mark the output file as demand paged. This option isn't meaningful
694 for all object file formats.
695 --impure
697 Mark the output file as impure. This option isn't meaningful for
698 all object file formats.
699 --prefix-symbols=string
701 Prefix all symbols in the output file with string.
702 --prefix-sections=string
704 Prefix all section names in the output file with string.
705 --prefix-alloc-sections=string
707 Prefix all the names of all allocated sections in the output file
708 with string.
709 --add-gnu-debuglink=path-to-file
711 Creates a .gnu_debuglink section which contains a reference to
712 path-to-file and adds it to the output file. Note: the file at
713 path-to-file must exist. Part of the process of adding the
714 .gnu_debuglink section involves embedding a checksum of the
715 contents of the debug info file into the section.
716 If the debug info file is built in one location but it is going to
718 be installed at a later time into a different location then do not
719 use the path to the installed location. The --add-gnu-debuglink
720 option will fail because the installed file does not exist yet.
721 Instead put the debug info file in the current directory and use
722 the --add-gnu-debuglink option without any directory components,
723 like this:
724 objcopy --add-gnu-debuglink=foo.debug
726 At debug time the debugger will attempt to look for the separate
728 debug info file in a set of known locations. The exact set of
729 these locations varies depending upon the distribution being used,
730 but it typically includes:
731 "* The same directory as the executable."
733 "* A sub-directory of the directory containing the executable"
734 called .debug
735 "* A global debug directory such as /usr/lib/debug."
737 As long as the debug info file has been installed into one of these
739 locations before the debugger is run everything should work
740 correctly.
741 --keep-section-symbils
743 When stripping a file, perhaps with --strip-debug or
744 --strip-unneeded, retain any symbols specifying section names,
745 which would otherwise get stripped.
746 --keep-file-symbols
748 When stripping a file, perhaps with --strip-debug or
749 --strip-unneeded, retain any symbols specifying source file names,
750 which would otherwise get stripped.
751 --only-keep-debug
753 Strip a file, removing contents of any sections that would not be
754 stripped by --strip-debug and leaving the debugging sections
755 intact. In ELF files, this preserves all note sections in the
756 output.
757 Note - the section headers of the stripped sections are preserved,
759 including their sizes, but the contents of the section are
760 discarded. The section headers are preserved so that other tools
761 can match up the debuginfo file with the real executable, even if
762 that executable has been relocated to a different address space.
763 The intention is that this option will be used in conjunction with
765 --add-gnu-debuglink to create a two part executable. One a
766 stripped binary which will occupy less space in RAM and in a
767 distribution and the second a debugging information file which is
768 only needed if debugging abilities are required. The suggested
769 procedure to create these files is as follows:
770 1.<Link the executable as normal. Assuming that it is called>
772 "foo" then...
773 1.<Run "objcopy --only-keep-debug foo foo.dbg" to>
775 create a file containing the debugging info.
776 1.<Run "objcopy --strip-debug foo" to create a>
778 stripped executable.
779 1.<Run "objcopy --add-gnu-debuglink=foo.dbg foo">
781 to add a link to the debugging info into the stripped
782 executable.
783 Note---the choice of ".dbg" as an extension for the debug info file
785 is arbitrary. Also the "--only-keep-debug" step is optional. You
786 could instead do this:
787 1.<Link the executable as normal.>
789 1.<Copy "foo" to "foo.full">
790 1.<Run "objcopy --strip-debug foo">
791 1.<Run "objcopy --add-gnu-debuglink=foo.full foo">
792 i.e., the file pointed to by the --add-gnu-debuglink can be the
794 full executable. It does not have to be a file created by the
795 --only-keep-debug switch.
796 Note---this switch is only intended for use on fully linked files.
798 It does not make sense to use it on object files where the
799 debugging information may be incomplete. Besides the gnu_debuglink
800 feature currently only supports the presence of one filename
801 containing debugging information, not multiple filenames on a one-
802 per-object-file basis.
803 --strip-dwo
805 Remove the contents of all DWARF .dwo sections, leaving the
806 remaining debugging sections and all symbols intact. This option
807 is intended for use by the compiler as part of the -gsplit-dwarf
808 option, which splits debug information between the .o file and a
809 separate .dwo file. The compiler generates all debug information
810 in the same file, then uses the --extract-dwo option to copy the
811 .dwo sections to the .dwo file, then the --strip-dwo option to
812 remove those sections from the original .o file.
813 --extract-dwo
815 Extract the contents of all DWARF .dwo sections. See the
816 --strip-dwo option for more information.
817 --file-alignment num
819 Specify the file alignment. Sections in the file will always begin
820 at file offsets which are multiples of this number. This defaults
821 to 512. [This option is specific to PE targets.]
822 --heap reserve
824 --heap reserve,commit
825 Specify the number of bytes of memory to reserve (and optionally
826 commit) to be used as heap for this program. [This option is
827 specific to PE targets.]
828 --image-base value
830 Use value as the base address of your program or dll. This is the
831 lowest memory location that will be used when your program or dll
832 is loaded. To reduce the need to relocate and improve performance
833 of your dlls, each should have a unique base address and not
834 overlap any other dlls. The default is 0x400000 for executables,
835 and 0x10000000 for dlls. [This option is specific to PE targets.]
836 --section-alignment num
838 Sets the section alignment field in the PE header. Sections in
839 memory will always begin at addresses which are a multiple of this
840 number. Defaults to 0x1000. [This option is specific to PE
841 targets.]
842 --stack reserve
844 --stack reserve,commit
845 Specify the number of bytes of memory to reserve (and optionally
846 commit) to be used as stack for this program. [This option is
847 specific to PE targets.]
848 --subsystem which
850 --subsystem which:major
851 --subsystem which:major.minor
852 Specifies the subsystem under which your program will execute. The
853 legal values for which are "native", "windows", "console", "posix",
854 "efi-app", "efi-bsd", "efi-rtd", "sal-rtd", and "xbox". You may
855 optionally set the subsystem version also. Numeric values are also
856 accepted for which. [This option is specific to PE targets.]
857 --extract-symbol
859 Keep the file's section flags and symbols but remove all section
860 data. Specifically, the option:
861 *<removes the contents of all sections;>
863 *<sets the size of every section to zero; and>
864 *<sets the file's start address to zero.>
865 This option is used to build a .sym file for a VxWorks kernel. It
867 can also be a useful way of reducing the size of a --just-symbols
868 linker input file.
869 --compress-debug-sections
871 Compress DWARF debug sections using zlib with SHF_COMPRESSED from
872 the ELF ABI. Note - if compression would actually make a section
873 larger, then it is not compressed.
874 --compress-debug-sections=none
876 --compress-debug-sections=zlib
877 --compress-debug-sections=zlib-gnu
878 --compress-debug-sections=zlib-gabi
879 --compress-debug-sections=zstd
880 For ELF files, these options control how DWARF debug sections are
881 compressed. --compress-debug-sections=none is equivalent to
882 --decompress-debug-sections. --compress-debug-sections=zlib and
883 --compress-debug-sections=zlib-gabi are equivalent to
884 --compress-debug-sections. --compress-debug-sections=zlib-gnu
885 compresses DWARF debug sections using the obsoleted zlib-gnu
886 format. The debug sections are renamed to begin with .zdebug.
887 --compress-debug-sections=zstd compresses DWARF debug sections
888 using zstd. Note - if compression would actually make a section
889 larger, then it is not compressed nor renamed.
890 --decompress-debug-sections
892 Decompress DWARF debug sections. For a .zdebug section, the
893 original name is restored.
894 --elf-stt-common=yes
896 --elf-stt-common=no
897 For ELF files, these options control whether common symbols should
898 be converted to the "STT_COMMON" or "STT_OBJECT" type.
899 --elf-stt-common=yes converts common symbol type to "STT_COMMON".
900 --elf-stt-common=no converts common symbol type to "STT_OBJECT".
901 --merge-notes
903 --no-merge-notes
904 For ELF files, attempt (or do not attempt) to reduce the size of
905 any SHT_NOTE type sections by removing duplicate notes.
906 -V
908 --version
909 Show the version number of objcopy.
910 --verilog-data-width=bytes
912 For Verilog output, this options controls the number of bytes
913 converted for each output data element. The input target controls
914 the endianness of the conversion.
915 -v
917 --verbose
918 Verbose output: list all object files modified. In the case of
919 archives, objcopy -V lists all members of the archive.
920 --help
922 Show a summary of the options to objcopy.
923 --info
925 Display a list showing all architectures and object formats
926 available.
927 @file
929 Read command-line options from file. The options read are inserted
930 in place of the original @file option. If file does not exist, or
931 cannot be read, then the option will be treated literally, and not
932 removed.
933 Options in file are separated by whitespace. A whitespace
935 character may be included in an option by surrounding the entire
936 option in either single or double quotes. Any character (including
937 a backslash) may be included by prefixing the character to be
938 included with a backslash. The file may itself contain additional
939 @file options; any such options will be processed recursively.
940
942 ld(1), objdump(1), and the Info entries for binutils.
943
945 Copyright (c) 1991-2023 Free Software Foundation, Inc.
946 Permission is granted to copy, distribute and/or modify this document
948 under the terms of the GNU Free Documentation License, Version 1.3 or
949 any later version published by the Free Software Foundation; with no
950 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
951 Texts. A copy of the license is included in the section entitled "GNU
952 Free Documentation License".
953binutils-2.41 2023-08-16 OBJCOPY(1)