elfedit(1) User Commands elfedit(1)
elfedit - examine or edit ELF files
elfedit [-adr] [-e cmd] [-L path] [-o default | simple | num]
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.
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
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-
fR form feed
' single 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
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
%i Expands to the current instruction set architecture (ISA) name (sparc, sparcv9,
%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:
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
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
-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
-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
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.
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.
The following exit values are returned:
0 Successful completion.
1 A fatal error occurred.
2 Invalid command line options were specified.
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
 RUNPATH 0x3e6 $ORIGIN/../lib
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
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
% TYPE=`elfedit -r -osimple -e 'sym:st_type unlink' /lib/libc.so`
% echo $TYPE
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).
/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
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|Availability |SUNWbtool |
|Interface Stability |Committed |
dump(1), elfdump(1), ld.so.1(1), more(1), nm(1), pvs(1), elf(3ELF), libelf(3LIB),
Linker and Libraries Guide
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
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)