MirOS Manual: objcopy(1)


OBJCOPY(1)            GNU Development Tools            OBJCOPY(1)

NAME

     objcopy - copy and translate object files

SYNOPSIS

     objcopy [-F bfdname|--target=bfdname]
             [-I bfdname|--input-target=bfdname]
             [-O bfdname|--output-target=bfdname]
             [-B bfdarch|--binary-architecture=bfdarch]
             [-S|--strip-all]
             [-g|--strip-debug]
             [-K symbolname|--keep-symbol=symbolname]
             [-N symbolname|--strip-symbol=symbolname]
             [--strip-unneeded-symbol=symbolname]
             [-G symbolname|--keep-global-symbol=symbolname]
             [-L symbolname|--localize-symbol=symbolname]
             [--globalize-symbol=symbolname]
             [-W symbolname|--weaken-symbol=symbolname]
             [-w|--wildcard]
             [-x|--discard-all]
             [-X|--discard-locals]
             [-b byte|--byte=byte]
             [-i interleave|--interleave=interleave]
             [-j sectionname|--only-section=sectionname]
             [-R sectionname|--remove-section=sectionname]
             [-p|--preserve-dates]
             [--debugging]
             [--gap-fill=val]
             [--pad-to=address]
             [--set-start=val]
             [--adjust-start=incr]
             [--change-addresses=incr]
             [--change-section-address section{=,+,-}val]
             [--change-section-lma section{=,+,-}val]
             [--change-section-vma section{=,+,-}val]
             [--change-warnings] [--no-change-warnings]
             [--set-section-flags section=flags]
             [--add-section sectionname=filename]
             [--rename-section oldname=newname[,flags]]
             [--change-leading-char] [--remove-leading-char]
             [--srec-len=ival] [--srec-forceS3]
             [--redefine-sym old=new]
             [--redefine-syms=filename]
             [--weaken]
             [--keep-symbols=filename]
             [--strip-symbols=filename]
             [--strip-unneeded-symbols=filename]
             [--keep-global-symbols=filename]
             [--localize-symbols=filename]
             [--globalize-symbols=filename]
             [--weaken-symbols=filename]
             [--alt-machine-code=index]
             [--prefix-symbols=string]

binutils-050707            2014-07-04                           1

OBJCOPY(1)            GNU Development Tools            OBJCOPY(1)

             [--prefix-sections=string]
             [--prefix-alloc-sections=string]
             [--add-gnu-debuglink=path-to-file]
             [--only-keep-debug]
             [--writable-text]
             [--readonly-text]
             [--pure]
             [--impure]
             [-v|--verbose]
             [-V|--version]
             [--help] [--info]
             infile [outfile]

DESCRIPTION

     The GNU objcopy utility copies the contents of an object
     file to another.  objcopy uses the GNU BFD Library to read
     and write the object files.  It can write the destination
     object file in a format different from that of the source
     object file.  The exact behavior of objcopy is controlled by
     command-line options. Note that objcopy should be able to
     copy a fully linked file between any two formats. However,
     copying a relocatable object file between any two formats
     may not work as expected.

     objcopy creates temporary files to do its translations and
     deletes them afterward.  objcopy uses BFD to do all its
     translation work; it has access to all the formats described
     in BFD and thus is able to recognize most formats without
     being told explicitly.

     objcopy can be used to generate S-records by using an output
     target of srec (e.g., use -O srec).

     objcopy can be used to generate a raw binary file by using
     an output target of binary (e.g., use -O binary).  When
     objcopy generates a raw binary file, it will essentially
     produce a memory dump of the contents of the input object
     file.  All symbols and relocation information will be
     discarded.  The memory dump will start at the load address
     of the lowest section copied into the output file.

     When generating an S-record or a raw binary file, it may be
     helpful to use -S to remove sections containing debugging
     information.  In some cases -R will be useful to remove
     sections which contain information that is not needed by the
     binary file.

     Note---objcopy is not able to change the endianness of its
     input files.  If the input format has an endianness (some
     formats do not), objcopy can only copy the inputs into file
     formats that have the same endianness or which have no
     endianness (e.g., srec).

binutils-050707            2014-07-04                           2

OBJCOPY(1)            GNU Development Tools            OBJCOPY(1)

OPTIONS

     infile
     outfile
         The input and output files, respectively. If you do not
         specify outfile, objcopy creates a temporary file and
         destructively renames the result with the name of
         infile.

     -I bfdname
     --input-target=bfdname
         Consider the source file's object format to be bfdname,
         rather than attempting to deduce it.

     -O bfdname
     --output-target=bfdname
         Write the output file using the object format bfdname.

     -F bfdname
     --target=bfdname
         Use bfdname as the object format for both the input and
         the output file; i.e., simply transfer data from source
         to destination with no translation.

     -B bfdarch
     --binary-architecture=bfdarch
         Useful when transforming a raw binary input file into an
         object file. In this case the output architecture can be
         set to bfdarch. This option will be ignored if the input
         file has a known bfdarch. You can access this binary
         data inside a program by referencing the special symbols
         that are created by the conversion process.  These
         symbols are called _binary_objfile_start,
         _binary_objfile_end and _binary_objfile_size.  e.g. you
         can transform a picture file into an object file and
         then access it in your code using these symbols.

     -j sectionname
     --only-section=sectionname
         Copy only the named section from the input file to the
         output file. This option may be given more than once.
         Note that using this option inappropriately may make the
         output file unusable.

     -R sectionname
     --remove-section=sectionname
         Remove any section named sectionname from the output
         file.  This option may be given more than once.  Note
         that using this option inappropriately may make the
         output file unusable.

     -S
     --strip-all

binutils-050707            2014-07-04                           3

OBJCOPY(1)            GNU Development Tools            OBJCOPY(1)

         Do not copy relocation and symbol information from the
         source file.

     -g
     --strip-debug
         Do not copy debugging symbols or sections from the
         source file.

     --strip-unneeded
         Strip all symbols that are not needed for relocation
         processing.

     -K symbolname
     --keep-symbol=symbolname
         When stripping symbols, keep symbol symbolname even if
         it would normally be stripped.  This option may be given
         more than once.

     -N symbolname
     --strip-symbol=symbolname
         Do not copy symbol symbolname from the source file.
         This option may be given more than once.

     --strip-unneeded-symbol=symbolname
         Do not copy symbol symbolname from the source file
         unless it is needed by a relocation.  This option may be
         given more than once.

     -G symbolname
     --keep-global-symbol=symbolname
         Keep only symbol symbolname global.  Make all other
         symbols local to the file, so that they are not visible
         externally.  This option may be given more than once.

     -L symbolname
     --localize-symbol=symbolname
         Make symbol symbolname local to the file, so that it is
         not visible externally.  This option may be given more
         than once.

     -W symbolname
     --weaken-symbol=symbolname
         Make symbol symbolname weak. This option may be given
         more than once.

     --globalize-symbol=symbolname
         Give symbol symbolname global scoping so that it is
         visible outside of the file in which it is defined.
         This option may be given more than once.

     -w
     --wildcard

binutils-050707            2014-07-04                           4

OBJCOPY(1)            GNU Development Tools            OBJCOPY(1)

         Permit regular expressions in symbolnames used in other
         command line options.  The question mark (?), asterisk
         (*), backslash (\) and square brackets ([]) operators
         can be used anywhere in the symbol name.  If the first
         character of the symbol name is the exclamation point
         (!) then the sense of the switch is reversed for that
         symbol. For example:

                   -w -W !foo -W fo*

         would cause objcopy to weaken all symbols that start
         with ``fo'' except for the symbol ``foo''.

     -x
     --discard-all
         Do not copy non-global symbols from the source file.

     -X
     --discard-locals
         Do not copy compiler-generated local symbols. (These
         usually start with L or ..)

     -b byte
     --byte=byte
         Keep only every byteth byte of the input file (header
         data is not affected).  byte can be in the range from 0
         to interleave-1, where interleave is given by the -i or
         --interleave option, or the default of 4.  This option
         is useful for creating files to program ROM.  It is
         typically used with an "srec" output target.

     -i interleave
     --interleave=interleave
         Only copy one out of every interleave bytes.  Select
         which byte to copy with the -b or --byte option.  The
         default is 4. objcopy ignores this option if you do not
         specify either -b or --byte.

     -p
     --preserve-dates
         Set the access and modification dates of the output file
         to be the same as those of the input file.

     --debugging
         Convert debugging information, if possible.  This is not
         the default because only certain debugging formats are
         supported, and the conversion process can be time
         consuming.

     --gap-fill val
         Fill gaps between sections with val.  This operation
         applies to the load address (LMA) of the sections.  It

binutils-050707            2014-07-04                           5

OBJCOPY(1)            GNU Development Tools            OBJCOPY(1)

         is done by increasing the size of the section with the
         lower address, and filling in the extra space created
         with val.

     --pad-to address
         Pad the output file up to the load address address.
         This is done by increasing the size of the last section.
         The extra space is filled in with the value specified by
         --gap-fill (default zero).

     --set-start val
         Set the start address of the new file to val.  Not all
         object file formats support setting the start address.

     --change-start incr
     --adjust-start incr
         Change the start address by adding incr.  Not all object
         file formats support setting the start address.

     --change-addresses incr
     --adjust-vma incr
         Change the VMA and LMA addresses of all sections, as
         well as the start address, by adding incr.  Some object
         file formats do not permit section addresses to be
         changed arbitrarily.  Note that this does not relocate
         the sections; if the program expects sections to be
         loaded at a certain address, and this option is used to
         change the sections such that they are loaded at a
         different address, the program may fail.

     --change-section-address section{=,+,-}val
     --adjust-section-vma section{=,+,-}val
         Set or change both the VMA address and the LMA address
         of the named section.  If = is used, the section address
         is set to val.  Otherwise, val is added to or subtracted
         from the section address.  See the comments under
         --change-addresses, above. If section does not exist in
         the input file, a warning will be issued, unless
         --no-change-warnings is used.

     --change-section-lma section{=,+,-}val
         Set or change the LMA address of the named section.  The
         LMA address is the address where the section will be
         loaded into memory at program load time.  Normally this
         is the same as the VMA address, which is the address of
         the section at program run time, but on some systems,
         especially those where a program is held in ROM, the two
         can be different.  If = is used, the section address is
         set to val.  Otherwise, val is added to or subtracted
         from the section address.  See the comments under
         --change-addresses, above.  If section does not exist in
         the input file, a warning will be issued, unless

binutils-050707            2014-07-04                           6

OBJCOPY(1)            GNU Development Tools            OBJCOPY(1)

         --no-change-warnings is used.

     --change-section-vma section{=,+,-}val
         Set or change the VMA address of the named section.  The
         VMA address is the address where the section will be
         located once the program has started executing.
         Normally this is the same as the LMA address, which is
         the address where the section will be loaded into
         memory, but on some systems, especially those where a
         program is held in ROM, the two can be different.  If =
         is used, the section address is set to val.  Otherwise,
         val is added to or subtracted from the section address.
         See the comments under --change-addresses, above.  If
         section does not exist in the input file, a warning will
         be issued, unless --no-change-warnings is used.

     --change-warnings
     --adjust-warnings
         If --change-section-address or --change-section-lma or
         --change-section-vma is used, and the named section does
         not exist, issue a warning.  This is the default.

     --no-change-warnings
     --no-adjust-warnings
         Do not issue a warning if --change-section-address or
         --adjust-section-lma or --adjust-section-vma is used,
         even if the named section does not exist.

     --set-section-flags section=flags
         Set the flags for the named section.  The flags argument
         is a comma separated string of flag names.  The
         recognized names are alloc, contents, load, noload,
         readonly, code, data, rom, share, and debug.  You can
         set the contents flag for a section which does not have
         contents, but it is not meaningful to clear the contents
         flag of a section which does have contents--just remove
         the section instead.  Not all flags are meaningful for
         all object file formats.

     --add-section sectionname=filename
         Add a new section named sectionname while copying the
         file.  The contents of the new section are taken from
         the file filename.  The size of the section will be the
         size of the file.  This option only works on file
         formats which can support sections with arbitrary names.

     --rename-section oldname=newname[,flags]
         Rename a section from oldname to newname, optionally
         changing the section's flags to flags in the process.
         This has the advantage over usng a linker script to
         perform the rename in that the output stays as an object
         file and does not become a linked executable.

binutils-050707            2014-07-04                           7

OBJCOPY(1)            GNU Development Tools            OBJCOPY(1)

         This option is particularly helpful when the input
         format is binary, since this will always create a
         section called .data.  If for example, you wanted
         instead to create a section called .rodata containing
         binary data you could use the following command line to
         achieve it:

                   objcopy -I binary -O <output_format> -B <architecture> \
                    --rename-section .data=.rodata,alloc,load,readonly,data,contents \
                    <input_binary_file> <output_object_file>

     --change-leading-char
         Some object file formats use special characters at the
         start of symbols.  The most common such character is
         underscore, which compilers often add before every
         symbol.  This option tells objcopy to change the leading
         character of every symbol when it converts between
         object file formats.  If the object file formats use the
         same leading character, this option has no effect.
         Otherwise, it will add a character, or remove a
         character, or change a character, as appropriate.

     --remove-leading-char
         If the first character of a global symbol is a special
         symbol leading character used by the object file format,
         remove the character.  The most common symbol leading
         character is underscore.  This option will remove a
         leading underscore from all global symbols.  This can be
         useful if you want to link together objects of different
         file formats with different conventions for symbol
         names.  This is different from --change-leading-char
         because it always changes the symbol name when
         appropriate, regardless of the object file format of the
         output file.

     --srec-len=ival
         Meaningful only for srec output.  Set the maximum length
         of the Srecords being produced to ival.  This length
         covers both address, data and crc fields.

     --srec-forceS3
         Meaningful only for srec output.  Avoid generation of
         S1/S2 records, creating S3-only record format.

     --redefine-sym old=new
         Change the name of a symbol old, to new.  This can be
         useful when one is trying link two things together for
         which you have no source, and there are name collisions.

     --redefine-syms=filename
         Apply --redefine-sym to each symbol pair "old new"
         listed in the file filename.  filename is simply a flat

binutils-050707            2014-07-04                           8

OBJCOPY(1)            GNU Development Tools            OBJCOPY(1)

         file, with one symbol pair per line.  Line comments may
         be introduced by the hash character.  This option may be
         given more than once.

     --weaken
         Change all global symbols in the file to be weak.  This
         can be useful when building an object which will be
         linked against other objects using the -R option to the
         linker.  This option is only effective when using an
         object file format which supports weak symbols.

     --keep-symbols=filename
         Apply --keep-symbol option to each symbol listed in the
         file filename.  filename is simply a flat file, with one
         symbol name per line.  Line comments may be introduced
         by the hash character. This option may be given more
         than once.

     --strip-symbols=filename
         Apply --strip-symbol option to each symbol listed in the
         file filename.  filename is simply a flat file, with one
         symbol name per line.  Line comments may be introduced
         by the hash character. This option may be given more
         than once.

     --strip-unneeded-symbols=filename
         Apply --strip-unneeded-symbol option to each symbol
         listed in the file filename.  filename is simply a flat
         file, with one symbol name per line.  Line comments may
         be introduced by the hash character.  This option may be
         given more than once.

     --keep-global-symbols=filename
         Apply --keep-global-symbol option to each symbol listed
         in the file filename.  filename is simply a flat file,
         with one symbol name per line.  Line comments may be
         introduced by the hash character.  This option may be
         given more than once.

     --localize-symbols=filename
         Apply --localize-symbol option to each symbol listed in
         the file filename.  filename is simply a flat file, with
         one symbol name per line.  Line comments may be
         introduced by the hash character. This option may be
         given more than once.

     --globalize-symbols=filename
         Apply --globalize-symbol option to each symbol listed in
         the file filename.  filename is simply a flat file, with
         one symbol name per line.  Line comments may be
         introduced by the hash character. This option may be
         given more than once.

binutils-050707            2014-07-04                           9

OBJCOPY(1)            GNU Development Tools            OBJCOPY(1)

     --weaken-symbols=filename
         Apply --weaken-symbol option to each symbol listed in
         the file filename.  filename is simply a flat file, with
         one symbol name per line.  Line comments may be
         introduced by the hash character. This option may be
         given more than once.

     --alt-machine-code=index
         If the output architecture has alternate machine codes,
         use the indexth code instead of the default one.  This
         is useful in case a machine is assigned an official code
         and the tool-chain adopts the new code, but other
         applications still depend on the original code being
         used.

     --writable-text
         Mark the output text as writable.  This option isn't
         meaningful for all object file formats.

     --readonly-text
         Make the output text write protected.  This option isn't
         meaningful for all object file formats.

     --pure
         Mark the output file as demand paged.  This option isn't
         meaningful for all object file formats.

     --impure
         Mark the output file as impure.  This option isn't
         meaningful for all object file formats.

     --prefix-symbols=string
         Prefix all symbols in the output file with string.

     --prefix-sections=string
         Prefix all section names in the output file with string.

     --prefix-alloc-sections=string
         Prefix all the names of all allocated sections in the
         output file with string.

     --add-gnu-debuglink=path-to-file
         Creates a .gnu_debuglink section which contains a
         reference to path-to-file and adds it to the output
         file.

     --only-keep-debug
         Strip a file, removing contents of any sections that
         would not be stripped by --strip-debug and leaving the
         debugging sections intact.

         The intention is that this option will be used in

binutils-050707            2014-07-04                          10

OBJCOPY(1)            GNU Development Tools            OBJCOPY(1)

         conjunction with --add-gnu-debuglink to create a two
         part executable.  One a stripped binary which will
         occupy less space in RAM and in a distribution and the
         second a debugging information file which is only needed
         if debugging abilities are required.  The suggested
         procedure to create these files is as follows:

         1.<Link the executable as normal.  Assuming that is is
          called>
             "foo" then...

         1.<Run "objcopy --only-keep-debug foo foo.dbg" to>
             create a file containing the debugging info.

         1.<Run "objcopy --strip-debug foo" to create a>
             stripped executable.

         1.<Run "objcopy --add-gnu-debuglink=foo.dbg foo">
             to add a link to the debugging info into the
             stripped executable.

         Note - the choice of ".dbg" as an extension for the
         debug info file is arbitrary.  Also the
         "--only-keep-debug" step is optional.  You could instead
         do this:

         1.<Link the executable as normal.>
         1.<Copy "foo" to  "foo.full">
         1.<Run "objcopy --strip-debug foo">
         1.<Run "objcopy --add-gnu-debuglink=foo.full foo">

         i.e. the file pointed to by the --add-gnu-debuglink can
         be the full executable.  It does not have to be a file
         created by the --only-keep-debug switch.

     -V
     --version
         Show the version number of objcopy.

     -v
     --verbose
         Verbose output: list all object files modified.  In the
         case of archives, objcopy -V lists all members of the
         archive.

     --help
         Show a summary of the options to objcopy.

     --info
         Display a list showing all architectures and object
         formats available.

binutils-050707            2014-07-04                          11

OBJCOPY(1)            GNU Development Tools            OBJCOPY(1)

SEE ALSO

     ld(1), objdump(1), and the Info entries for binutils.

COPYRIGHT

     Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997,
     1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software
     Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation
     License, Version 1.1 or any later version published by the
     Free Software Foundation; with no Invariant Sections, with
     no Front-Cover Texts, and with no Back-Cover Texts.  A copy
     of the license is included in the section entitled ``GNU
     Free Documentation License''.

binutils-050707            2014-07-04                          12

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.