1OBJCOPY(1)                   GNU Development Tools                  OBJCOPY(1)
2
3
4

NAME

6       objcopy - copy and translate object files
7

SYNOPSIS

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               [-N symbolname|--strip-symbol=symbolname]
18               [--strip-unneeded-symbol=symbolname]
19               [-G symbolname|--keep-global-symbol=symbolname]
20               [--localize-hidden]
21               [-L symbolname|--localize-symbol=symbolname]
22               [--globalize-symbol=symbolname]
23               [--globalize-symbols=filename]
24               [-W symbolname|--weaken-symbol=symbolname]
25               [-w|--wildcard]
26               [-x|--discard-all]
27               [-X|--discard-locals]
28               [-b byte|--byte=byte]
29               [-i [breadth]|--interleave[=breadth]]
30               [--interleave-width=width]
31               [-j sectionpattern|--only-section=sectionpattern]
32               [-R sectionpattern|--remove-section=sectionpattern]
33               [--remove-relocations=sectionpattern]
34               [-p|--preserve-dates]
35               [-D|--enable-deterministic-archives]
36               [-U|--disable-deterministic-archives]
37               [--debugging]
38               [--gap-fill=val]
39               [--pad-to=address]
40               [--set-start=val]
41               [--adjust-start=incr]
42               [--change-addresses=incr]
43               [--change-section-address sectionpattern{=,+,-}val]
44               [--change-section-lma sectionpattern{=,+,-}val]
45               [--change-section-vma sectionpattern{=,+,-}val]
46               [--change-warnings] [--no-change-warnings]
47               [--set-section-flags sectionpattern=flags]
48               [--add-section sectionname=filename]
49               [--dump-section sectionname=filename]
50               [--update-section sectionname=filename]
51               [--rename-section oldname=newname[,flags]]
52               [--long-section-names {enable,disable,keep}]
53               [--change-leading-char] [--remove-leading-char]
54               [--reverse-bytes=num]
55               [--srec-len=ival] [--srec-forceS3]
56               [--redefine-sym old=new]
57               [--redefine-syms=filename]
58               [--weaken]
59               [--keep-symbols=filename]
60               [--strip-symbols=filename]
61               [--strip-unneeded-symbols=filename]
62               [--keep-global-symbols=filename]
63               [--localize-symbols=filename]
64               [--weaken-symbols=filename]
65               [--add-symbol name=[section:]value[,flags]]
66               [--alt-machine-code=index]
67               [--prefix-symbols=string]
68               [--prefix-sections=string]
69               [--prefix-alloc-sections=string]
70               [--add-gnu-debuglink=path-to-file]
71               [--keep-file-symbols]
72               [--only-keep-debug]
73               [--strip-dwo]
74               [--extract-dwo]
75               [--extract-symbol]
76               [--writable-text]
77               [--readonly-text]
78               [--pure]
79               [--impure]
80               [--file-alignment=num]
81               [--heap=size]
82               [--image-base=address]
83               [--section-alignment=num]
84               [--stack=size]
85               [--subsystem=which:major.minor]
86               [--compress-debug-sections]
87               [--decompress-debug-sections]
88               [--elf-stt-common=val]
89               [--merge-notes]
90               [--no-merge-notes]
91               [-v|--verbose]
92               [-V|--version]
93               [--help] [--info]
94               infile [outfile]
95

DESCRIPTION

97       The GNU objcopy utility copies the contents of an object file to
98       another.  objcopy uses the GNU BFD Library to read and write the object
99       files.  It can write the destination object file in a format different
100       from that of the source object file.  The exact behavior of objcopy is
101       controlled by command-line options.  Note that objcopy should be able
102       to copy a fully linked file between any two formats. However, copying a
103       relocatable object file between any two formats may not work as
104       expected.
105
106       objcopy creates temporary files to do its translations and deletes them
107       afterward.  objcopy uses BFD to do all its translation work; it has
108       access to all the formats described in BFD and thus is able to
109       recognize most formats without being told explicitly.
110
111       objcopy can be used to generate S-records by using an output target of
112       srec (e.g., use -O srec).
113
114       objcopy can be used to generate a raw binary file by using an output
115       target of binary (e.g., use -O binary).  When objcopy generates a raw
116       binary file, it will essentially produce a memory dump of the contents
117       of the input object file.  All symbols and relocation information will
118       be discarded.  The memory dump will start at the load address of the
119       lowest section copied into the output file.
120
121       When generating an S-record or a raw binary file, it may be helpful to
122       use -S to remove sections containing debugging information.  In some
123       cases -R will be useful to remove sections which contain information
124       that is not needed by the binary file.
125
126       Note---objcopy is not able to change the endianness of its input files.
127       If the input format has an endianness (some formats do not), objcopy
128       can only copy the inputs into file formats that have the same
129       endianness or which have no endianness (e.g., srec).  (However, see the
130       --reverse-bytes option.)
131

OPTIONS

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

SEE ALSO

903       ld(1), objdump(1), and the Info entries for binutils.
904
906       Copyright (c) 1991-2019 Free Software Foundation, Inc.
907
908       Permission is granted to copy, distribute and/or modify this document
909       under the terms of the GNU Free Documentation License, Version 1.3 or
910       any later version published by the Free Software Foundation; with no
911       Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
912       Texts.  A copy of the license is included in the section entitled "GNU
913       Free Documentation License".
914
915
916
917binutils-2.31.90                  2019-01-19                        OBJCOPY(1)
Impressum