Tribblix: manual page: elfedit.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, 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

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 21, 2022 ELFEDIT(1)