👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

OpenSolaris 2009.06 - man page for gobjcopy (opensolaris section 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]
	       [-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. 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.   obj-
       copy  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 pro-
       duce  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 low-
       est 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 sec-
       tions 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 for-
       mat 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 cre-
	   ates 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_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 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 cer-
	   tain debugging formats are supported, and the conversion process can be  time  consum-
	   ing.

       --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 sec-
	   tions 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 sec-
	   tion  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.  Oth-
	   erwise,  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 warn-
	   ing 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  sec-
	   tion  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 exe-
	   cutable.

	   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 con-
	   verts 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 char-
	   acter 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  pro-
	   duced 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.  file-
	   name 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.

       --keep-global-symbols=filename
	   Apply --keep-global-symbol option to each symbol listed in the file	filename.   file-
	   name  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  origi-
	   nal 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 for-
	   mats.

       --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  leav-
	   ing 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, 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 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''.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +--------------------+-----------------+
       |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
       +--------------------+-----------------+
       |Availability	    | SUNWbinutils    |
       +--------------------+-----------------+
       |Interface Stability | External	      |
       +--------------------+-----------------+
NOTES
       Source for GNU binutils is available on http://opensolaris.org.

binutils-2.14.91			    2004-04-09				       OBJCOPY(1)


All times are GMT -4. The time now is 04:28 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?