Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenSolaris 2009.06 - man page for elfedit (opensolaris section 1)

elfedit(1)				  User Commands 			       elfedit(1)

NAME
       elfedit - examine or edit ELF files

SYNOPSIS
       elfedit [-adr] [-e cmd] [-L path] [-o default | simple | num]
	    [infile] [outfile]

DESCRIPTION
       elfedit	is  a  tool  for  examining  or modifying the contents of an existing ELF object.
       Specifically, elfedit is used to modify the ELF metadata contained in the  object.  Access
       is provided to most of the ELF data contained in an object, including the ELF header, sec-
       tion header table, program header table, dynamic section, hardware and software	capabili-
       ties, string tables, and symbol tables.

   Syntax
       elfedit	processes  commands  from the command line (-e option) or from standard input. If
       standard input is a terminal, elfedit provides terminal editing capabilities, as  well  as
       extensive  command  completion.	ELF uses many standard symbolic names for special integer
       values and bit masks. elfedit is aware of most possible completions for	such  names.  You
       can press TAB at any point while entering an elfedit command to cause elfedit to display a
       usage message and any known completions for the text at the current cursor.

       elfedit functionality is organized in the form of modules. Each module delivers a  set  of
       commands, focused on related functionality. A command is specified by combining the module
       and command names with a colon (:) delimiter, with no intervening white space.  For  exam-
       ple,  dyn:runpath  refers  to the runpath command provided by the dyn module. Module names
       must be unique. The command names within a given module are unique within that module, but
       the same command names can be used in more than one module.

       Some  modules  designate  one of their commands to be the default command for that module.
       This command is run when the user specifies only a module name. Most elfedit modules  sup-
       ply  a  command	named  dump, which produces the same information displayed by the elfdump
       utility for the part of the ELF file covered by the module. It is common for a  module  to
       specify dump as its default command.

       The  syntax  used  to  execute an elfedit command is intended to be familiar to anyone who
       uses UNIX command line utilities. It consists of white space delimited tokens.  The  first
       token  is  the  command	name. Options, which are arguments that start with the hyphen (-)
       character follow the command. Plain arguments (operands) follow the options. There can  be
       0  or  more  options  and  operands  for a given command, but if they are present, options
       always precede plain arguments. The special option, --,	(two  hyphens)	can  be  used  to
       delimit	the  end of the options. When it is encountered, any remaining arguments are con-
       sidered to be plain arguments even if they start with a -.

       The interpretation of the characters in an elfedit token depends on the style  of  quoting
       used:

       Unquoted 	Outside of single (') or double (") quotes, backslash ( acts as an escape
			character. When a backslash character is seen, elfedit	ignores  it,  and
			treats	the character following it literally (even if the following char-
			acter is itself a backslash). This feature can be used to insert a  white
			space  character  into	a  string argument to a command without having it
			split the string into two separate tokens. Similarly, it can be  used  to
			insert a quote or backslash as a literal character.

       Single Quotes	Within	single	quotes ('), white space characters do not delimit tokens,
			and are interpreted as literal characters within the token. Double  quote
			(") and backslash ( characters are interpreted as literal characters, and
			have no special meaning.

       Double Quotes	Within double quotes ("), white space characters do not  delimit  tokens.
			Single quote characters are interpreted literally and do not have a quot-
			ing function. Backslash ( is an escape character which operates similarly
			to  the way it is used in the C programming language within a string lit-
			eral:

				alert (bell)

			.
			a	backspace
			d

			fR	form feed

			0fR	newline

				return

				horizontal tab

				vertical tab

			\	backslash

			'	single quote

				double quote

				An octal constant, where ooo is one to three octal digits (0...7)

			Any other character following a backslash is an error.

       The core commands belong to an internal module named sys. All other modules  are  packaged
       as  dynamically loadable sharable objects. elfedit loads modules on demand, when a command
       that requires it is executed, or as the result of executing the sys:load command.  Due  to
       its special built in status, and because its commands are used heavily, elfedit allows you
       to specify commands from the sys module without including the sys:  prefix,  for  example,
       load rather than sys:load. To access a command from any other module, you must specify the
       full module:cmd form.

       elfedit is delivered with the following standard modules:

       cap	  Capabilities Section

       dyn	  Dynamic Section

       ehdr	  ELF Header

       phdr	  Program Header Array

       shdr	  Section Header Array

       str	  String Table Section

       sym	  Symbol Table Section

       syminfo	  Syminfo Section

       sys	  Core built in elfedit commands

   Status And Command Documentation
       Status And Command Documentation

       The status (sys:status) command displays information about the current elfedit session:

	   o	  Input and output files

	   o	  Option setting

	   o	  Module search path

	   o	  Modules loaded

       Included with every elfedit module is extensive online documentation for every command, in
       a format similar to UNIX manual pages. The help (sys:help) command is used to display this
       information. To learn more about elfedit, start elfedit and use the help  command  without
       arguments:

	 % elfedit
	 > help

       elfedit	displays a welcome message with more information about elfedit, and on how to use
       the help system.

       To obtain summary information for a module:

	 > help module

       To obtain the full documentation for a specific command provided by a module:

	 > help module:command

       Using the dyn module and dyn:runpath commands as examples:

	 > help dyn
	 > help dyn:runpath

       help (sys:help) can be used to obtain help on itself:

	 > help help

   Module Search Path
       elfedit modules are implemented as sharable objects which are loaded  on  demand.  When	a
       module  is required, elfedit searches a module path in order to locate the sharable object
       that implements the module. The path is a sequence of directory names delimited	by  colon
       (:)  characters.  In  addition  to normal characters, the path can also contain any of the
       following tokens:

       %i    Expands to the current instruction set  architecture  (ISA)  name	(sparc,  sparcv9,
	     i386, amd64).

       %I    Expands  to  the  64-bit  ISA.  This  is the same thing as %i for 64-bit versions of
	     elfedit, but expands to the empty string for 32-bit versions.

       %o    Expands to the old value of the path being modified. This is useful for appending or
	     prepending directories to the default path.

       %r    Root  of  file  system  tree  holding  the elfedit program, assuming that elfedit is
	     installed as usr/bin/elfedit within the tree. On a standard system, this  is  simply
	     the  standard  system root directory (/). On a development system, where the copy of
	     elfedit can be installed elsewhere, the use of %r can be used  to	ensure	that  the
	     matching set of modules are used.

       %%    Expands to a single % character

       The default module search path for elfedit is:

	 %r/usr/lib/elfedit/%I

       Expanding the tokens, this is:

       /usr/lib/elfedit 	   32-bit elfedit

       /usr/lib/elfedit/sparcv9    64-bit elfedit (sparc)

       /usr/lib/elfedit/amd64	   64-bit elfedit (x86)

       The  default  search path can be changed by setting the ELFEDIT_PATH environment variable,
       or by using the -L command line option. If you specify both, the -L option supersedes  the
       environment variable.

OPTIONS
       The following options are supported:

       -a			    Enable  autoprint  mode.  When  autoprint is enabled, elfedit
				    prints the modified values that result when the ELF  file  is
				    modified.  This  output is shown in the current output style,
				    which can be changed using the -o option. The default  output
				    style  is the style used by the elfdump(1) utility. autoprint
				    mode is the default when elfedit is used interactively  (when
				    stdin  and	stdout	are  terminals). Therefore, the -a option
				    only has meaning when elfedit is used in non-interactive con-
				    texts.  To	disable  autoprint in an interactive session, use
				    the elfedit command:

				      > set a off

       -d			    If set, this option causes	elfedit  to  issue  informational
				    messages  describing  its  internal operations and details of
				    the ELF object being processed. This can  be  useful  when	a
				    deep  understanding  of  the  operation  being carried out is
				    desired.

       -e cmd			    Specifies an edit command. Multiple -e options can be  speci-
				    fied.  If  edit  commands  are  present  on the command line,
				    elfedit operates in  batch	mode.  After  opening  the  file,
				    elfedit executes each command in the order given, after which
				    the modified file is saved and elfedit exits. Batch  mode  is
				    useful  for  performing  simple operations from shell scripts
				    and makefiles.

       -L path			    Sets default path for locating elfedit modules.  Modules  are
				    described in Module Search Path section of this manual page..

       -o default | simple | num    The  style	used to display ELF data. This option establishes
				    the current style for the session. It  can	be  changed  from
				    within  the  elfedit  session by using the set (sys:set) com-
				    mand, or by providing -o options to the  individual  commands
				    executed within the session.

				    default    The default style is to display output in a format
					       intended for human viewing. This style is  similar
					       to that used by the elfdump utility.

				    num        Integer	values	are always shown in integer form.
					       Strings are shown as the integer offset	into  the
					       containing string table.

				    simple     When  displaying strings from within the ELF file,
					       only the string is displayed. Integer  values  are
					       displayed  as  symbolic constants if possible, and
					       in integer form otherwise. No titles, headers,  or
					       other supplemental output is shown.

       -r			    Read-only  mode.  The  input  file	is  opened  for read-only
				    access, and the results of the edit session  are  not  saved.
				    elfedit does not allow the outfile argument when -r is speci-
				    fied. Read-only mode is highly recommended when there  is  no
				    intention  to modify the file. In addition to providing extra
				    protection against accidental modification, it allows for the
				    examination  of  files for which the user does not have write
				    permission.

OPERANDS
       The following operands are supported:

       infile	  Input file containing an ELF object to process.

		  This can be an executable (ET_EXEC), shared  object  (ET_DYN),  or  relocatable
		  object  file,  (ET_REL). Archives are not directly supported. To edit an object
		  in an archive, you must extract the object, edit the copy, and then  insert  it
		  back into the archive.

		  If  no  infile is present, elfedit runs in a limited mode that only allows exe-
		  cuting commands from the sys: module. This mode is primarily to allow access to
		  the command documentation available from the help (sys:help) command.

		  If infile is present, and no outfile is given, elfedit edits the file in place,
		  and writes the results into the same file, causing the original  file  contents
		  to  be  overwritten. It is usually recommended that elfedit not be used in this
		  mode, and that an output file be specified. Once the resulting  file	has  been
		  tested and validated, it can be moved into the place of the original file.

		  The -r option can be used to open infile for read-only access. This can be use-
		  ful for examining an existing file that you do not wish to modify.

       outfile	  Output file. If both infile and outfile are present, infile is opened for read-
		  only access, and the modified object contents are written to outfile.

USAGE
       When  supported by the system, elfedit runs as a 64-bit application, capable of processing
       files greater than or equal to 2 Gbytes (2^31 bytes).

       At startup, elfedit uses libelf to open the input file and cache a copy of its contents in
       memory  for  editing.  It  can  then  execute  one or more commands. A session finishes by
       optionally writing the modified object to the output file, and then exiting.

       If no infile is present, elfedit runs in a limited mode that only  allows  executing  com-
       mands  from the sys module. This mode is primarily to allow access to the command documen-
       tation available from the help (sys:help) command.

       If one or more -e options are specified, the commands they  supply  are	executed  in  the
       order  given. elfedit adds implicit calls to write (sys:write) and quit (sys:quit) immedi-
       ately following the given commands, causing the output file to be written and the  elfedit
       process to exit. This form of use is convenient in shell scripts and makefiles.

       If no -e options are specified, elfedit reads commands from stdin and executes them in the
       order given. The caller must explicitly issue the write (sys:write)  and  quit  (sys:quit)
       commands to save their work and exit when running in this mode.

EXIT STATUS
       The following exit values are returned:

       0    Successful completion.

       1    A fatal error occurred.

       2    Invalid command line options were specified.

EXAMPLES
       In  the	following examples, interactive use of elfedit is shown with the shell prompt (%)
       and the elfedit prompt (>). Neither of these characters should be entered by the user.

       Example 1 Changing the Runpath of an Executable

       The following example presupposes an executable named prog, installed in a  bin	directory
       that  has  an  adjacent lib directory for sharable objects. The following command sets the
       runpath of that executable to the lib directory:

	 elfedit -e 'dyn:runpath $ORIGIN/../lib'

       The use of single quotes with the argument to the -e option is necessary  to  ensure  that
       the shell passes the entire command as a single argument to elfedit.

       Alternatively, the same operation can be done using elfedit in its non-batch mode:

	 % elfedit prog
	 > dyn:runpath $ORIGIN/../lib
	      index  tag	 value
		[30]  RUNPATH	  0x3e6      $ORIGIN/../lib
	 > write
	 > quit

       The  addition  or modification of elements such as runpath or needed entries might only be
       achievable when padding exists within the objects. See Notes.

       Example 2 Removing a Hardware Capability Bit

       Objects that require optional hardware support to run are built with a capability  section
       that  contains  a mask of bits specifying which capabilities they need. The runtime linker
       (ld.so.1) checks this mask against the attributes  of  the  running  system  to	determine
       whether	a  given  object  is  able to be run by the current system. Programs that require
       abilities not available on the system are prevented from running.

       This check prevents a naive program that does not explicitly check for the  hardware  sup-
       port  it requires from crashing in a confusing manner. However, it can be inconvenient for
       a program that is written to explicitly check the system capabilities at runtime.  Such	a
       program	might  have optimized code to use when the hardware supports it while providing a
       generic fallback version that can be run, albeit more slowly, otherwise. In this case, the
       hardware compatibility mask prevents such a program from running on the older hardware. In
       such a case, removing the relevant bit from the mask allows the program to run.

       The following example removes the AV_386_SSE3 hardware capability from an x86 binary  that
       uses  the  SSE3 CPU extension. This transfers responsibility for validating the ability to
       use SSE3 from the runtime linker to the program itself:

	 elfedit -e 'cap:hw1 -and -cmp sse3' prog

       Example 3 Reading Information From an Object

       elfedit can be used to extract specific targeted information from an object. The following
       shell command reads the number of section headers contained in the file /usr/bin/ls:

	 % SHNUM=`elfedit -r -onum -e 'ehdr:e_shnum' /usr/bin/ls`
	 % echo $SHNUM
	 29

       You  might  get a different value, depending on the version of Solaris and type of machine
       that you are using. The -r option causes the file to be opened read-only, allowing a  user
       with  ordinary access permissions to open the file, and protecting against accidental dam-
       age to an important system executable. The num output style is used  in	order  to  obtain
       only the desired value, without any extraneous text.

       Similarly,  the following extracts the symbol type of the symbol unlink from the C runtime
       library:

	 % TYPE=`elfedit -r -osimple -e 'sym:st_type unlink' /lib/libc.so`
	 % echo $TYPE
	 STT_FUNC

ENVIRONMENT VARIABLES
       ELFEDIT_PATH    Alters the default module search path. Module search paths  are	discussed
		       in the Module Search Path section of this manual page.

       LD_NOEXEC_64    Suppresses  the automatic execution of the 64-bit elfedit. By default, the
		       64-bit version of elfedit runs if the system is 64-bit capable.

       PAGER	       Interactively delivers output from elfedit to the screen. If not set, more
		       is used. See more(1).

FILES
       /usr/lib/elfedit    Default  directory  for  elfedit  modules that are loaded on demand to
			   supply editing commands.

       ~/.teclarc	   Personal tecla  customization  file	for  command  line  editing.  See
			   tecla(5).

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWbtool 		   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Committed 		   |
       +-----------------------------+-----------------------------+

SEE ALSO
       dump(1),   elfdump(1),	ld.so.1(1),  more(1),  nm(1),  pvs(1),	elf(3ELF),  libelf(3LIB),
       tecla(5), attributes(5)

       Linker and Libraries Guide

WARNINGS
       elfedit is designed to be a tool for testing and development of the ELF system. It  offers
       the  ability  to  examine  and change nearly every piece of ELF metadata in the object. It
       quietly allows edits that can produce an  invalid  or  unusable	ELF  file.  The  user  is
       expected  to have knowledge of the ELF format and of the rules and conventions that govern
       them. The Linker and Libraries Guide can be helpful when using elfedit.

       elfedit allows the user to alter the ELF metadata in an object, but cannot  understand  or
       alter  the code of the actual program. Setting ELF attributes such as types, sizes, align-
       ments, and so forth in a manner that does not agree with the actual contents of	the  file
       is  therefore  likely  to yield a broken and unusable output object. Such changes might be
       useful for testing of linker components, but should be avoided otherwise.

       Higher level operations, such as the use of the dyn:runpath command to change the  runpath
       of  an  object, are safe, and can be carried out without the sort of risk detailed in this
       section.

NOTES
       Not every ELF operation supported by elfedit can be successfully carried out on every  ELF
       object. elfedit is constrained by the existing sections found in the file.

       One area of particular interest is that elfedit might not be able to modify the runpath of
       a given object. To modify a runpath, the following must be true:

	   o	  The desired string must already exist in the dynamic	string	table,	or  there
		  must	be  enough  reserved  space  within this section for the new string to be
		  added. If your object has a string table reservation area,  the  value  of  the
		  .dynamic  DT_SUNW_STRPAD  element indicates the size of the area. The following
		  elfedit command can be used to check this:

		    % elfedit -r -e 'dyn:tag DT_SUNW_STRPAD' file

	   o	  The dynamic section must already have a runpath element, or there  must  be  an
		  unused  dynamic slot available where one can be inserted. To test for the pres-
		  ence of an existing runpath:

		    % elfedit -r -e 'dyn:runpath' file

		  A dynamic section uses an element of type DT_NULL to terminate the array  found
		  in  that  section.  The  final DT_NULL cannot be changed, but if there are more
		  than one of these, elfedit can convert one of them into a runpath  element.  To
		  test for extra dynamic slots:

		    % elfedit -r -e 'dyn:tag DT_NULL' file

       Older objects do not have the extra space necessary to complete such operations. The space
       necessary to do so was introduced in the Solaris Express Community Edition release.

       When an operation fails, the detailed information printed using the -d (debug) option  can
       be very helpful in uncovering the reason why.

       elfedit	modules follow a convention by which commands that directly manipulate a field in
       an ELF structure have the same name as the field, while	commands  that	implement  higher
       level  concepts	do  not. For instance, the command to manipulate the e_flags field in the
       ELF header is named ehdr:e_flags. Therefore, you generally find the command to modify  ELF
       fields by identifying the module and looking for a command with the name of the field.

SunOS 5.11				   28 Jan 2008				       elfedit(1)


All times are GMT -4. The time now is 05:56 AM.

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