12745 man page typos

   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)
--- EOF ---