1elfedit(1) User Commands elfedit(1)
2
6 elfedit - examine or edit ELF files
7
9 elfedit [-adr] [-e cmd] [-L path] [-o default | simple | num]
10 [infile] [outfile]
11
14 elfedit is a tool for examining or modifying the contents of an exist‐
15 ing ELF object. Specifically, elfedit is used to modify the ELF meta‐
16 data contained in the object. Access is provided to most of the ELF
17 data contained in an object, including the ELF header, section header
18 table, program header table, dynamic section, hardware and software
19 capabilities, string tables, and symbol tables.
20 Syntax
22 elfedit processes commands from the command line (-e option) or from
23 standard input. If standard input is a terminal, elfedit provides ter‐
24 minal editing capabilities, as well as extensive command completion.
25 ELF uses many standard symbolic names for special integer values and
26 bit masks. elfedit is aware of most possible completions for such
27 names. You can press TAB at any point while entering an elfedit command
28 to cause elfedit to display a usage message and any known completions
29 for the text at the current cursor.
30 elfedit functionality is organized in the form of modules. Each module
33 delivers a set of commands, focused on related functionality. A command
34 is specified by combining the module and command names with a colon (:)
35 delimiter, with no intervening white space. For example, dyn:runpath
36 refers to the runpath command provided by the dyn module. Module names
37 must be unique. The command names within a given module are unique
38 within that module, but the same command names can be used in more than
39 one module.
40 Some modules designate one of their commands to be the default command
43 for that module. This command is run when the user specifies only a
44 module name. Most elfedit modules supply a command named dump, which
45 produces the same information displayed by the elfdump utility for the
46 part of the ELF file covered by the module. It is common for a module
47 to specify dump as its default command.
48 The syntax used to execute an elfedit command is intended to be famil‐
51 iar to anyone who uses UNIX command line utilities. It consists of
52 white space delimited tokens. The first token is the command name.
53 Options, which are arguments that start with the hyphen (-) character
54 follow the command. Plain arguments (operands) follow the options.
55 There can be 0 or more options and operands for a given command, but if
56 they are present, options always precede plain arguments. The special
57 option, --, (two hyphens) can be used to delimit the end of the
58 options. When it is encountered, any remaining arguments are considered
59 to be plain arguments even if they start with a -.
60 The interpretation of the characters in an elfedit token depends on the
63 style of quoting used:
64 Unquoted Outside of single (') or double (") quotes, backslash
66 ( acts as an escape character. When a backslash char‐
67 acter is seen, elfedit ignores it, and treats the
68 character following it literally (even if the follow‐
69 ing character is itself a backslash). This feature can
70 be used to insert a white space character into a
71 string argument to a command without having it split
72 the string into two separate tokens. Similarly, it can
73 be used to insert a quote or backslash as a literal
74 character.
75 Single Quotes Within single quotes ('), white space characters do
78 not delimit tokens, and are interpreted as literal
79 characters within the token. Double quote (") and
80 backslash ( characters are interpreted as literal
81 characters, and have no special meaning.
82 Double Quotes Within double quotes ("), white space characters do
85 not delimit tokens. Single quote characters are inter‐
86 preted literally and do not have a quoting function.
87 Backslash ( is an escape character which operates sim‐
88 ilarly to the way it is used in the C programming lan‐
89 guage within a string literal:
90 alert (bell)
92 .
94 a backspace
95 d
96 fR form feed
98 0fR newline
101 return
104 horizontal tab
107 vertical tab
110 \ backslash
113 ´ single quote
116 double quote
119 An octal constant, where ooo is one to three
122 octal digits (0...7)
123 Any other character following a backslash is an error.
125 The core commands belong to an internal module named sys. All other
129 modules are packaged as dynamically loadable sharable objects. elfedit
130 loads modules on demand, when a command that requires it is executed,
131 or as the result of executing the sys:load command. Due to its special
132 built in status, and because its commands are used heavily, elfedit
133 allows you to specify commands from the sys module without including
134 the sys: prefix, for example, load rather than sys:load. To access a
135 command from any other module, you must specify the full module:cmd
136 form.
137 elfedit is delivered with the following standard modules:
140 cap Capabilities Section
142 dyn Dynamic Section
145 ehdr ELF Header
148 phdr Program Header Array
151 shdr Section Header Array
154 str String Table Section
157 sym Symbol Table Section
160 syminfo Syminfo Section
163 sys Core built in elfedit commands
166 Status And Command Documentation
169 Status And Command Documentation
170 The status (sys:status) command displays information about the current
173 elfedit session:
174 o Input and output files
176 o Option setting
178 o Module search path
180 o Modules loaded
182 Included with every elfedit module is extensive online documentation
185 for every command, in a format similar to UNIX manual pages. The help
186 (sys:help) command is used to display this information. To learn more
187 about elfedit, start elfedit and use the help command without argu‐
188 ments:
189 % elfedit
191 > help
192 elfedit displays a welcome message with more information about elfedit,
197 and on how to use the help system.
198 To obtain summary information for a module:
201 > help module
203 To obtain the full documentation for a specific command provided by a
208 module:
209 > help module:command
211 Using the dyn module and dyn:runpath commands as examples:
216 > help dyn
218 > help dyn:runpath
219 help (sys:help) can be used to obtain help on itself:
224 > help help
226 Module Search Path
230 elfedit modules are implemented as sharable objects which are loaded on
231 demand. When a module is required, elfedit searches a module path in
232 order to locate the sharable object that implements the module. The
233 path is a sequence of directory names delimited by colon (:) charac‐
234 ters. In addition to normal characters, the path can also contain any
235 of the following tokens:
236 %i Expands to the current instruction set architecture (ISA) name
238 (sparc, sparcv9, i386, amd64).
239 %I Expands to the 64-bit ISA. This is the same thing as %i for
242 64-bit versions of elfedit, but expands to the empty string for
243 32-bit versions.
244 %o Expands to the old value of the path being modified. This is use‐
247 ful for appending or prepending directories to the default path.
248 %r Root of file system tree holding the elfedit program, assuming
251 that elfedit is installed as usr/bin/elfedit within the tree. On
252 a standard system, this is simply the standard system root direc‐
253 tory (/). On a development system, where the copy of elfedit can
254 be installed elsewhere, the use of %r can be used to ensure that
255 the matching set of modules are used.
256 %% Expands to a single % character
259 The default module search path for elfedit is:
263 %r/usr/lib/elfedit/%I
265 Expanding the tokens, this is:
270 /usr/lib/elfedit 32-bit elfedit
272 /usr/lib/elfedit/sparcv9 64-bit elfedit (sparc)
275 /usr/lib/elfedit/amd64 64-bit elfedit (x86)
278 The default search path can be changed by setting the ELFEDIT_PATH
282 environment variable, or by using the -L command line option. If you
283 specify both, the -L option supersedes the environment variable.
284
286 The following options are supported:
287 -a Enable autoprint mode. When autoprint is
289 enabled, elfedit prints the modified val‐
290 ues that result when the ELF file is modi‐
291 fied. This output is shown in the current
292 output style, which can be changed using
293 the -o option. The default output style is
294 the style used by the elfdump(1) utility.
295 autoprint mode is the default when elfedit
296 is used interactively (when stdin and std‐
297 out are terminals). Therefore, the -a
298 option only has meaning when elfedit is
299 used in non-interactive contexts. To dis‐
300 able autoprint in an interactive session,
301 use the elfedit command:
302 > set a off
304 -d If set, this option causes elfedit to
309 issue informational messages describing
310 its internal operations and details of the
311 ELF object being processed. This can be
312 useful when a deep understanding of the
313 operation being carried out is desired.
314 -e cmd Specifies an edit command. Multiple -e
317 options can be specified. If edit commands
318 are present on the command line, elfedit
319 operates in batch mode. After opening the
320 file, elfedit executes each command in the
321 order given, after which the modified file
322 is saved and elfedit exits. Batch mode is
323 useful for performing simple operations
324 from shell scripts and makefiles.
325 -L path Sets default path for locating elfedit
328 modules. Modules are described in Module
329 Search Path section of this manual page..
330 -o default | simple | num The style used to display ELF data. This
333 option establishes the current style for
334 the session. It can be changed from within
335 the elfedit session by using the set
336 (sys:set) command, or by providing -o
337 options to the individual commands exe‐
338 cuted within the session.
339 default The default style is to display
341 output in a format intended for
342 human viewing. This style is
343 similar to that used by the
344 elfdump utility.
345 num Integer values are always shown
348 in integer form. Strings are
349 shown as the integer offset
350 into the containing string ta‐
351 ble.
352 simple When displaying strings from
355 within the ELF file, only the
356 string is displayed. Integer
357 values are displayed as sym‐
358 bolic constants if possible,
359 and in integer form otherwise.
360 No titles, headers, or other
361 supplemental output is shown.
362 -r Read-only mode. The input file is opened
366 for read-only access, and the results of
367 the edit session are not saved. elfedit
368 does not allow the outfile argument when
369 -r is specified. Read-only mode is highly
370 recommended when there is no intention to
371 modify the file. In addition to providing
372 extra protection against accidental modi‐
373 fication, it allows for the examination of
374 files for which the user does not have
375 write permission.
376
379 The following operands are supported:
380 infile Input file containing an ELF object to process.
382 This can be an executable (ET_EXEC), shared object (ET_DYN),
384 or relocatable object file, (ET_REL). Archives are not
385 directly supported. To edit an object in an archive, you
386 must extract the object, edit the copy, and then insert it
387 back into the archive.
388 If no infile is present, elfedit runs in a limited mode that
390 only allows executing commands from the sys: module. This
391 mode is primarily to allow access to the command documenta‐
392 tion available from the help (sys:help) command.
393 If infile is present, and no outfile is given, elfedit edits
395 the file in place, and writes the results into the same
396 file, causing the original file contents to be overwritten.
397 It is usually recommended that elfedit not be used in this
398 mode, and that an output file be specified. Once the result‐
399 ing file has been tested and validated, it can be moved into
400 the place of the original file.
401 The -r option can be used to open infile for read-only
403 access. This can be useful for examining an existing file
404 that you do not wish to modify.
405 outfile Output file. If both infile and outfile are present, infile
408 is opened for read-only access, and the modified object con‐
409 tents are written to outfile.
410
413 When supported by the system, elfedit runs as a 64-bit application,
414 capable of processing files greater than or equal to 2 Gbytes (2^31
415 bytes).
416 At startup, elfedit uses libelf to open the input file and cache a copy
419 of its contents in memory for editing. It can then execute one or more
420 commands. A session finishes by optionally writing the modified object
421 to the output file, and then exiting.
422 If no infile is present, elfedit runs in a limited mode that only
425 allows executing commands from the sys module. This mode is primarily
426 to allow access to the command documentation available from the help
427 (sys:help) command.
428 If one or more -e options are specified, the commands they supply are
431 executed in the order given. elfedit adds implicit calls to write
432 (sys:write) and quit (sys:quit) immediately following the given com‐
433 mands, causing the output file to be written and the elfedit process to
434 exit. This form of use is convenient in shell scripts and makefiles.
435 If no -e options are specified, elfedit reads commands from stdin and
438 executes them in the order given. The caller must explicitly issue the
439 write (sys:write) and quit (sys:quit) commands to save their work and
440 exit when running in this mode.
441
443 The following exit values are returned:
444 0 Successful completion.
446 1 A fatal error occurred.
449 2 Invalid command line options were specified.
452
455 In the following examples, interactive use of elfedit is shown with the
456 shell prompt (%) and the elfedit prompt (>). Neither of these charac‐
457 ters should be entered by the user.
458 Example 1 Changing the Runpath of an Executable
460 The following example presupposes an executable named prog, installed
463 in a bin directory that has an adjacent lib directory for sharable
464 objects. The following command sets the runpath of that executable to
465 the lib directory:
466 elfedit -e 'dyn:runpath $ORIGIN/../lib'
469 The use of single quotes with the argument to the -e option is neces‐
474 sary to ensure that the shell passes the entire command as a single
475 argument to elfedit.
476 Alternatively, the same operation can be done using elfedit in its non-
480 batch mode:
481 % elfedit prog
484 > dyn:runpath $ORIGIN/../lib
485 index tag value
486 [30] RUNPATH 0x3e6 $ORIGIN/../lib
487 > write
488 > quit
489 The addition or modification of elements such as runpath or needed
494 entries might only be achievable when padding exists within the
495 objects. See Notes.
496 Example 2 Removing a Hardware Capability Bit
499 Objects that require optional hardware support to run are built with a
502 capability section that contains a mask of bits specifying which capa‐
503 bilities they need. The runtime linker (ld.so.1) checks this mask
504 against the attributes of the running system to determine whether a
505 given object is able to be run by the current system. Programs that
506 require abilities not available on the system are prevented from run‐
507 ning.
508 This check prevents a naive program that does not explicitly check for
512 the hardware support it requires from crashing in a confusing manner.
513 However, it can be inconvenient for a program that is written to
514 explicitly check the system capabilities at runtime. Such a program
515 might have optimized code to use when the hardware supports it while
516 providing a generic fallback version that can be run, albeit more
517 slowly, otherwise. In this case, the hardware compatibility mask pre‐
518 vents such a program from running on the older hardware. In such a
519 case, removing the relevant bit from the mask allows the program to
520 run.
521 The following example removes the AV_386_SSE3 hardware capability from
525 an x86 binary that uses the SSE3 CPU extension. This transfers respon‐
526 sibility for validating the ability to use SSE3 from the runtime linker
527 to the program itself:
528 elfedit -e 'cap:hw1 -and -cmp sse3' prog
531 Example 3 Reading Information From an Object
535 elfedit can be used to extract specific targeted information from an
538 object. The following shell command reads the number of section headers
539 contained in the file /usr/bin/ls:
540 % SHNUM=`elfedit -r -onum -e 'ehdr:e_shnum' /usr/bin/ls`
543 % echo $SHNUM
544 29
545 You might get a different value, depending on the version of Solaris
550 and type of machine that you are using. The -r option causes the file
551 to be opened read-only, allowing a user with ordinary access permis‐
552 sions to open the file, and protecting against accidental damage to an
553 important system executable. The num output style is used in order to
554 obtain only the desired value, without any extraneous text.
555 Similarly, the following extracts the symbol type of the symbol unlink
559 from the C runtime library:
560 % TYPE=`elfedit -r -osimple -e 'sym:st_type unlink' /lib/libc.so`
563 % echo $TYPE
564 STT_FUNC
565
569 ELFEDIT_PATH Alters the default module search path. Module search
570 paths are discussed in the Module Search Path section
571 of this manual page.
572 LD_NOEXEC_64 Suppresses the automatic execution of the 64-bit
575 elfedit. By default, the 64-bit version of elfedit runs
576 if the system is 64-bit capable.
577 PAGER Interactively delivers output from elfedit to the
580 screen. If not set, more is used. See more(1).
581
584 /usr/lib/elfedit Default directory for elfedit modules that are
585 loaded on demand to supply editing commands.
586 ~/.teclarc Personal tecla customization file for command line
589 editing. See tecla(5).
590
593 See attributes(5) for descriptions of the following attributes:
594 ┌─────────────────────────────┬─────────────────────────────┐
599 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
600 ├─────────────────────────────┼─────────────────────────────┤
601 │Availability │SUNWbtool │
602 ├─────────────────────────────┼─────────────────────────────┤
603 │Interface Stability │Committed │
604 └─────────────────────────────┴─────────────────────────────┘
605
607 dump(1), elfdump(1), ld.so.1(1), more(1), nm(1), pvs(1), elf(3ELF),
608 libelf(3LIB), tecla(5), attributes(5)
609 Linker and Libraries Guide
612
614 elfedit is designed to be a tool for testing and development of the ELF
615 system. It offers the ability to examine and change nearly every piece
616 of ELF metadata in the object. It quietly allows edits that can produce
617 an invalid or unusable ELF file. The user is expected to have knowledge
618 of the ELF format and of the rules and conventions that govern them.
619 The Linker and Libraries Guide can be helpful when using elfedit.
620 elfedit allows the user to alter the ELF metadata in an object, but
623 cannot understand or alter the code of the actual program. Setting ELF
624 attributes such as types, sizes, alignments, and so forth in a manner
625 that does not agree with the actual contents of the file is therefore
626 likely to yield a broken and unusable output object. Such changes might
627 be useful for testing of linker components, but should be avoided oth‐
628 erwise.
629 Higher level operations, such as the use of the dyn:runpath command to
632 change the runpath of an object, are safe, and can be carried out with‐
633 out the sort of risk detailed in this section.
634
636 Not every ELF operation supported by elfedit can be successfully car‐
637 ried out on every ELF object. elfedit is constrained by the existing
638 sections found in the file.
639 One area of particular interest is that elfedit might not be able to
642 modify the runpath of a given object. To modify a runpath, the follow‐
643 ing must be true:
644 o The desired string must already exist in the dynamic string
646 table, or there must be enough reserved space within this
647 section for the new string to be added. If your object has a
648 string table reservation area, the value of the .dynamic
649 DT_SUNW_STRPAD element indicates the size of the area. The
650 following elfedit command can be used to check this:
651 % elfedit -r -e 'dyn:tag DT_SUNW_STRPAD' file
653 o The dynamic section must already have a runpath element, or
657 there must be an unused dynamic slot available where one can
658 be inserted. To test for the presence of an existing run‐
659 path:
660 % elfedit -r -e 'dyn:runpath' file
662 A dynamic section uses an element of type DT_NULL to termi‐
665 nate the array found in that section. The final DT_NULL can‐
666 not be changed, but if there are more than one of these,
667 elfedit can convert one of them into a runpath element. To
668 test for extra dynamic slots:
669 % elfedit -r -e 'dyn:tag DT_NULL' file
671 Older objects do not have the extra space necessary to complete such
676 operations. The space necessary to do so was introduced in the Solaris
677 Express Community Edition release.
678 When an operation fails, the detailed information printed using the -d
681 (debug) option can be very helpful in uncovering the reason why.
682 elfedit modules follow a convention by which commands that directly
685 manipulate a field in an ELF structure have the same name as the field,
686 while commands that implement higher level concepts do not. For
687 instance, the command to manipulate the e_flags field in the ELF header
688 is named ehdr:e_flags. Therefore, you generally find the command to
689 modify ELF fields by identifying the module and looking for a command
690 with the name of the field.
691SunOS 5.11 28 Jan 2008 elfedit(1)