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]
               [-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]
               [--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. How-
       ever, 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  for-
       mats without being told explicitly.

       objcopy can be used to generate S-records by using an out-
       put 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 dis-
       carded.  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 debug-
       ging 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 bfd-
           name, 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_obj-
           file_start,   _binary_objfile_end   and   _binary_obj-
           file_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.

       -G symbolname
       --keep-global-symbol=symbolname
           Keep only symbol symbolname global.   Make  all  other
           symbols  local to the file, so that they are not visi-
           ble 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 exclama-
           tion  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 sec-
           tion.  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 relo-
           cate  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 sec-
           tion 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 mem-
           ory, 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.   Other-
           wise,  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  argu-
           ment  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  con-
           tents--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 sec-
           tion 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 lead-
           ing 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 char-
           acter, 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 for-
           mat, 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  con-
           ventions  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 colli-
           sions.

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

       --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  com-
           ments  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 ref-
           erence 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 con-
           junction 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  pro-
           cedure 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, 92, 93, 94, 95, 96, 97, 98, 99,  2000,
       2001, 2002, 2003 Free Software Foundation, Inc.

       Permission  is  granted  to copy, distribute and/or modify
       this document under the terms of the GNU  Free  Documenta-
       tion  License,  Version 1.1 or any later version published
       by the Free Software Foundation; with  no  Invariant  Sec-
       tions,  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-2.14.91            2004-04-09                 OBJCOPY(1)
