1 ELFEDIT(1) User Commands ELFEDIT(1)
2
3
4
5 NAME
6 elfedit - examine or edit ELF files
7
8 SYNOPSIS
9 elfedit [-adr] [-e cmd] [-L path] [-o default | simple | num]
10 [infile] [outfile]
11
12
13 DESCRIPTION
14 elfedit is a tool for examining or modifying the contents of an
15 existing ELF object. Specifically, elfedit is used to modify the ELF
16 metadata 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
21 Syntax
22 elfedit processes commands from the command line (-e option) or from
23 standard input. If standard input is a terminal, elfedit provides
24 terminal 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
31
32 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
41
42 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
49
50 The syntax used to execute an elfedit command is intended to be
51 familiar 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
61
62 The interpretation of the characters in an elfedit token depends on the
63 style of quoting used:
64
65 Unquoted
66 Outside of single (') or double (") quotes, backslash
67 ( acts as an escape character. When a backslash
68 character is seen, elfedit ignores it, and treats the
69 character following it literally (even if the
70 following character is itself a backslash). This
71 feature can be used to insert a white space character
72 into a string argument to a command without having it
73 split the string into two separate tokens. Similarly,
74 it can be used to insert a quote or backslash as a
75 literal character.
76
77
78 Single Quotes
79 Within single quotes ('), white space characters do
80 not delimit tokens, and are interpreted as literal
81 characters within the token. Double quote (") and
82 backslash ( characters are interpreted as literal
83 characters, and have no special meaning.
84
85
86 Double Quotes
87 Within double quotes ("), white space characters do
88 not delimit tokens. Single quote characters are
89 interpreted literally and do not have a quoting
90 function. Backslash ( is an escape character which
91 operates similarly to the way it is used in the C
92 programming language within a string literal:
93
94 \a
95 alert (bell)
96
97
98 \b
99 backspace
100
101
102 \f
103 form feed
104
105
106 \n
107 newline
108
109
110 \r
111 return
112
113
114 \t
115 horizontal tab
116
117
118 \v
119 vertical tab
120
121
122 \
123 backslash
124
125
126 '
127 single quote
128
129
130 \"
131 double quote
132
133
134 \ooo
135 An octal constant, where ooo is one to three
136 octal digits (0...7)
137
138 Any other character following a backslash is an error.
139
140
141
142 The core commands belong to an internal module named sys. All other
143 modules are packaged as dynamically loadable sharable objects. elfedit
144 loads modules on demand, when a command that requires it is executed,
145 or as the result of executing the sys:load command. Due to its special
146 built in status, and because its commands are used heavily, elfedit
147 allows you to specify commands from the sys module without including
148 the sys: prefix, for example, load rather than sys:load. To access a
149 command from any other module, you must specify the full module:cmd
150 form.
151
152
153 elfedit is delivered with the following standard modules:
154
155 cap
156 Capabilities Section
157
158
159 dyn
160 Dynamic Section
161
162
163 ehdr
164 ELF Header
165
166
167 phdr
168 Program Header Array
169
170
171 shdr
172 Section Header Array
173
174
175 str
176 String Table Section
177
178
179 sym
180 Symbol Table Section
181
182
183 syminfo
184 Syminfo Section
185
186
187 sys
188 Core built in elfedit commands
189
190
191 Status And Command Documentation
192 Status And Command Documentation
193
194
195 The status (sys:status) command displays information about the current
196 elfedit session:
197
198 o Input and output files
199
200 o Option setting
201
202 o Module search path
203
204 o Modules loaded
205
206
207 Included with every elfedit module is extensive online documentation
208 for every command, in a format similar to UNIX manual pages. The help
209 (sys:help) command is used to display this information. To learn more
210 about elfedit, start elfedit and use the help command without
211 arguments:
212
213 % elfedit
214 > help
215
216
217
218
219 elfedit displays a welcome message with more information about elfedit,
220 and on how to use the help system.
221
222
223 To obtain summary information for a module:
224
225 > help module
226
227
228
229
230 To obtain the full documentation for a specific command provided by a
231 module:
232
233 > help module:command
234
235
236
237
238 Using the dyn module and dyn:runpath commands as examples:
239
240 > help dyn
241 > help dyn:runpath
242
243
244
245
246 help (sys:help) can be used to obtain help on itself:
247
248 > help help
249
250
251
252 Module Search Path
253 elfedit modules are implemented as sharable objects which are loaded on
254 demand. When a module is required, elfedit searches a module path in
255 order to locate the sharable object that implements the module. The
256 path is a sequence of directory names delimited by colon (:)
257 characters. In addition to normal characters, the path can also contain
258 any of the following tokens:
259
260 %i
261 Expands to the current instruction set architecture (ISA) name
262 (sparc, sparcv9, i386, amd64).
263
264
265 %I
266 Expands to the 64-bit ISA. This is the same thing as %i for
267 64-bit versions of elfedit, but expands to the empty string for
268 32-bit versions.
269
270
271 %o
272 Expands to the old value of the path being modified. This is
273 useful for appending or prepending directories to the default
274 path.
275
276
277 %r
278 Root of file system tree holding the elfedit program, assuming
279 that elfedit is installed as usr/bin/elfedit within the tree. On
280 a standard system, this is simply the standard system root
281 directory (/). On a development system, where the copy of
282 elfedit can be installed elsewhere, the use of %r can be used to
283 ensure that the matching set of modules are used.
284
285
286 %%
287 Expands to a single % character
288
289
290
291 The default module search path for elfedit is:
292
293 %r/usr/lib/elfedit/%I
294
295
296
297
298 Expanding the tokens, this is:
299
300 /usr/lib/elfedit
301 32-bit elfedit
302
303
304 /usr/lib/elfedit/sparcv9
305 64-bit elfedit (sparc)
306
307
308 /usr/lib/elfedit/amd64
309 64-bit elfedit (x86)
310
311
312
313 The default search path can be changed by setting the ELFEDIT_PATH
314 environment variable, or by using the -L command line option. If you
315 specify both, the -L option supersedes the environment variable.
316
317 OPTIONS
318 The following options are supported:
319
320 -a
321 Enable autoprint mode. When autoprint is
322 enabled, elfedit prints the modified
323 values that result when the ELF file is
324 modified. This output is shown in the
325 current output style, which can be changed
326 using the -o option. The default output
327 style is the style used by the elfdump(1)
328 utility. autoprint mode is the default
329 when elfedit is used interactively (when
330 stdin and stdout are terminals).
331 Therefore, the -a option only has meaning
332 when elfedit is used in non-interactive
333 contexts. To disable autoprint in an
334 interactive session, use the elfedit
335 command:
336
337 > set a off
338
339
340
341
342 -d
343 If set, this option causes elfedit to
344 issue informational messages describing
345 its internal operations and details of the
346 ELF object being processed. This can be
347 useful when a deep understanding of the
348 operation being carried out is desired.
349
350
351 -e cmd
352 Specifies an edit command. Multiple -e
353 options can be specified. If edit commands
354 are present on the command line, elfedit
355 operates in batch mode. After opening the
356 file, elfedit executes each command in the
357 order given, after which the modified file
358 is saved and elfedit exits. Batch mode is
359 useful for performing simple operations
360 from shell scripts and makefiles.
361
362
363 -L path
364 Sets default path for locating elfedit
365 modules. Modules are described in Module
366 Search Path section of this manual page..
367
368
369 -o default | simple | num
370 The style used to display ELF data. This
371 option establishes the current style for
372 the session. It can be changed from within
373 the elfedit session by using the set
374 (sys:set) command, or by providing -o
375 options to the individual commands
376 executed within the session.
377
378 default
379 The default style is to display
380 output in a format intended for
381 human viewing. This style is
382 similar to that used by the
383 elfdump utility.
384
385
386 num
387 Integer values are always shown
388 in integer form. Strings are
389 shown as the integer offset
390 into the containing string
391 table.
392
393
394 simple
395 When displaying strings from
396 within the ELF file, only the
397 string is displayed. Integer
398 values are displayed as
399 symbolic constants if possible,
400 and in integer form otherwise.
401 No titles, headers, or other
402 supplemental output is shown.
403
404
405
406 -r
407 Read-only mode. The input file is opened
408 for read-only access, and the results of
409 the edit session are not saved. elfedit
410 does not allow the outfile argument when
411 -r is specified. Read-only mode is highly
412 recommended when there is no intention to
413 modify the file. In addition to providing
414 extra protection against accidental
415 modification, it allows for the
416 examination of files for which the user
417 does not have write permission.
418
419
420 OPERANDS
421 The following operands are supported:
422
423 infile
424 Input file containing an ELF object to process.
425
426 This can be an executable (ET_EXEC), shared object (ET_DYN),
427 or relocatable object file, (ET_REL). Archives are not
428 directly supported. To edit an object in an archive, you
429 must extract the object, edit the copy, and then insert it
430 back into the archive.
431
432 If no infile is present, elfedit runs in a limited mode that
433 only allows executing commands from the sys: module. This
434 mode is primarily to allow access to the command
435 documentation available from the help (sys:help) command.
436
437 If infile is present, and no outfile is given, elfedit edits
438 the file in place, and writes the results into the same
439 file, causing the original file contents to be overwritten.
440 It is usually recommended that elfedit not be used in this
441 mode, and that an output file be specified. Once the
442 resulting file has been tested and validated, it can be
443 moved into the place of the original file.
444
445 The -r option can be used to open infile for read-only
446 access. This can be useful for examining an existing file
447 that you do not wish to modify.
448
449
450 outfile
451 Output file. If both infile and outfile are present, infile
452 is opened for read-only access, and the modified object
453 contents are written to outfile.
454
455
456 USAGE
457 When supported by the system, elfedit runs as a 64-bit application,
458 capable of processing files greater than or equal to 2 Gbytes (2^31
459 bytes).
460
461
462 At startup, elfedit uses libelf to open the input file and cache a copy
463 of its contents in memory for editing. It can then execute one or more
464 commands. A session finishes by optionally writing the modified object
465 to the output file, and then exiting.
466
467
468 If no infile is present, elfedit runs in a limited mode that only
469 allows executing commands from the sys module. This mode is primarily
470 to allow access to the command documentation available from the help
471 (sys:help) command.
472
473
474 If one or more -e options are specified, the commands they supply are
475 executed in the order given. elfedit adds implicit calls to write
476 (sys:write) and quit (sys:quit) immediately following the given
477 commands, causing the output file to be written and the elfedit process
478 to exit. This form of use is convenient in shell scripts and makefiles.
479
480
481 If no -e options are specified, elfedit reads commands from stdin and
482 executes them in the order given. The caller must explicitly issue the
483 write (sys:write) and quit (sys:quit) commands to save their work and
484 exit when running in this mode.
485
486 EXIT STATUS
487 The following exit values are returned:
488
489 0
490 Successful completion.
491
492
493 1
494 A fatal error occurred.
495
496
497 2
498 Invalid command line options were specified.
499
500
501 EXAMPLES
502 In the following examples, interactive use of elfedit is shown with the
503 shell prompt (%) and the elfedit prompt (>). Neither of these
504 characters should be entered by the user.
505
506 Example 1 Changing the Runpath of an Executable
507
508
509 The following example presupposes an executable named prog, installed
510 in a bin directory that has an adjacent lib directory for sharable
511 objects. The following command sets the runpath of that executable to
512 the lib directory:
513
514
515 elfedit -e 'dyn:runpath $ORIGIN/../lib'
516
517
518
519
520 The use of single quotes with the argument to the -e option is
521 necessary to ensure that the shell passes the entire command as a
522 single argument to elfedit.
523
524
525
526 Alternatively, the same operation can be done using elfedit in its non-
527 batch mode:
528
529
530 % elfedit prog
531 > dyn:runpath $ORIGIN/../lib
532 index tag value
533 [30] RUNPATH 0x3e6 $ORIGIN/../lib
534 > write
535 > quit
536
537
538
539
540 The addition or modification of elements such as runpath or needed
541 entries might only be achievable when padding exists within the
542 objects. See Notes.
543
544
545 Example 2 Removing a Hardware Capability Bit
546
547
548 Objects that require optional hardware support to run are built with a
549 capability section that contains a mask of bits specifying which
550 capabilities they need. The runtime linker (ld.so.1) checks this mask
551 against the attributes of the running system to determine whether a
552 given object is able to be run by the current system. Programs that
553 require abilities not available on the system are prevented from
554 running.
555
556
557
558 This check prevents a naive program that does not explicitly check for
559 the hardware support it requires from crashing in a confusing manner.
560 However, it can be inconvenient for a program that is written to
561 explicitly check the system capabilities at runtime. Such a program
562 might have optimized code to use when the hardware supports it while
563 providing a generic fallback version that can be run, albeit more
564 slowly, otherwise. In this case, the hardware compatibility mask
565 prevents such a program from running on the older hardware. In such a
566 case, removing the relevant bit from the mask allows the program to
567 run.
568
569
570
571 The following example removes the AV_386_SSE3 hardware capability from
572 an x86 binary that uses the SSE3 CPU extension. This transfers
573 responsibility for validating the ability to use SSE3 from the runtime
574 linker to the program itself:
575
576
577 elfedit -e 'cap:hw1 -and -cmp sse3' prog
578
579
580
581 Example 3 Reading Information From an Object
582
583
584 elfedit can be used to extract specific targeted information from an
585 object. The following shell command reads the number of section headers
586 contained in the file /usr/bin/ls:
587
588
589 % SHNUM=`elfedit -r -onum -e 'ehdr:e_shnum' /usr/bin/ls`
590 % echo $SHNUM
591 29
592
593
594
595
596 You might get a different value, depending on the version of Solaris
597 and type of machine that you are using. The -r option causes the file
598 to be opened read-only, allowing a user with ordinary access
599 permissions to open the file, and protecting against accidental damage
600 to an important system executable. The num output style is used in
601 order to obtain only the desired value, without any extraneous text.
602
603
604
605 Similarly, the following extracts the symbol type of the symbol unlink
606 from the C runtime library:
607
608
609 % TYPE=`elfedit -r -osimple -e 'sym:st_type unlink' /lib/libc.so`
610 % echo $TYPE
611 STT_FUNC
612
613
614
615 ENVIRONMENT VARIABLES
616 ELFEDIT_PATH
617 Alters the default module search path. Module search
618 paths are discussed in the Module Search Path section
619 of this manual page.
620
621
622 LD_NOEXEC_64
623 Suppresses the automatic execution of the 64-bit
624 elfedit. By default, the 64-bit version of elfedit runs
625 if the system is 64-bit capable.
626
627
628 PAGER
629 Interactively delivers output from elfedit to the
630 screen. If not set, more is used. See more(1).
631
632
633 FILES
634 /usr/lib/elfedit
635 Default directory for elfedit modules that are
636 loaded on demand to supply editing commands.
637
638
639 ~/.teclarc
640 Personal tecla customization file for command line
641 editing. See tecla(5).
642
643
644 ATTRIBUTES
645 See attributes(5) for descriptions of the following attributes:
646
647
648
649
650 +--------------------+-----------------+
651 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
652 +--------------------+-----------------+
653 |Interface Stability | Committed |
654 +--------------------+-----------------+
655
656 SEE ALSO
657 dump(1), elfdump(1), ld.so.1(1), more(1), nm(1), pvs(1), elf(3ELF),
658 libelf(3LIB), tecla(5), attributes(5)
659
660
661 Linker and Libraries Guide
662
663 WARNINGS
664 elfedit is designed to be a tool for testing and development of the ELF
665 system. It offers the ability to examine and change nearly every piece
666 of ELF metadata in the object. It quietly allows edits that can produce
667 an invalid or unusable ELF file. The user is expected to have knowledge
668 of the ELF format and of the rules and conventions that govern them.
669 The Linker and Libraries Guide can be helpful when using elfedit.
670
671
672 elfedit allows the user to alter the ELF metadata in an object, but
673 cannot understand or alter the code of the actual program. Setting ELF
674 attributes such as types, sizes, alignments, and so forth in a manner
675 that does not agree with the actual contents of the file is therefore
676 likely to yield a broken and unusable output object. Such changes might
677 be useful for testing of linker components, but should be avoided
678 otherwise.
679
680
681 Higher level operations, such as the use of the dyn:runpath command to
682 change the runpath of an object, are safe, and can be carried out
683 without the sort of risk detailed in this section.
684
685 NOTES
686 Not every ELF operation supported by elfedit can be successfully
687 carried out on every ELF object. elfedit is constrained by the existing
688 sections found in the file.
689
690
691 One area of particular interest is that elfedit might not be able to
692 modify the runpath of a given object. To modify a runpath, the
693 following must be true:
694
695 o The desired string must already exist in the dynamic string
696 table, or there must be enough reserved space within this
697 section for the new string to be added. If your object has a
698 string table reservation area, the value of the .dynamic
699 DT_SUNW_STRPAD element indicates the size of the area. The
700 following elfedit command can be used to check this:
701
702 % elfedit -r -e 'dyn:tag DT_SUNW_STRPAD' file
703
704
705
706 o The dynamic section must already have a runpath element, or
707 there must be an unused dynamic slot available where one can
708 be inserted. To test for the presence of an existing
709 runpath:
710
711 % elfedit -r -e 'dyn:runpath' file
712
713
714 A dynamic section uses an element of type DT_NULL to
715 terminate the array found in that section. The final DT_NULL
716 cannot be changed, but if there are more than one of these,
717 elfedit can convert one of them into a runpath element. To
718 test for extra dynamic slots:
719
720 % elfedit -r -e 'dyn:tag DT_NULL' file
721
722
723
724
725 Older objects do not have the extra space necessary to complete such
726 operations. The space necessary to do so was introduced in the Solaris
727 Express Community Edition release.
728
729
730 When an operation fails, the detailed information printed using the -d
731 (debug) option can be very helpful in uncovering the reason why.
732
733
734 elfedit modules follow a convention by which commands that directly
735 manipulate a field in an ELF structure have the same name as the field,
736 while commands that implement higher level concepts do not. For
737 instance, the command to manipulate the e_flags field in the ELF header
738 is named ehdr:e_flags. Therefore, you generally find the command to
739 modify ELF fields by identifying the module and looking for a command
740 with the name of the field.
741
742
743
744 May 17, 2020 ELFEDIT(1)