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