binutils: objcopy
1
1 3 objcopy
1 *********
1
1 objcopy [-F BFDNAME|--target=BFDNAME]
1 [-I BFDNAME|--input-target=BFDNAME]
1 [-O BFDNAME|--output-target=BFDNAME]
1 [-B BFDARCH|--binary-architecture=BFDARCH]
1 [-S|--strip-all]
1 [-g|--strip-debug]
1 [--strip-unneeded]
1 [-K SYMBOLNAME|--keep-symbol=SYMBOLNAME]
1 [-N SYMBOLNAME|--strip-symbol=SYMBOLNAME]
1 [--strip-unneeded-symbol=SYMBOLNAME]
1 [-G SYMBOLNAME|--keep-global-symbol=SYMBOLNAME]
1 [--localize-hidden]
1 [-L SYMBOLNAME|--localize-symbol=SYMBOLNAME]
1 [--globalize-symbol=SYMBOLNAME]
1 [-W SYMBOLNAME|--weaken-symbol=SYMBOLNAME]
1 [-w|--wildcard]
1 [-x|--discard-all]
1 [-X|--discard-locals]
1 [-b BYTE|--byte=BYTE]
1 [-i [BREADTH]|--interleave[=BREADTH]]
1 [--interleave-width=WIDTH]
1 [-j SECTIONPATTERN|--only-section=SECTIONPATTERN]
1 [-R SECTIONPATTERN|--remove-section=SECTIONPATTERN]
1 [--remove-relocations=SECTIONPATTERN]
1 [-p|--preserve-dates]
1 [-D|--enable-deterministic-archives]
1 [-U|--disable-deterministic-archives]
1 [--debugging]
1 [--gap-fill=VAL]
1 [--pad-to=ADDRESS]
1 [--set-start=VAL]
1 [--adjust-start=INCR]
1 [--change-addresses=INCR]
1 [--change-section-address SECTIONPATTERN{=,+,-}VAL]
1 [--change-section-lma SECTIONPATTERN{=,+,-}VAL]
1 [--change-section-vma SECTIONPATTERN{=,+,-}VAL]
1 [--change-warnings] [--no-change-warnings]
1 [--set-section-flags SECTIONPATTERN=FLAGS]
1 [--add-section SECTIONNAME=FILENAME]
1 [--dump-section SECTIONNAME=FILENAME]
1 [--update-section SECTIONNAME=FILENAME]
1 [--rename-section OLDNAME=NEWNAME[,FLAGS]]
1 [--long-section-names {enable,disable,keep}]
1 [--change-leading-char] [--remove-leading-char]
1 [--reverse-bytes=NUM]
1 [--srec-len=IVAL] [--srec-forceS3]
1 [--redefine-sym OLD=NEW]
1 [--redefine-syms=FILENAME]
1 [--weaken]
1 [--keep-symbols=FILENAME]
1 [--strip-symbols=FILENAME]
1 [--strip-unneeded-symbols=FILENAME]
1 [--keep-global-symbols=FILENAME]
1 [--localize-symbols=FILENAME]
1 [--globalize-symbols=FILENAME]
1 [--weaken-symbols=FILENAME]
1 [--add-symbol NAME=[SECTION:]VALUE[,FLAGS]
1 [--alt-machine-code=INDEX]
1 [--prefix-symbols=STRING]
1 [--prefix-sections=STRING]
1 [--prefix-alloc-sections=STRING]
1 [--add-gnu-debuglink=PATH-TO-FILE]
1 [--keep-file-symbols]
1 [--only-keep-debug]
1 [--strip-dwo]
1 [--extract-dwo]
1 [--extract-symbol]
1 [--writable-text]
1 [--readonly-text]
1 [--pure]
1 [--impure]
1 [--file-alignment=NUM]
1 [--heap=SIZE]
1 [--image-base=ADDRESS]
1 [--section-alignment=NUM]
1 [--stack=SIZE]
1 [--subsystem=WHICH:MAJOR.MINOR]
1 [--compress-debug-sections]
1 [--decompress-debug-sections]
1 [--elf-stt-common=VAL]
1 [--merge-notes]
1 [--no-merge-notes]
1 [-v|--verbose]
1 [-V|--version]
1 [--help] [--info]
1 INFILE [OUTFILE]
1
1 The GNU 'objcopy' utility copies the contents of an object file to
1 another. 'objcopy' uses the GNU BFD Library to read and write the
1 object files. It can write the destination object file in a format
1 different from that of the source object file. The exact behavior of
1 'objcopy' is controlled by command-line options. Note that 'objcopy'
1 should be able to copy a fully linked file between any two formats.
1 However, copying a relocatable object file between any two formats may
1 not work as expected.
1
1 'objcopy' creates temporary files to do its translations and deletes
1 them afterward. 'objcopy' uses BFD to do all its translation work; it
1 has access to all the formats described in BFD and thus is able to
11 recognize most formats without being told explicitly. ⇒BFD
(ld.info)BFD.
1
1 'objcopy' can be used to generate S-records by using an output target
1 of 'srec' (e.g., use '-O srec').
1
1 'objcopy' can be used to generate a raw binary file by using an
1 output target of 'binary' (e.g., use '-O binary'). When 'objcopy'
1 generates a raw binary file, it will essentially produce a memory dump
1 of the contents of the input object file. All symbols and relocation
1 information will be discarded. The memory dump will start at the load
1 address of the lowest section copied into the output file.
1
1 When generating an S-record or a raw binary file, it may be helpful
1 to use '-S' to remove sections containing debugging information. In
1 some cases '-R' will be useful to remove sections which contain
1 information that is not needed by the binary file.
1
1 Note--'objcopy' is not able to change the endianness of its input
1 files. If the input format has an endianness (some formats do not),
1 'objcopy' can only copy the inputs into file formats that have the same
1 endianness or which have no endianness (e.g., 'srec'). (However, see
1 the '--reverse-bytes' option.)
1
1 'INFILE'
1 'OUTFILE'
1 The input and output files, respectively. If you do not specify
1 OUTFILE, 'objcopy' creates a temporary file and destructively
1 renames the result with the name of INFILE.
1
1 '-I BFDNAME'
1 '--input-target=BFDNAME'
1 Consider the source file's object format to be BFDNAME, rather than
1 attempting to deduce it. ⇒Target Selection, for more
1 information.
1
1 '-O BFDNAME'
1 '--output-target=BFDNAME'
11 Write the output file using the object format BFDNAME. ⇒
Target Selection, for more information.
1
1 '-F BFDNAME'
1 '--target=BFDNAME'
1 Use BFDNAME as the object format for both the input and the output
1 file; i.e., simply transfer data from source to destination with no
1 translation. ⇒Target Selection, for more information.
1
1 '-B BFDARCH'
1 '--binary-architecture=BFDARCH'
1 Useful when transforming a architecture-less input file into an
1 object file. In this case the output architecture can be set to
1 BFDARCH. This option will be ignored if the input file has a known
1 BFDARCH. You can access this binary data inside a program by
1 referencing the special symbols that are created by the conversion
1 process. These symbols are called _binary_OBJFILE_start,
1 _binary_OBJFILE_end and _binary_OBJFILE_size. e.g. you can
1 transform a picture file into an object file and then access it in
1 your code using these symbols.
1
1 '-j SECTIONPATTERN'
1 '--only-section=SECTIONPATTERN'
1 Copy only the indicated sections from the input file to the output
1 file. This option may be given more than once. Note that using
1 this option inappropriately may make the output file unusable.
1 Wildcard characters are accepted in SECTIONPATTERN.
1
1 If the first character of SECTIONPATTERN is the exclamation point
1 (!) then matching sections will not be copied, even if earlier use
1 of '--only-section' on the same command line would otherwise copy
1 it. For example:
1
1 --only-section=.text.* --only-section=!.text.foo
1
1 will copy all sectinos maching '.text.*' but not the section
1 '.text.foo'.
1
1 '-R SECTIONPATTERN'
1 '--remove-section=SECTIONPATTERN'
1 Remove any section matching SECTIONPATTERN from the output file.
1 This option may be given more than once. Note that using this
1 option inappropriately may make the output file unusable. Wildcard
1 characters are accepted in SECTIONPATTERN. Using both the '-j' and
1 '-R' options together results in undefined behaviour.
1
1 If the first character of SECTIONPATTERN is the exclamation point
1 (!) then matching sections will not be removed even if an earlier
1 use of '--remove-section' on the same command line would otherwise
1 remove it. For example:
1
1 --remove-section=.text.* --remove-section=!.text.foo
1
1 will remove all sections matching the pattern '.text.*', but will
1 not remove the section '.text.foo'.
1
1 '--remove-relocations=SECTIONPATTERN'
1 Remove relocations from the output file for any section matching
1 SECTIONPATTERN. This option may be given more than once. Note
1 that using this option inappropriately may make the output file
1 unusable. Wildcard characters are accepted in SECTIONPATTERN. For
1 example:
1
1 --remove-relocations=.text.*
1
1 will remove the relocations for all sections matching the patter
1 '.text.*'.
1
1 If the first character of SECTIONPATTERN is the exclamation point
1 (!) then matching sections will not have their relocation removed
1 even if an earlier use of '--remove-relocations' on the same
1 command line would otherwise cause the relocations to be removed.
1 For example:
1
1 --remove-relocations=.text.* --remove-relocations=!.text.foo
1
1 will remove all relocations for sections matching the pattern
1 '.text.*', but will not remove relocations for the section
1 '.text.foo'.
1
1 '-S'
1 '--strip-all'
1 Do not copy relocation and symbol information from the source file.
1
1 '-g'
1 '--strip-debug'
1 Do not copy debugging symbols or sections from the source file.
1
1 '--strip-unneeded'
1 Strip all symbols that are not needed for relocation processing.
1
1 '-K SYMBOLNAME'
1 '--keep-symbol=SYMBOLNAME'
1 When stripping symbols, keep symbol SYMBOLNAME even if it would
1 normally be stripped. This option may be given more than once.
1
1 '-N SYMBOLNAME'
1 '--strip-symbol=SYMBOLNAME'
1 Do not copy symbol SYMBOLNAME from the source file. This option
1 may be given more than once.
1
1 '--strip-unneeded-symbol=SYMBOLNAME'
1 Do not copy symbol SYMBOLNAME from the source file unless it is
1 needed by a relocation. This option may be given more than once.
1
1 '-G SYMBOLNAME'
1 '--keep-global-symbol=SYMBOLNAME'
1 Keep only symbol SYMBOLNAME global. Make all other symbols local
1 to the file, so that they are not visible externally. This option
1 may be given more than once.
1
1 '--localize-hidden'
1 In an ELF object, mark all symbols that have hidden or internal
1 visibility as local. This option applies on top of symbol-specific
1 localization options such as '-L'.
1
1 '-L SYMBOLNAME'
1 '--localize-symbol=SYMBOLNAME'
1 Convert a global or weak symbol called SYMBOLNAME into a local
1 symbol, so that it is not visible externally. This option may be
1 given more than once. Note - unique symbols are not converted.
1
1 '-W SYMBOLNAME'
1 '--weaken-symbol=SYMBOLNAME'
1 Make symbol SYMBOLNAME weak. This option may be given more than
1 once.
1
1 '--globalize-symbol=SYMBOLNAME'
1 Give symbol SYMBOLNAME global scoping so that it is visible outside
1 of the file in which it is defined. This option may be given more
1 than once.
1
1 '-w'
1 '--wildcard'
1 Permit regular expressions in SYMBOLNAMEs used in other command
1 line options. The question mark (?), asterisk (*), backslash (\)
1 and square brackets ([]) operators can be used anywhere in the
1 symbol name. If the first character of the symbol name is the
1 exclamation point (!) then the sense of the switch is reversed for
1 that symbol. For example:
1
1 -w -W !foo -W fo*
1
1 would cause objcopy to weaken all symbols that start with "fo"
1 except for the symbol "foo".
1
1 '-x'
1 '--discard-all'
1 Do not copy non-global symbols from the source file.
1
1 '-X'
1 '--discard-locals'
1 Do not copy compiler-generated local symbols. (These usually start
1 with 'L' or '.'.)
1
1 '-b BYTE'
1 '--byte=BYTE'
1 If interleaving has been enabled via the '--interleave' option then
1 start the range of bytes to keep at the BYTEth byte. BYTE can be
1 in the range from 0 to BREADTH-1, where BREADTH is the value given
1 by the '--interleave' option.
1
1 '-i [BREADTH]'
1 '--interleave[=BREADTH]'
1 Only copy a range out of every BREADTH bytes. (Header data is not
1 affected). Select which byte in the range begins the copy with the
1 '--byte' option. Select the width of the range with the
1 '--interleave-width' option.
1
1 This option is useful for creating files to program ROM. It is
1 typically used with an 'srec' output target. Note that 'objcopy'
1 will complain if you do not specify the '--byte' option as well.
1
1 The default interleave breadth is 4, so with '--byte' set to 0,
1 'objcopy' would copy the first byte out of every four bytes from
1 the input to the output.
1
1 '--interleave-width=WIDTH'
1 When used with the '--interleave' option, copy WIDTH bytes at a
1 time. The start of the range of bytes to be copied is set by the
1 '--byte' option, and the extent of the range is set with the
1 '--interleave' option.
1
1 The default value for this option is 1. The value of WIDTH plus
1 the BYTE value set by the '--byte' option must not exceed the
1 interleave breadth set by the '--interleave' option.
1
1 This option can be used to create images for two 16-bit flashes
1 interleaved in a 32-bit bus by passing '-b 0 -i 4
1 --interleave-width=2' and '-b 2 -i 4 --interleave-width=2' to two
1 'objcopy' commands. If the input was '12345678' then the outputs
1 would be '1256' and '3478' respectively.
1
1 '-p'
1 '--preserve-dates'
1 Set the access and modification dates of the output file to be the
1 same as those of the input file.
1
1 '-D'
1 '--enable-deterministic-archives'
1 Operate in _deterministic_ mode. When copying archive members and
1 writing the archive index, use zero for UIDs, GIDs, timestamps, and
1 use consistent file modes for all files.
1
1 If 'binutils' was configured with
1 '--enable-deterministic-archives', then this mode is on by default.
1 It can be disabled with the '-U' option, below.
1
1 '-U'
1 '--disable-deterministic-archives'
1 Do _not_ operate in _deterministic_ mode. This is the inverse of
1 the '-D' option, above: when copying archive members and writing
1 the archive index, use their actual UID, GID, timestamp, and file
1 mode values.
1
1 This is the default unless 'binutils' was configured with
1 '--enable-deterministic-archives'.
1
1 '--debugging'
1 Convert debugging information, if possible. This is not the
1 default because only certain debugging formats are supported, and
1 the conversion process can be time consuming.
1
1 '--gap-fill VAL'
1 Fill gaps between sections with VAL. This operation applies to the
1 _load address_ (LMA) of the sections. It is done by increasing the
1 size of the section with the lower address, and filling in the
1 extra space created with VAL.
1
1 '--pad-to ADDRESS'
1 Pad the output file up to the load address ADDRESS. This is done
1 by increasing the size of the last section. The extra space is
1 filled in with the value specified by '--gap-fill' (default zero).
1
1 '--set-start VAL'
1 Set the start address of the new file to VAL. Not all object file
1 formats support setting the start address.
1
1 '--change-start INCR'
1 '--adjust-start INCR'
1 Change the start address by adding INCR. Not all object file
1 formats support setting the start address.
1
1 '--change-addresses INCR'
1 '--adjust-vma INCR'
1 Change the VMA and LMA addresses of all sections, as well as the
1 start address, by adding INCR. Some object file formats do not
1 permit section addresses to be changed arbitrarily. Note that this
1 does not relocate the sections; if the program expects sections to
1 be loaded at a certain address, and this option is used to change
1 the sections such that they are loaded at a different address, the
1 program may fail.
1
1 '--change-section-address SECTIONPATTERN{=,+,-}VAL'
1 '--adjust-section-vma SECTIONPATTERN{=,+,-}VAL'
1 Set or change both the VMA address and the LMA address of any
1 section matching SECTIONPATTERN. If '=' is used, the section
1 address is set to VAL. Otherwise, VAL is added to or subtracted
1 from the section address. See the comments under
1 '--change-addresses', above. If SECTIONPATTERN does not match any
1 sections in the input file, a warning will be issued, unless
1 '--no-change-warnings' is used.
1
1 '--change-section-lma SECTIONPATTERN{=,+,-}VAL'
1 Set or change the LMA address of any sections matching
1 SECTIONPATTERN. The LMA address is the address where the section
1 will be loaded into memory at program load time. Normally this is
1 the same as the VMA address, which is the address of the section at
1 program run time, but on some systems, especially those where a
1 program is held in ROM, the two can be different. If '=' is used,
1 the section address is set to VAL. Otherwise, VAL is added to or
1 subtracted from the section address. See the comments under
1 '--change-addresses', above. If SECTIONPATTERN does not match any
1 sections in the input file, a warning will be issued, unless
1 '--no-change-warnings' is used.
1
1 '--change-section-vma SECTIONPATTERN{=,+,-}VAL'
1 Set or change the VMA address of any section matching
1 SECTIONPATTERN. The VMA address is the address where the section
1 will be located once the program has started executing. Normally
1 this is the same as the LMA address, which is the address where the
1 section will be loaded into memory, but on some systems, especially
1 those where a program is held in ROM, the two can be different. If
1 '=' is used, the section address is set to VAL. Otherwise, VAL is
1 added to or subtracted from the section address. See the comments
1 under '--change-addresses', above. If SECTIONPATTERN does not
1 match any sections in the input file, a warning will be issued,
1 unless '--no-change-warnings' is used.
1
1 '--change-warnings'
1 '--adjust-warnings'
1 If '--change-section-address' or '--change-section-lma' or
1 '--change-section-vma' is used, and the section pattern does not
1 match any sections, issue a warning. This is the default.
1
1 '--no-change-warnings'
1 '--no-adjust-warnings'
1 Do not issue a warning if '--change-section-address' or
1 '--adjust-section-lma' or '--adjust-section-vma' is used, even if
1 the section pattern does not match any sections.
1
1 '--set-section-flags SECTIONPATTERN=FLAGS'
1 Set the flags for any sections matching SECTIONPATTERN. The FLAGS
1 argument is a comma separated string of flag names. The recognized
1 names are 'alloc', 'contents', 'load', 'noload', 'readonly',
1 'code', 'data', 'rom', 'share', and 'debug'. You can set the
1 'contents' flag for a section which does not have contents, but it
1 is not meaningful to clear the 'contents' flag of a section which
1 does have contents-just remove the section instead. Not all flags
1 are meaningful for all object file formats. In particular the
1 'share' flag is only meaningful for COFF format files and not for
1 ELF format files.
1
1 '--add-section SECTIONNAME=FILENAME'
1 Add a new section named SECTIONNAME while copying the file. The
1 contents of the new section are taken from the file FILENAME. The
1 size of the section will be the size of the file. This option only
1 works on file formats which can support sections with arbitrary
1 names. Note - it may be necessary to use the '--set-section-flags'
1 option to set the attributes of the newly created section.
1
1 '--dump-section SECTIONNAME=FILENAME'
1 Place the contents of section named SECTIONNAME into the file
1 FILENAME, overwriting any contents that may have been there
1 previously. This option is the inverse of '--add-section'. This
1 option is similar to the '--only-section' option except that it
1 does not create a formatted file, it just dumps the contents as raw
1 binary data, without applying any relocations. The option can be
1 specified more than once.
1
1 '--update-section SECTIONNAME=FILENAME'
1 Replace the existing contents of a section named SECTIONNAME with
1 the contents of file FILENAME. The size of the section will be
1 adjusted to the size of the file. The section flags for
1 SECTIONNAME will be unchanged. For ELF format files the section to
1 segment mapping will also remain unchanged, something which is not
1 possible using '--remove-section' followed by '--add-section'. The
1 option can be specified more than once.
1
1 Note - it is possible to use '--rename-section' and
1 '--update-section' to both update and rename a section from one
1 command line. In this case, pass the original section name to
1 '--update-section', and the original and new section names to
1 '--rename-section'.
1
1 '--add-symbol NAME=[SECTION:]VALUE[,FLAGS]'
1 Add a new symbol named NAME while copying the file. This option
1 may be specified multiple times. If the SECTION is given, the
1 symbol will be associated with and relative to that section,
1 otherwise it will be an ABS symbol. Specifying an undefined
1 section will result in a fatal error. There is no check for the
1 value, it will be taken as specified. Symbol flags can be
1 specified and not all flags will be meaningful for all object file
1 formats. By default, the symbol will be global. The special flag
1 'before=OTHERSYM' will insert the new symbol in front of the
1 specified OTHERSYM, otherwise the symbol(s) will be added at the
1 end of the symbol table in the order they appear.
1
1 '--rename-section OLDNAME=NEWNAME[,FLAGS]'
1 Rename a section from OLDNAME to NEWNAME, optionally changing the
1 section's flags to FLAGS in the process. This has the advantage
1 over using a linker script to perform the rename in that the output
1 stays as an object file and does not become a linked executable.
1 This option accepts the same set of flags as the
1 '--sect-section-flags' option.
1
1 This option is particularly helpful when the input format is
1 binary, since this will always create a section called .data. If
1 for example, you wanted instead to create a section called .rodata
1 containing binary data you could use the following command line to
1 achieve it:
1
1 objcopy -I binary -O <output_format> -B <architecture> \
1 --rename-section .data=.rodata,alloc,load,readonly,data,contents \
1 <input_binary_file> <output_object_file>
1
1 '--long-section-names {enable,disable,keep}'
1 Controls the handling of long section names when processing 'COFF'
1 and 'PE-COFF' object formats. The default behaviour, 'keep', is to
1 preserve long section names if any are present in the input file.
1 The 'enable' and 'disable' options forcibly enable or disable the
1 use of long section names in the output object; when 'disable' is
1 in effect, any long section names in the input object will be
1 truncated. The 'enable' option will only emit long section names
1 if any are present in the inputs; this is mostly the same as
1 'keep', but it is left undefined whether the 'enable' option might
1 force the creation of an empty string table in the output file.
1
1 '--change-leading-char'
1 Some object file formats use special characters at the start of
1 symbols. The most common such character is underscore, which
1 compilers often add before every symbol. This option tells
1 'objcopy' to change the leading character of every symbol when it
1 converts between object file formats. If the object file formats
1 use the same leading character, this option has no effect.
1 Otherwise, it will add a character, or remove a character, or
1 change a character, as appropriate.
1
1 '--remove-leading-char'
1 If the first character of a global symbol is a special symbol
1 leading character used by the object file format, remove the
1 character. The most common symbol leading character is underscore.
1 This option will remove a leading underscore from all global
1 symbols. This can be useful if you want to link together objects
1 of different file formats with different conventions for symbol
1 names. This is different from '--change-leading-char' because it
1 always changes the symbol name when appropriate, regardless of the
1 object file format of the output file.
1
1 '--reverse-bytes=NUM'
1 Reverse the bytes in a section with output contents. A section
1 length must be evenly divisible by the value given in order for the
1 swap to be able to take place. Reversing takes place before the
1 interleaving is performed.
1
1 This option is used typically in generating ROM images for
1 problematic target systems. For example, on some target boards,
1 the 32-bit words fetched from 8-bit ROMs are re-assembled in
1 little-endian byte order regardless of the CPU byte order.
1 Depending on the programming model, the endianness of the ROM may
1 need to be modified.
1
1 Consider a simple file with a section containing the following
1 eight bytes: '12345678'.
1
1 Using '--reverse-bytes=2' for the above example, the bytes in the
1 output file would be ordered '21436587'.
1
1 Using '--reverse-bytes=4' for the above example, the bytes in the
1 output file would be ordered '43218765'.
1
1 By using '--reverse-bytes=2' for the above example, followed by
1 '--reverse-bytes=4' on the output file, the bytes in the second
1 output file would be ordered '34127856'.
1
1 '--srec-len=IVAL'
1 Meaningful only for srec output. Set the maximum length of the
1 Srecords being produced to IVAL. This length covers both address,
1 data and crc fields.
1
1 '--srec-forceS3'
1 Meaningful only for srec output. Avoid generation of S1/S2
1 records, creating S3-only record format.
1
1 '--redefine-sym OLD=NEW'
1 Change the name of a symbol OLD, to NEW. This can be useful when
1 one is trying link two things together for which you have no
1 source, and there are name collisions.
1
1 '--redefine-syms=FILENAME'
1 Apply '--redefine-sym' to each symbol pair "OLD NEW" listed in the
1 file FILENAME. FILENAME is simply a flat file, with one symbol
1 pair per line. Line comments may be introduced by the hash
1 character. This option may be given more than once.
1
1 '--weaken'
1 Change all global symbols in the file to be weak. This can be
1 useful when building an object which will be linked against other
1 objects using the '-R' option to the linker. This option is only
1 effective when using an object file format which supports weak
1 symbols.
1
1 '--keep-symbols=FILENAME'
1 Apply '--keep-symbol' option to each symbol listed in the file
1 FILENAME. FILENAME is simply a flat file, with one symbol name per
1 line. Line comments may be introduced by the hash character. This
1 option may be given more than once.
1
1 '--strip-symbols=FILENAME'
1 Apply '--strip-symbol' option to each symbol listed in the file
1 FILENAME. FILENAME is simply a flat file, with one symbol name per
1 line. Line comments may be introduced by the hash character. This
1 option may be given more than once.
1
1 '--strip-unneeded-symbols=FILENAME'
1 Apply '--strip-unneeded-symbol' option to each symbol listed in the
1 file FILENAME. FILENAME is simply a flat file, with one symbol
1 name per line. Line comments may be introduced by the hash
1 character. This option may be given more than once.
1
1 '--keep-global-symbols=FILENAME'
1 Apply '--keep-global-symbol' option to each symbol listed in the
1 file FILENAME. FILENAME is simply a flat file, with one symbol
1 name per line. Line comments may be introduced by the hash
1 character. This option may be given more than once.
1
1 '--localize-symbols=FILENAME'
1 Apply '--localize-symbol' option to each symbol listed in the file
1 FILENAME. FILENAME is simply a flat file, with one symbol name per
1 line. Line comments may be introduced by the hash character. This
1 option may be given more than once.
1
1 '--globalize-symbols=FILENAME'
1 Apply '--globalize-symbol' option to each symbol listed in the file
1 FILENAME. FILENAME is simply a flat file, with one symbol name per
1 line. Line comments may be introduced by the hash character. This
1 option may be given more than once.
1
1 '--weaken-symbols=FILENAME'
1 Apply '--weaken-symbol' option to each symbol listed in the file
1 FILENAME. FILENAME is simply a flat file, with one symbol name per
1 line. Line comments may be introduced by the hash character. This
1 option may be given more than once.
1
1 '--alt-machine-code=INDEX'
1 If the output architecture has alternate machine codes, use the
1 INDEXth code instead of the default one. This is useful in case a
1 machine is assigned an official code and the tool-chain adopts the
1 new code, but other applications still depend on the original code
1 being used. For ELF based architectures if the INDEX alternative
1 does not exist then the value is treated as an absolute number to
1 be stored in the e_machine field of the ELF header.
1
1 '--writable-text'
1 Mark the output text as writable. This option isn't meaningful for
1 all object file formats.
1
1 '--readonly-text'
1 Make the output text write protected. This option isn't meaningful
1 for all object file formats.
1
1 '--pure'
1 Mark the output file as demand paged. This option isn't meaningful
1 for all object file formats.
1
1 '--impure'
1 Mark the output file as impure. This option isn't meaningful for
1 all object file formats.
1
1 '--prefix-symbols=STRING'
1 Prefix all symbols in the output file with STRING.
1
1 '--prefix-sections=STRING'
1 Prefix all section names in the output file with STRING.
1
1 '--prefix-alloc-sections=STRING'
1 Prefix all the names of all allocated sections in the output file
1 with STRING.
1
1 '--add-gnu-debuglink=PATH-TO-FILE'
1 Creates a .gnu_debuglink section which contains a reference to
1 PATH-TO-FILE and adds it to the output file. Note: the file at
1 PATH-TO-FILE must exist. Part of the process of adding the
1 .gnu_debuglink section involves embedding a checksum of the
1 contents of the debug info file into the section.
1
1 If the debug info file is built in one location but it is going to
1 be installed at a later time into a different location then do not
1 use the path to the installed location. The '--add-gnu-debuglink'
1 option will fail because the installed file does not exist yet.
1 Instead put the debug info file in the current directory and use
1 the '--add-gnu-debuglink' option without any directory components,
1 like this:
1
1 objcopy --add-gnu-debuglink=foo.debug
1
1 At debug time the debugger will attempt to look for the separate
1 debug info file in a set of known locations. The exact set of
1 these locations varies depending upon the distribution being used,
1 but it typically includes:
1
1 '* The same directory as the executable.'
1
1 '* A sub-directory of the directory containing the executable'
1 called .debug
1
1 '* A global debug directory such as /usr/lib/debug.'
1
1 As long as the debug info file has been installed into one of these
1 locations before the debugger is run everything should work
1 correctly.
1
1 '--keep-file-symbols'
1 When stripping a file, perhaps with '--strip-debug' or
1 '--strip-unneeded', retain any symbols specifying source file
1 names, which would otherwise get stripped.
1
1 '--only-keep-debug'
1 Strip a file, removing contents of any sections that would not be
1 stripped by '--strip-debug' and leaving the debugging sections
1 intact. In ELF files, this preserves all note sections in the
1 output.
1
1 Note - the section headers of the stripped sections are preserved,
1 including their sizes, but the contents of the section are
1 discarded. The section headers are preserved so that other tools
1 can match up the debuginfo file with the real executable, even if
1 that executable has been relocated to a different address space.
1
1 The intention is that this option will be used in conjunction with
1 '--add-gnu-debuglink' to create a two part executable. One a
1 stripped binary which will occupy less space in RAM and in a
1 distribution and the second a debugging information file which is
1 only needed if debugging abilities are required. The suggested
1 procedure to create these files is as follows:
1
1 1. Link the executable as normal. Assuming that is is called
1 'foo' then...
1 2. Run 'objcopy --only-keep-debug foo foo.dbg' to create a file
1 containing the debugging info.
1 3. Run 'objcopy --strip-debug foo' to create a stripped
1 executable.
1 4. Run 'objcopy --add-gnu-debuglink=foo.dbg foo' to add a link to
1 the debugging info into the stripped executable.
1
1 Note--the choice of '.dbg' as an extension for the debug info file
1 is arbitrary. Also the '--only-keep-debug' step is optional. You
1 could instead do this:
1
1 1. Link the executable as normal.
1 2. Copy 'foo' to 'foo.full'
1 3. Run 'objcopy --strip-debug foo'
1 4. Run 'objcopy --add-gnu-debuglink=foo.full foo'
1
1 i.e., the file pointed to by the '--add-gnu-debuglink' can be the
1 full executable. It does not have to be a file created by the
1 '--only-keep-debug' switch.
1
1 Note--this switch is only intended for use on fully linked files.
1 It does not make sense to use it on object files where the
1 debugging information may be incomplete. Besides the gnu_debuglink
1 feature currently only supports the presence of one filename
1 containing debugging information, not multiple filenames on a
1 one-per-object-file basis.
1
1 '--strip-dwo'
1 Remove the contents of all DWARF .dwo sections, leaving the
1 remaining debugging sections and all symbols intact. This option
1 is intended for use by the compiler as part of the '-gsplit-dwarf'
1 option, which splits debug information between the .o file and a
1 separate .dwo file. The compiler generates all debug information
1 in the same file, then uses the '--extract-dwo' option to copy the
1 .dwo sections to the .dwo file, then the '--strip-dwo' option to
1 remove those sections from the original .o file.
1
1 '--extract-dwo'
1 Extract the contents of all DWARF .dwo sections. See the
1 '--strip-dwo' option for more information.
1
1 '--file-alignment NUM'
1 Specify the file alignment. Sections in the file will always begin
1 at file offsets which are multiples of this number. This defaults
1 to 512. [This option is specific to PE targets.]
1
1 '--heap RESERVE'
1 '--heap RESERVE,COMMIT'
1 Specify the number of bytes of memory to reserve (and optionally
1 commit) to be used as heap for this program. [This option is
1 specific to PE targets.]
1
1 '--image-base VALUE'
1 Use VALUE as the base address of your program or dll. This is the
1 lowest memory location that will be used when your program or dll
1 is loaded. To reduce the need to relocate and improve performance
1 of your dlls, each should have a unique base address and not
1 overlap any other dlls. The default is 0x400000 for executables,
1 and 0x10000000 for dlls. [This option is specific to PE targets.]
1
1 '--section-alignment NUM'
1 Sets the section alignment. Sections in memory will always begin
1 at addresses which are a multiple of this number. Defaults to
1 0x1000. [This option is specific to PE targets.]
1
1 '--stack RESERVE'
1 '--stack RESERVE,COMMIT'
1 Specify the number of bytes of memory to reserve (and optionally
1 commit) to be used as stack for this program. [This option is
1 specific to PE targets.]
1
1 '--subsystem WHICH'
1 '--subsystem WHICH:MAJOR'
1 '--subsystem WHICH:MAJOR.MINOR'
1 Specifies the subsystem under which your program will execute. The
1 legal values for WHICH are 'native', 'windows', 'console', 'posix',
1 'efi-app', 'efi-bsd', 'efi-rtd', 'sal-rtd', and 'xbox'. You may
1 optionally set the subsystem version also. Numeric values are also
1 accepted for WHICH. [This option is specific to PE targets.]
1
1 '--extract-symbol'
1 Keep the file's section flags and symbols but remove all section
1 data. Specifically, the option:
1
1 * removes the contents of all sections;
1 * sets the size of every section to zero; and
1 * sets the file's start address to zero.
1
1 This option is used to build a '.sym' file for a VxWorks kernel.
1 It can also be a useful way of reducing the size of a
1 '--just-symbols' linker input file.
1
1 '--compress-debug-sections'
1 Compress DWARF debug sections using zlib with SHF_COMPRESSED from
1 the ELF ABI. Note - if compression would actually make a section
1 _larger_, then it is not compressed.
1
1 '--compress-debug-sections=none'
1 '--compress-debug-sections=zlib'
1 '--compress-debug-sections=zlib-gnu'
1 '--compress-debug-sections=zlib-gabi'
1 For ELF files, these options control how DWARF debug sections are
1 compressed. '--compress-debug-sections=none' is equivalent to
1 '--decompress-debug-sections'. '--compress-debug-sections=zlib'
1 and '--compress-debug-sections=zlib-gabi' are equivalent to
1 '--compress-debug-sections'. '--compress-debug-sections=zlib-gnu'
1 compresses DWARF debug sections using zlib. The debug sections are
1 renamed to begin with '.zdebug' instead of '.debug'. Note - if
1 compression would actually make a section _larger_, then it is not
1 compressed nor renamed.
1
1 '--decompress-debug-sections'
1 Decompress DWARF debug sections using zlib. The original section
1 names of the compressed sections are restored.
1
1 '--elf-stt-common=yes'
1 '--elf-stt-common=no'
1 For ELF files, these options control whether common symbols should
1 be converted to the 'STT_COMMON' or 'STT_OBJECT' type.
1 '--elf-stt-common=yes' converts common symbol type to 'STT_COMMON'.
1 '--elf-stt-common=no' converts common symbol type to 'STT_OBJECT'.
1
1 '--merge-notes'
1 '--no-merge-notes'
1 For ELF files, attempt (or do not attempt) to reduce the size of
1 any SHT_NOTE type sections by removing duplicate notes.
1
1 '-V'
1 '--version'
1 Show the version number of 'objcopy'.
1
1 '-v'
1 '--verbose'
1 Verbose output: list all object files modified. In the case of
1 archives, 'objcopy -V' lists all members of the archive.
1
1 '--help'
1 Show a summary of the options to 'objcopy'.
1
1 '--info'
1 Display a list showing all architectures and object formats
1 available.
1