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, section header table,
program header table, dynamic section, hardware and software
capabilities, 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 example, 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 supply 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 considered 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 character
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 quoting function. Backslash
( is an escape character which operates similarly to the
way it is used in the C programming language within a
string literal:

\a
alert (bell)


\b
backspace


\f
form feed


\n
newline


\r
return


\t
horizontal tab


\v
vertical tab


\
backslash


'
single quote


\"
double quote


\ooo
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 contexts. 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 specified. 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)
command, 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
specified. 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 executing 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 useful 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 commands from the sys module. This mode is primarily to allow
access to the command documentation 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) immediately 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 support 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 damage 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(7).


ATTRIBUTES


See attributes(7) for descriptions of the following attributes:


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

SEE ALSO


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


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, alignments, 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 presence 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.


May 17, 2020 ELFEDIT(1)