Penguin
Recent Changes
Annotated edit history of objcopy(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 OBJCOPY
2 !!!OBJCOPY
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 SEE ALSO
8 COPYRIGHT
9 ----
10 !!NAME
11
12
13 objcopy - copy and translate object files
14 !!SYNOPSIS
15
16
17 objcopy [[__-F__
18 ''bfdname''__--target=__''bfdname''] [[__-I__
19 ''bfdname''__--input-target=__''bfdname'']
20 [[__-O__
21 ''bfdname''__--output-target=__''bfdname'']
22 [[__-B__
23 ''bfdarch''__--binary-architecture=__''bfdarch'']
24 [[__-S--strip-all__] [[__-g--strip-debug__] [[__-K__
25 ''symbolname''__--keep-symbol=__''symbolname'']
26 [[__-N__
27 ''symbolname''__--strip-symbol=__''symbolname'']
28 [[__-G__
29 ''symbolname''__--keep-global-symbol=__''symbolname'']
30 [[__-L__
31 ''symbolname''__--localize-symbol=__''symbolname'']
32 [[__-W__
33 ''symbolname''__--weaken-symbol=__''symbolname'']
34 [[__-x--discard-all__] [[__-X--discard-locals__]
35 [[__-b__ ''byte''__--byte=__''byte''] [[__-i__
36 ''interleave''__--interleave=__''interleave'']
37 [[__-j__
38 ''sectionname''__--only-section=__''sectionname'']
39 [[__-R__
40 ''sectionname''__--remove-section=__''sectionname'']
41 [[__-p--preserve-dates__] [[__--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__
48 ''section''{=,+,-}''val'']
49 [[__--change-section-lma__
50 ''section''{=,+,-}''val'']
51 [[__--change-section-vma__
52 ''section''{=,+,-}''val''] [[__--change-warnings__]
53 [[__--no-change-warnings__] [[__--set-section-flags__
54 ''section''=''flags''] [[__--add-section__
55 ''sectionname''=''filename''] [[__--rename-section__
56 ''oldname''=''newname''[[,''flags'']]
57 [[__--change-leading-char__ ]
58 [[__--remove-leading-char__]
59 [[__--srec-len=__''ival'' ] [[__--srec-forceS3__]
60 [[__--redefine-sym__ ''old''=''new'' ]
61 [[__--weaken__] [[__--keep-symbols=__''filename'']
62 [[__--strip-symbols=__''filename'']
63 [[__--keep-global-symbols=__''filename'']
64 [[__--localize-symbols=__''filename'']
65 [[__--weaken-symbols=__''filename'']
66 [[__--alt-machine-code=__''index'']
67 [[__-v--verbose__] [[__-V--version__] [[__--help__]
68 ''infile'' [[''outfile'']
69 !!DESCRIPTION
70
71
72 The GNU __objcopy__ utility copies the
73 contents of an object file to another. __objcopy__ uses
74 the GNU BFD Library to read and write the
75 object files. It can write the destination object file in a
76 format different from that of the source object file. The
77 exact behavior of __objcopy__ is controlled by
78 command-line options. Note that __objcopy__ should be
79 able to copy a fully linked file between any two formats.
80 However, copying a relocatable object file between any two
81 formats may not work as expected.
82
83
84 __objcopy__ creates temporary files to do its
85 translations and deletes them afterward. __objcopy__ uses
86 BFD to do all its translation work; it has
87 access to all the formats described in BFD
88 and thus is able to recognize most formats without being
89 told explicitly.
90
91
92 __objcopy__ can be used to generate S-records by using an
93 output target of __srec__ (e.g., use __-O
94 srec__).
95
96
97 __objcopy__ can be used to generate a raw binary file by
98 using an output target of __binary__ (e.g., use __-O
99 binary__). When __objcopy__ generates a raw binary
100 file, it will essentially produce a memory dump of the
101 contents of the input object file. All symbols and
102 relocation information will be discarded. The memory dump
103 will start at the load address of the lowest section copied
104 into the output file.
105
106
107 When generating an S-record or a raw binary file, it may be
108 helpful to use __-S__ to remove sections containing
109 debugging information. In some cases __-R__ will be
110 useful to remove sections which contain information that is
111 not needed by the binary file.
112
113
114 Note - __objcopy__ is not able to change the endianness
115 of its input files. If the input format has an endianness,
116 (some formats do not), __objcopy__ can only copy the
117 inputs into file formats that have the same endianness or
118 which have no endianness (eg __srec__).
119 !!OPTIONS
120
121
122 ''infile''
123
124
125 ''outfile''
126
127
128 The input and output files, respectively. If you do not
129 specify ''outfile'', __objcopy__ creates a temporary
130 file and destructively renames the result with the name of
131 ''infile''.
132
133
134 __-I__ ''bfdname''
135
136
137 __--input-target=__''bfdname''
138
139
140 Consider the source file's object format to be
141 ''bfdname'', rather than attempting to deduce
142 it.
143
144
145 __-O__ ''bfdname''
146
147
148 __--output-target=__''bfdname''
149
150
151 Write the output file using the object format
152 ''bfdname''.
153
154
155 __-F__ ''bfdname''
156
157
158 __--target=__''bfdname''
159
160
161 Use ''bfdname'' as the object format for both the input
162 and the output file; i.e., simply transfer data from source
163 to destination with no translation.
164
165
166 __-B__ ''bfdarch''
167
168
169 __--binary-architecture=__''bfdarch''
170
171
172 Useful when transforming a raw binary input file into an
173 object file. In this case the output architecture can be set
174 to ''bfdarch''. This option will be ignored if the input
175 file has a known ''bfdarch''. You can access this binary
176 data inside a program by referencing the special symbols
177 that are created by the conversion process. These symbols
178 are called _binary_''objfile''_start,
179 _binary_''objfile''_end and _binary_''objfile''_size.
180 e.g. you can transform a picture file into an object file
181 and then access it in your code using these
182 symbols.
183
184
185 __-j__ ''sectionname''
186
187
188 __--only-section=__''sectionname''
189
190
191 Copy only the named section from the input file to the
192 output file. This option may be given more than once. Note
193 that using this option inappropriately may make the output
194 file unusable.
195
196
197 __-R__ ''sectionname''
198
199
200 __--remove-section=__''sectionname''
201
202
203 Remove any section named ''sectionname'' from the output
204 file. This option may be given more than once. Note that
205 using this option inappropriately may make the output file
206 unusable.
207
208
209 __-S__
210
211
212 __--strip-all__
213
214
215 Do not copy relocation and symbol information from the
216 source file.
217
218
219 __-g__
220
221
222 __--strip-debug__
223
224
225 Do not copy debugging symbols from the source
226 file.
227
228
229 __--strip-unneeded__
230
231
232 Strip all symbols that are not needed for relocation
233 processing.
234
235
236 __-K__ ''symbolname''
237
238
239 __--keep-symbol=__''symbolname''
240
241
242 Copy only symbol ''symbolname'' from the source file.
243 This option may be given more than once.
244
245
246 __-N__ ''symbolname''
247
248
249 __--strip-symbol=__''symbolname''
250
251
252 Do not copy symbol ''symbolname'' from the source file.
253 This option may be given more than once.
254
255
256 __-G__ ''symbolname''
257
258
259 __--keep-global-symbol=__''symbolname''
260
261
262 Keep only symbol ''symbolname'' global. Make all other
263 symbols local to the file, so that they are not visible
264 externally. This option may be given more than
265 once.
266
267
268 __-L__ ''symbolname''
269
270
271 __--localize-symbol=__''symbolname''
272
273
274 Make symbol ''symbolname'' local to the file, so that it
275 is not visible externally. This option may be given more
276 than once.
277
278
279 __-W__ ''symbolname''
280
281
282 __--weaken-symbol=__''symbolname''
283
284
285 Make symbol ''symbolname'' weak. This option may be given
286 more than once.
287
288
289 __-x__
290
291
292 __--discard-all__
293
294
295 Do not copy non-global symbols from the source
296 file.
297
298
299 __-X__
300
301
302 __--discard-locals__
303
304
305 Do not copy compiler-generated local symbols. (These usually
306 start with __L__ or __.__.)
307
308
309 __-b__ ''byte''
310
311
312 __--byte=__''byte''
313
314
315 Keep only every ''byte''th byte of the input file (header
316 data is not affected). ''byte'' can be in the range from
317 0 to ''interleave''-1, where ''interleave'' is given
318 by the __-i__ or __--interleave__ option, or the
319 default of 4. This option is useful for creating files to
320 program ROM . It is typically used with an
321 srec output target.
322
323
324 __-i__ ''interleave''
325
326
327 __--interleave=__''interleave''
328
329
330 Only copy one out of every ''interleave'' bytes. Select
331 which byte to copy with the __-b__ or __--byte__
332 option. The default is 4. __objcopy__ ignores this option
333 if you do not specify either __-b__ or
334 __--byte__.
335
336
337 __-p__
338
339
340 __--preserve-dates__
341
342
343 Set the access and modification dates of the output file to
344 be the same as those of the input file.
345
346
347 __--debugging__
348
349
350 Convert debugging information, if possible. This is not the
351 default because only certain debugging formats are
352 supported, and the conversion process can be time
353 consuming.
354
355
356 __--gap-fill__ ''val''
357
358
359 Fill gaps between sections with ''val''. This operation
360 applies to the ''load address'' ( LMA ) of
361 the sections. It is done by increasing the size of the
362 section with the lower address, and filling in the extra
363 space created with ''val''.
364
365
366 __--pad-to__ ''address''
367
368
369 Pad the output file up to the load address ''address''.
370 This is done by increasing the size of the last section. The
371 extra space is filled in with the value specified by
372 __--gap-fill__ (default zero).
373
374
375 __--set-start__ ''val''
376
377
378 Set the start address of the new file to ''val''. Not all
379 object file formats support setting the start
380 address.
381
382
383 __--change-start__ ''incr''
384
385
386 __--adjust-start__ ''incr''
387
388
389 Change the start address by adding ''incr''. Not all
390 object file formats support setting the start
391 address.
392
393
394 __--change-addresses__ ''incr''
395
396
397 __--adjust-vma__ ''incr''
398
399
400 Change the VMA and LMA
401 addresses of all sections, as well as the start address, by
402 adding ''incr''. Some object file formats do not permit
403 section addresses to be changed arbitrarily. Note that this
404 does not relocate the sections; if the program expects
405 sections to be loaded at a certain address, and this option
406 is used to change the sections such that they are loaded at
407 a different address, the program may fail.
408
409
410 __--change-section-address__
411 ''section''__{=,+,-}__''val''
412
413
414 __--adjust-section-vma__
415 ''section''__{=,+,-}__''val''
416
417
418 Set or change both the VMA address and the
419 LMA address of the named ''section''. If
420 __=__ is used, the section address is set to ''val''.
421 Otherwise, ''val'' is added to or subtracted from the
422 section address. See the comments under
423 __--change-addresses__, above. If ''section'' does not
424 exist in the input file, a warning will be issued, unless
425 __--no-change-warnings__ is used.
426
427
428 __--change-section-lma__
429 ''section''__{=,+,-}__''val''
430
431
432 Set or change the LMA address of the named
433 ''section''. The LMA address is the
434 address where the section will be loaded into memory at
435 program load time. Normally this is the same as the
436 VMA address, which is the address of the
437 section at program run time, but on some systems, especially
438 those where a program is held in ROM , the
439 two can be different. If __=__ is used, the section
440 address is set to ''val''. Otherwise, ''val'' is added
441 to or subtracted from the section address. See the comments
442 under __--change-addresses__, above. If ''section''
443 does not exist in the input file, a warning will be issued,
444 unless __--no-change-warnings__ is used.
445
446
447 __--change-section-vma__
448 ''section''__{=,+,-}__''val''
449
450
451 Set or change the VMA address of the named
452 ''section''. The VMA address is the
453 address where the section will be located once the program
454 has started executing. Normally this is the same as the
455 LMA address, which is the address where the
456 section will be loaded into memory, but on some systems,
457 especially those where a program is held in
458 ROM , the two can be different. If __=__
459 is used, the section address is set to ''val''.
460 Otherwise, ''val'' is added to or subtracted from the
461 section address. See the comments under
462 __--change-addresses__, above. If ''section'' does not
463 exist in the input file, a warning will be issued, unless
464 __--no-change-warnings__ is used.
465
466
467 __--change-warnings__
468
469
470 __--adjust-warnings__
471
472
473 If __--change-section-address__ or
474 __--change-section-lma__ or __--change-section-vma__
475 is used, and the named section does not exist, issue a
476 warning. This is the default.
477
478
479 __--no-change-warnings__
480
481
482 __--no-adjust-warnings__
483
484
485 Do not issue a warning if __--change-section-address__ or
486 __--adjust-section-lma__ or __--adjust-section-vma__
487 is used, even if the named section does not
488 exist.
489
490
491 __--set-section-flags__
492 ''section''__=__''flags''
493
494
495 Set the flags for the named section. The ''flags''
496 argument is a comma separated string of flag names. The
497 recognized names are __alloc__, __contents__,
498 __load__, __noload__, __readonly__, __code__,
499 __data__, __rom__, __share__, and __debug__. You
500 can set the __contents__ flag for a section which does
501 not have contents, but it is not meaningful to clear the
502 __contents__ flag of a section which does have
503 contents--just remove the section instead. Not all flags are
504 meaningful for all object file formats.
505
506
507 __--add-section__
508 ''sectionname''__=__''filename''
509
510
511 Add a new section named ''sectionname'' while copying the
512 file. The contents of the new section are taken from the
513 file ''filename''. The size of the section will be the
514 size of the file. This option only works on file formats
515 which can support sections with arbitrary
516 names.
517
518
519 __--rename-section__
520 ''oldname''__=__''newname''__[[,__''flags''__]__
521
522
523 Rename a section from ''oldname'' to ''newname'',
524 optionally changing the section's flags to ''flags'' in
525 the process. This has the advantage over usng a linker
526 script to perform the rename in that the output stays as an
527 object file and does not become a linked
528 executable.
529
530
531 This option is particularly helpful when the input format is
532 binary, since this will always create a section called
533 .data. If for example, you wanted instead to create a
534 section called .rodata containing binary data you could use
535 the following command line to achieve it:
536
537
538 objcopy -I binary -O
539
540
541 __--change-leading-char__
542
543
544 Some object file formats use special characters at the start
545 of symbols. The most common such character is underscore,
546 which compilers often add before every symbol. This option
547 tells __objcopy__ to change the leading character of
548 every symbol when it converts between object file formats.
549 If the object file formats use the same leading character,
550 this option has no effect. Otherwise, it will add a
551 character, or remove a character, or change a character, as
552 appropriate.
553
554
555 __--remove-leading-char__
556
557
558 If the first character of a global symbol is a special
559 symbol leading character used by the object file format,
560 remove the character. The most common symbol leading
561 character is underscore. This option will remove a leading
562 underscore from all global symbols. This can be useful if
563 you want to link together objects of different file formats
564 with different conventions for symbol names. This is
565 different from __--change-leading-char__ because it
566 always changes the symbol name when appropriate, regardless
567 of the object file format of the output file.
568
569
570 __--srec-len=__''ival''
571
572
573 Meaningful only for srec output. Set the maximum length of
574 the Srecords being produced to ''ival''. This length
575 covers both address, data and crc fields.
576
577
578 __--srec-forceS3__
579
580
581 Meaningful only for srec output. Avoid generation of S1/S2
582 records, creating S3-only record format.
583
584
585 __--redefine-sym__
586 ''old''__=__''new''
587
588
589 Change the name of a symbol ''old'', to ''new''. This
590 can be useful when one is trying link two things together
591 for which you have no source, and there are name
592 collisions.
593
594
595 __--weaken__
596
597
598 Change all global symbols in the file to be weak. This can
599 be useful when building an object which will be linked
600 against other objects using the __-R__ option to the
601 linker. This option is only effective when using an object
602 file format which supports weak symbols.
603
604
605 __--keep-symbols=__''filename''
606
607
608 Apply __--keep-symbol__ option to each symbol listed in
609 the file ''filename''. ''filename'' is simply a flat
610 file, with one symbol name per line. Line comments may be
611 introduced by the hash character. This option may be given
612 more than once.
613
614
615 __--strip-symbols=__''filename''
616
617
618 Apply __--strip-symbol__ option to each symbol listed in
619 the file ''filename''. ''filename'' is simply a flat
620 file, with one symbol name per line. Line comments may be
621 introduced by the hash character. This option may be given
622 more than once.
623
624
625 __--keep-global-symbols=__''filename''
626
627
628 Apply __--keep-global-symbol__ option to each symbol
629 listed in the file ''filename''. ''filename'' is
630 simply a flat file, with one symbol name per line. Line
631 comments may be introduced by the hash character. This
632 option may be given more than once.
633
634
635 __--localize-symbols=__''filename''
636
637
638 Apply __--localize-symbol__ option to each symbol listed
639 in the file ''filename''. ''filename'' is simply a
640 flat file, with one symbol name per line. Line comments may
641 be introduced by the hash character. This option may be
642 given more than once.
643
644
645 __--weaken-symbols=__''filename''
646
647
648 Apply __--weaken-symbol__ option to each symbol listed in
649 the file ''filename''. ''filename'' is simply a flat
650 file, with one symbol name per line. Line comments may be
651 introduced by the hash character. This option may be given
652 more than once.
653
654
655 __--alt-machine-code=__''index''
656
657
658 If the output architecture has alternate machine codes, use
659 the ''index''th code instead of the default one. This is
660 useful in case a machine is assigned an official code and
661 the tool-chain adopts the new code, but other applications
662 still depend on the original code being used.
663
664
665 __-V__
666
667
668 __--version__
669
670
671 Show the version number of __objcopy__.
672
673
674 __-v__
675
676
677 __--verbose__
678
679
680 Verbose output: list all object files modified. In the case
681 of archives, __objcopy -V__ lists all members of the
682 archive.
683
684
685 __--help__
686
687
688 Show a summary of the options to
689 __objcopy__.
690 !!SEE ALSO
691
692
693 ld(1), objdump(1), and the Info entries for
694 ''binutils''.
695 !!COPYRIGHT
696
697
698 Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
699 2001, 2002 Free Software Foundation, Inc.
700
701
702 Permission is granted to copy, distribute and/or modify this
703 document under the terms of the GNU Free
704 Documentation License, Version 1.1 or any later version
705 published by the Free Software Foundation; with no Invariant
706 Sections, with no Front-Cover Texts, and with no Back-Cover
707 Texts. A copy of the license is included in the section
708 entitled `` GNU Free Documentation
709 License''.
710 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.