Windows PowerShell command on Get-command elfedit

Manual Pages for UNIX Operating System command usage for man elfedit

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 capa-

bilities, 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 sym-

bolic 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 cur-

sor.

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 infor-

mation 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.

SunOS 5.11 Last change: 28 Jan 2008 1

User Commands elfedit(1)

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 fol-

lowing 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 com-

mand 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 char-

acters 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 char-

acters do not delimit tokens. Single quote characters are interpreted literally and do not have a quoting function. Backslash ()

is an escape character which operates simi-

larly to the way it is used in the C pro-

gramming language within a string literal: alert (bell) backspace

SunOS 5.11 Last change: 28 Jan 2008 2

User Commands elfedit(1)

form feed 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 shar-

able objects. elfedit loads modules on demand, when a com-

mand that requires it is executed, or as the result of exe-

cuting 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

SunOS 5.11 Last change: 28 Jan 2008 3

User Commands elfedit(1)

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 docu-

mentation 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.

SunOS 5.11 Last change: 28 Jan 2008 4

User Commands elfedit(1)

To obtain summary information for a module: > help module

To obtain the full documentation for a specific command pro-

vided 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 addi-

tion 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.

SunOS 5.11 Last change: 28 Jan 2008 5

User Commands elfedit(1)

%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 develop-

ment 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 com-

mand line option. If you specify both, the -L option super-

sedes 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

SunOS 5.11 Last change: 28 Jan 2008 6

User Commands elfedit(1)

(when stdin and stdout are ter-

minals). Therefore, the -a

option only has meaning when

elfedit is used in non-

interactive contexts. To dis-

able autoprint in an interac-

tive session, use the elfedit

command: > set a off

-d If set, this option causes

elfedit to issue informational

messages describing its inter-

nal 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. Mul-

tiple -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 ses-

sion. It can be changed from

within the elfedit session by

using the set (sys:set) com-

mand, or by providing -o

SunOS 5.11 Last change: 28 Jan 2008 7

User Commands elfedit(1)

options to the individual com-

mands executed within the ses-

sion. default The default style is to display output in a format intended for human viewing.

This style is simi-

lar 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 con-

stants 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 recom-

mended when there is no inten-

tion 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

SunOS 5.11 Last change: 28 Jan 2008 8

User Commands elfedit(1)

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 lim-

ited mode that only allows executing commands from the sys: module. This mode is primarily to

allow access to the command documentation avail-

able 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 examin-

ing 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

SunOS 5.11 Last change: 28 Jan 2008 9

User Commands elfedit(1)

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 documenta-

tion 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 impli-

cit 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 direc-

tory for sharable objects. The following command sets the runpath of that executable to the lib directory:

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

SunOS 5.11 Last change: 28 Jan 2008 10

User Commands elfedit(1)

The use of single quotes with the argument to the -e option

is necessary to ensure that the shell passes the entire com-

mand 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 abil-

ities not available on the system are prevented from run-

ning. 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 capa-

bilities 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.

SunOS 5.11 Last change: 28 Jan 2008 11

User Commands elfedit(1)

The following example removes the AV_386_SSE3 hardware capa-

bility 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.

SunOS 5.11 Last change: 28 Jan 2008 12

User Commands elfedit(1)

LD_NOEXEC_64 Suppresses the automatic execution of the

64-bit elfedit. By default, the 64-bit ver-

sion 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 attri-

butes:

____________________________________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

|_____________________________|_____________________________|

| Availability | developer/object-file |

|_____________________________|_____________________________|

| Interface Stability | Committed |

|_____________________________|_____________________________|

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.

SunOS 5.11 Last change: 28 Jan 2008 13

User Commands elfedit(1)

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 success-

fully carried out on every ELF object. elfedit is con-

strained 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:

SunOS 5.11 Last change: 28 Jan 2008 14

User Commands elfedit(1)

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

Older objects do not have the extra space necessary to com-

plete 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 uncover-

ing 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 manipu-

late 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 Last change: 28 Jan 2008 15