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