Provided by: binutils-h8300-hms_2.16.1-10build1_amd64 bug

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]
               [-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]
               [--weaken-symbols=filename]
               [--alt-machine-code=index]
               [--prefix-symbols=string]
               [--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).

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
           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
           Copy only symbol symbolname from the source file.  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.

       -w
       --wildcard
           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  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
           --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.

           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 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.

       --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  any  sections  that  would be stripped by --strip-debug and
           leaving the debugging sections.

           The intention is that this option will be used in 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">

           ie 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.

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 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''.