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 [--change-leading-char] [--remove-leading-char]
45 [--srec-len=ival] [--srec-forceS3]
46 [--redefine-sym old=new]
47 [--redefine-syms=filename]
48 [--weaken]
49 [--keep-symbols=filename]
50 [--strip-symbols=filename]
51 [--strip-unneeded-symbols=filename]
52 [--keep-global-symbols=filename]
53 [--localize-symbols=filename]
54 [--globalize-symbols=filename]
55 [--weaken-symbols=filename]
56 [--alt-machine-code=index]
57 [--prefix-symbols=string]
58 [--prefix-sections=string]
59 [--prefix-alloc-sections=string]
60 [--add-gnu-debuglink=path-to-file]
61 [--keep-file-symbols]
62 [--only-keep-debug]
63 [--writable-text]
64 [--readonly-text]
65 [--pure]
66 [--impure]
67 [-v⎪--verbose]
68 [-V⎪--version]
69 [--help] [--info]
70 infile [outfile]
71
73 The GNU objcopy utility copies the contents of an object file to
74 another. objcopy uses the GNU BFD Library to read and write the object
75 files. It can write the destination object file in a format different
76 from that of the source object file. The exact behavior of objcopy is
77 controlled by command-line options. Note that objcopy should be able
78 to copy a fully linked file between any two formats. However, copying a
79 relocatable object file between any two formats may not work as
80 expected.
81 objcopy creates temporary files to do its translations and deletes them
83 afterward. objcopy uses BFD to do all its translation work; it has
84 access to all the formats described in BFD and thus is able to recog‐
85 nize most formats without being told explicitly.
86 objcopy can be used to generate S-records by using an output target of
88 srec (e.g., use -O srec).
89 objcopy can be used to generate a raw binary file by using an output
91 target of binary (e.g., use -O binary). When objcopy generates a raw
92 binary file, it will essentially produce a memory dump of the contents
93 of the input object file. All symbols and relocation information will
94 be discarded. The memory dump will start at the load address of the
95 lowest section copied into the output file.
96 When generating an S-record or a raw binary file, it may be helpful to
98 use -S to remove sections containing debugging information. In some
99 cases -R will be useful to remove sections which contain information
100 that is not needed by the binary file.
101 Note---objcopy is not able to change the endianness of its input files.
103 If the input format has an endianness (some formats do not), objcopy
104 can only copy the inputs into file formats that have the same endian‐
105 ness or which have no endianness (e.g., srec).
106
108 infile
109 outfile
110 The input and output files, respectively. If you do not specify
111 outfile, objcopy creates a temporary file and destructively renames
112 the result with the name of infile.
113 -I bfdname
115 --input-target=bfdname
116 Consider the source file's object format to be bfdname, rather than
117 attempting to deduce it.
118 -O bfdname
120 --output-target=bfdname
121 Write the output file using the object format bfdname.
122 -F bfdname
124 --target=bfdname
125 Use bfdname as the object format for both the input and the output
126 file; i.e., simply transfer data from source to destination with no
127 translation.
128 -B bfdarch
130 --binary-architecture=bfdarch
131 Useful when transforming a raw binary input file into an object
132 file. In this case the output architecture can be set to bfdarch.
133 This option will be ignored if the input file has a known bfdarch.
134 You can access this binary data inside a program by referencing the
135 special symbols that are created by the conversion process. These
136 symbols are called _binary_objfile_start, _binary_objfile_end and
137 _binary_objfile_size. e.g. you can transform a picture file into
138 an object file and then access it in your code using these symbols.
139 -j sectionname
141 --only-section=sectionname
142 Copy only the named section from the input file to the output file.
143 This option may be given more than once. Note that using this
144 option inappropriately may make the output file unusable.
145 -R sectionname
147 --remove-section=sectionname
148 Remove any section named sectionname from the output file. This
149 option may be given more than once. Note that using this option
150 inappropriately may make the output file unusable.
151 -S
153 --strip-all
154 Do not copy relocation and symbol information from the source file.
155 -g
157 --strip-debug
158 Do not copy debugging symbols or sections from the source file.
159 --strip-unneeded
161 Strip all symbols that are not needed for relocation processing.
162 -K symbolname
164 --keep-symbol=symbolname
165 When stripping symbols, keep symbol symbolname even if it would
166 normally be stripped. This option may be given more than once.
167 -N symbolname
169 --strip-symbol=symbolname
170 Do not copy symbol symbolname from the source file. This option
171 may be given more than once.
172 --strip-unneeded-symbol=symbolname
174 Do not copy symbol symbolname from the source file unless it is
175 needed by a relocation. This option may be given more than once.
176 -G symbolname
178 --keep-global-symbol=symbolname
179 Keep only symbol symbolname global. Make all other symbols local
180 to the file, so that they are not visible externally. This option
181 may be given more than once.
182 --localize-hidden
184 In an ELF object, mark all symbols that have hidden or internal
185 visibility as local. This option applies on top of symbol-specific
186 localization options such as -L.
187 -L symbolname
189 --localize-symbol=symbolname
190 Make symbol symbolname local to the file, so that it is not visible
191 externally. This option may be given more than once.
192 -W symbolname
194 --weaken-symbol=symbolname
195 Make symbol symbolname weak. This option may be given more than
196 once.
197 --globalize-symbol=symbolname
199 Give symbol symbolname global scoping so that it is visible outside
200 of the file in which it is defined. This option may be given more
201 than once.
202 -w
204 --wildcard
205 Permit regular expressions in symbolnames used in other command
206 line options. The question mark (?), asterisk (*), backslash (\)
207 and square brackets ([]) operators can be used anywhere in the sym‐
208 bol name. If the first character of the symbol name is the excla‐
209 mation point (!) then the sense of the switch is reversed for that
210 symbol. For example:
211 -w -W !foo -W fo*
213 would cause objcopy to weaken all symbols that start with "fo"
215 except for the symbol "foo".
216 -x
218 --discard-all
219 Do not copy non-global symbols from the source file.
220 -X
222 --discard-locals
223 Do not copy compiler-generated local symbols. (These usually start
224 with L or ..)
225 -b byte
227 --byte=byte
228 Keep only every byteth byte of the input file (header data is not
229 affected). byte can be in the range from 0 to interleave-1, where
230 interleave is given by the -i or --interleave option, or the
231 default of 4. This option is useful for creating files to program
232 ROM. It is typically used with an "srec" output target.
233 -i interleave
235 --interleave=interleave
236 Only copy one out of every interleave bytes. Select which byte to
237 copy with the -b or --byte option. The default is 4. objcopy
238 ignores this option if you do not specify either -b or --byte.
239 -p
241 --preserve-dates
242 Set the access and modification dates of the output file to be the
243 same as those of the input file.
244 --debugging
246 Convert debugging information, if possible. This is not the
247 default because only certain debugging formats are supported, and
248 the conversion process can be time consuming.
249 --gap-fill val
251 Fill gaps between sections with val. This operation applies to the
252 load address (LMA) of the sections. It is done by increasing the
253 size of the section with the lower address, and filling in the
254 extra space created with val.
255 --pad-to address
257 Pad the output file up to the load address address. This is done
258 by increasing the size of the last section. The extra space is
259 filled in with the value specified by --gap-fill (default zero).
260 --set-start val
262 Set the start address of the new file to val. Not all object file
263 formats support setting the start address.
264 --change-start incr
266 --adjust-start incr
267 Change the start address by adding incr. Not all object file for‐
268 mats support setting the start address.
269 --change-addresses incr
271 --adjust-vma incr
272 Change the VMA and LMA addresses of all sections, as well as the
273 start address, by adding incr. Some object file formats do not
274 permit section addresses to be changed arbitrarily. Note that this
275 does not relocate the sections; if the program expects sections to
276 be loaded at a certain address, and this option is used to change
277 the sections such that they are loaded at a different address, the
278 program may fail.
279 --change-section-address section{=,+,-}val
281 --adjust-section-vma section{=,+,-}val
282 Set or change both the VMA address and the LMA address of the named
283 section. If = is used, the section address is set to val. Other‐
284 wise, val is added to or subtracted from the section address. See
285 the comments under --change-addresses, above. If section does not
286 exist in the input file, a warning will be issued, unless
287 --no-change-warnings is used.
288 --change-section-lma section{=,+,-}val
290 Set or change the LMA address of the named section. The LMA
291 address is the address where the section will be loaded into memory
292 at program load time. Normally this is the same as the VMA
293 address, which is the address of the section at program run time,
294 but on some systems, especially those where a program is held in
295 ROM, the two can be different. If = is used, the section address
296 is set to val. Otherwise, val is added to or subtracted from the
297 section address. See the comments under --change-addresses, above.
298 If section does not exist in the input file, a warning will be
299 issued, unless --no-change-warnings is used.
300 --change-section-vma section{=,+,-}val
302 Set or change the VMA address of the named section. The VMA
303 address is the address where the section will be located once the
304 program has started executing. Normally this is the same as the
305 LMA address, which is the address where the section will be loaded
306 into memory, but on some systems, especially those where a program
307 is held in ROM, the two can be different. If = is used, the sec‐
308 tion address is set to val. Otherwise, val is added to or sub‐
309 tracted from the section address. See the comments under
310 --change-addresses, above. If section does not exist in the input
311 file, a warning will be issued, unless --no-change-warnings is
312 used.
313 --change-warnings
315 --adjust-warnings
316 If --change-section-address or --change-section-lma or
317 --change-section-vma is used, and the named section does not exist,
318 issue a warning. This is the default.
319 --no-change-warnings
321 --no-adjust-warnings
322 Do not issue a warning if --change-section-address or --adjust-sec‐
323 tion-lma or --adjust-section-vma is used, even if the named section
324 does not exist.
325 --set-section-flags section=flags
327 Set the flags for the named section. The flags argument is a comma
328 separated string of flag names. The recognized names are alloc,
329 contents, load, noload, readonly, code, data, rom, share, and
330 debug. You can set the contents flag for a section which does not
331 have contents, but it is not meaningful to clear the contents flag
332 of a section which does have contents--just remove the section
333 instead. Not all flags are meaningful for all object file formats.
334 --add-section sectionname=filename
336 Add a new section named sectionname while copying the file. The
337 contents of the new section are taken from the file filename. The
338 size of the section will be the size of the file. This option only
339 works on file formats which can support sections with arbitrary
340 names.
341 --rename-section oldname=newname[,flags]
343 Rename a section from oldname to newname, optionally changing the
344 section's flags to flags in the process. This has the advantage
345 over usng a linker script to perform the rename in that the output
346 stays as an object file and does not become a linked executable.
347 This option is particularly helpful when the input format is
349 binary, since this will always create a section called .data. If
350 for example, you wanted instead to create a section called .rodata
351 containing binary data you could use the following command line to
352 achieve it:
353 objcopy -I binary -O <output_format> -B <architecture> \
355 --rename-section .data=.rodata,alloc,load,readonly,data,contents \
356 <input_binary_file> <output_object_file>
357 --change-leading-char
359 Some object file formats use special characters at the start of
360 symbols. The most common such character is underscore, which com‐
361 pilers often add before every symbol. This option tells objcopy to
362 change the leading character of every symbol when it converts
363 between object file formats. If the object file formats use the
364 same leading character, this option has no effect. Otherwise, it
365 will add a character, or remove a character, or change a character,
366 as appropriate.
367 --remove-leading-char
369 If the first character of a global symbol is a special symbol lead‐
370 ing character used by the object file format, remove the character.
371 The most common symbol leading character is underscore. This
372 option will remove a leading underscore from all global symbols.
373 This can be useful if you want to link together objects of differ‐
374 ent file formats with different conventions for symbol names. This
375 is different from --change-leading-char because it always changes
376 the symbol name when appropriate, regardless of the object file
377 format of the output file.
378 --srec-len=ival
380 Meaningful only for srec output. Set the maximum length of the
381 Srecords being produced to ival. This length covers both address,
382 data and crc fields.
383 --srec-forceS3
385 Meaningful only for srec output. Avoid generation of S1/S2
386 records, creating S3-only record format.
387 --redefine-sym old=new
389 Change the name of a symbol old, to new. This can be useful when
390 one is trying link two things together for which you have no
391 source, and there are name collisions.
392 --redefine-syms=filename
394 Apply --redefine-sym to each symbol pair "old new" listed in the
395 file filename. filename is simply a flat file, with one symbol
396 pair per line. Line comments may be introduced by the hash charac‐
397 ter. This option may be given more than once.
398 --weaken
400 Change all global symbols in the file to be weak. This can be use‐
401 ful when building an object which will be linked against other
402 objects using the -R option to the linker. This option is only
403 effective when using an object file format which supports weak sym‐
404 bols.
405 --keep-symbols=filename
407 Apply --keep-symbol option to each symbol listed in the file file‐
408 name. filename is simply a flat file, with one symbol name per
409 line. Line comments may be introduced by the hash character. This
410 option may be given more than once.
411 --strip-symbols=filename
413 Apply --strip-symbol option to each symbol listed in the file file‐
414 name. filename is simply a flat file, with one symbol name per
415 line. Line comments may be introduced by the hash character. This
416 option may be given more than once.
417 --strip-unneeded-symbols=filename
419 Apply --strip-unneeded-symbol option to each symbol listed in the
420 file filename. filename is simply a flat file, with one symbol
421 name per line. Line comments may be introduced by the hash charac‐
422 ter. This option may be given more than once.
423 --keep-global-symbols=filename
425 Apply --keep-global-symbol option to each symbol listed in the file
426 filename. filename is simply a flat file, with one symbol name per
427 line. Line comments may be introduced by the hash character. This
428 option may be given more than once.
429 --localize-symbols=filename
431 Apply --localize-symbol option to each symbol listed in the file
432 filename. filename is simply a flat file, with one symbol name per
433 line. Line comments may be introduced by the hash character. This
434 option may be given more than once.
435 --globalize-symbols=filename
437 Apply --globalize-symbol option to each symbol listed in the file
438 filename. filename is simply a flat file, with one symbol name per
439 line. Line comments may be introduced by the hash character. This
440 option may be given more than once.
441 --weaken-symbols=filename
443 Apply --weaken-symbol option to each symbol listed in the file
444 filename. filename is simply a flat file, with one symbol name per
445 line. Line comments may be introduced by the hash character. This
446 option may be given more than once.
447 --alt-machine-code=index
449 If the output architecture has alternate machine codes, use the
450 indexth code instead of the default one. This is useful in case a
451 machine is assigned an official code and the tool-chain adopts the
452 new code, but other applications still depend on the original code
453 being used. For ELF based architectures if the index alternative
454 does not exist then the value is treated as an absolute number to
455 be stored in the e_machine field of the ELF header.
456 --writable-text
458 Mark the output text as writable. This option isn't meaningful for
459 all object file formats.
460 --readonly-text
462 Make the output text write protected. This option isn't meaningful
463 for all object file formats.
464 --pure
466 Mark the output file as demand paged. This option isn't meaningful
467 for all object file formats.
468 --impure
470 Mark the output file as impure. This option isn't meaningful for
471 all object file formats.
472 --prefix-symbols=string
474 Prefix all symbols in the output file with string.
475 --prefix-sections=string
477 Prefix all section names in the output file with string.
478 --prefix-alloc-sections=string
480 Prefix all the names of all allocated sections in the output file
481 with string.
482 --add-gnu-debuglink=path-to-file
484 Creates a .gnu_debuglink section which contains a reference to
485 path-to-file and adds it to the output file.
486 --keep-file-symbols
488 When stripping a file, perhaps with --strip-debug or
489 --strip-unneeded, retain any symbols specifying source file names,
490 which would otherwise get stripped.
491 --only-keep-debug
493 Strip a file, removing contents of any sections that would not be
494 stripped by --strip-debug and leaving the debugging sections
495 intact.
496 The intention is that this option will be used in conjunction with
498 --add-gnu-debuglink to create a two part executable. One a
499 stripped binary which will occupy less space in RAM and in a dis‐
500 tribution and the second a debugging information file which is only
501 needed if debugging abilities are required. The suggested proce‐
502 dure to create these files is as follows:
503 1.<Link the executable as normal. Assuming that is is called>
505 "foo" then...
506 1.<Run "objcopy --only-keep-debug foo foo.dbg" to>
508 create a file containing the debugging info.
509 1.<Run "objcopy --strip-debug foo" to create a>
511 stripped executable.
512 1.<Run "objcopy --add-gnu-debuglink=foo.dbg foo">
514 to add a link to the debugging info into the stripped exe‐
515 cutable.
516 Note - the choice of ".dbg" as an extension for the debug info file
518 is arbitrary. Also the "--only-keep-debug" step is optional. You
519 could instead do this:
520 1.<Link the executable as normal.>
522 1.<Copy "foo" to "foo.full">
523 1.<Run "objcopy --strip-debug foo">
524 1.<Run "objcopy --add-gnu-debuglink=foo.full foo">
525 i.e., the file pointed to by the --add-gnu-debuglink can be the
527 full executable. It does not have to be a file created by the
528 --only-keep-debug switch.
529 Note - this switch is only intended for use on fully linked files.
531 It does not make sense to use it on object files where the debug‐
532 ging information may be incomplete. Besides the gnu_debuglink fea‐
533 ture currently only supports the presence of one filename contain‐
534 ing debugging information, not multiple filenames on a one-per-
535 object-file basis.
536 -V
538 --version
539 Show the version number of objcopy.
540 -v
542 --verbose
543 Verbose output: list all object files modified. In the case of ar‐
544 chives, objcopy -V lists all members of the archive.
545 --help
547 Show a summary of the options to objcopy.
548 --info
550 Display a list showing all architectures and object formats avail‐
551 able.
552 @file
554 Read command-line options from file. The options read are inserted
555 in place of the original @file option. If file does not exist, or
556 cannot be read, then the option will be treated literally, and not
557 removed.
558 Options in file are separated by whitespace. A whitespace charac‐
560 ter may be included in an option by surrounding the entire option
561 in either single or double quotes. Any character (including a
562 backslash) may be included by prefixing the character to be
563 included with a backslash. The file may itself contain additional
564 @file options; any such options will be processed recursively.
565
567 ld(1), objdump(1), and the Info entries for binutils.
568
570 Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
571 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
572 Permission is granted to copy, distribute and/or modify this document
574 under the terms of the GNU Free Documentation License, Version 1.1 or
575 any later version published by the Free Software Foundation; with no
576 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
577 Texts. A copy of the license is included in the section entitled "GNU
578 Free Documentation License".
579binutils-2.17.50.0.12-4 2007-04-14 OBJCOPY(1)