1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems Inc. All
3 .\" Rights Reserved.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH ELFEDIT 1 "Jan 28, 2008"
8 .SH NAME
9 elfedit \- examine or edit ELF files
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBelfedit\fR [\fB-adr\fR] [\fB-e\fR \fIcmd\fR] [\fB-L\fR \fIpath\fR] [\fB-o\fR \fBdefault\fR | \fBsimple\fR | \fBnum\fR]
14 [\fIinfile\fR] [\fIoutfile\fR]
15 .fi
16
17 .SH DESCRIPTION
18 .sp
19 .LP
20 \fBelfedit\fR is a tool for examining or modifying the contents of an existing
21 ELF object. Specifically, \fBelfedit\fR is used to modify the ELF metadata
22 contained in the object. Access is provided to most of the ELF data contained
23 in an object, including the ELF header, section header table, program header
24 table, dynamic section, hardware and software capabilities, string tables, and
25 symbol tables.
26 .SS "Syntax"
27 .sp
28 .LP
29 \fBelfedit\fR processes commands from the command line (\fB-e\fR option) or
30 from standard input. If standard input is a terminal, \fBelfedit\fR provides
31 terminal editing capabilities, as well as extensive command completion. ELF
32 uses many standard symbolic names for special integer values and bit masks.
33 \fBelfedit\fR is aware of most possible completions for such names. You can
34 press TAB at any point while entering an \fBelfedit\fR command to cause
35 \fBelfedit\fR to display a usage message and any known completions for the text
36 at the current cursor.
37 .sp
38 .LP
39 \fBelfedit\fR functionality is organized in the form of modules. Each module
40 delivers a set of commands, focused on related functionality. A command is
41 specified by combining the module and command names with a colon (\fB:\fR)
42 delimiter, with no intervening white space. For example, \fBdyn:runpath\fR
43 refers to the \fBrunpath\fR command provided by the \fBdyn\fR module. Module
44 names must be unique. The command names within a given module are unique within
45 that module, but the same command names can be used in more than one module.
46 .sp
47 .LP
48 Some modules designate one of their commands to be the default command for that
285
286 .sp
287 .ne 2
288 .na
289 \fB\fBsyminfo\fR\fR
290 .ad
291 .RS 11n
292 \fBSyminfo\fR Section
293 .RE
294
295 .sp
296 .ne 2
297 .na
298 \fB\fBsys\fR\fR
299 .ad
300 .RS 11n
301 Core built in \fBelfedit\fR commands
302 .RE
303
304 .SS "Status And Command Documentation"
305 .sp
306 .LP
307 Status And Command Documentation
308 .sp
309 .LP
310 The status (\fBsys:status\fR) command displays information about the current
311 \fBelfedit\fR session:
312 .RS +4
313 .TP
314 .ie t \(bu
315 .el o
316 Input and output files
317 .RE
318 .RS +4
319 .TP
320 .ie t \(bu
321 .el o
322 Option setting
323 .RE
324 .RS +4
325 .TP
326 .ie t \(bu
382 .in +2
383 .nf
384 > help dyn
385 > help dyn:runpath
386 .fi
387 .in -2
388 .sp
389
390 .sp
391 .LP
392 help (\fBsys:help\fR) can be used to obtain help on itself:
393 .sp
394 .in +2
395 .nf
396 > help help
397 .fi
398 .in -2
399 .sp
400
401 .SS "Module Search Path"
402 .sp
403 .LP
404 \fBelfedit\fR modules are implemented as sharable objects which are loaded on
405 demand. When a module is required, \fBelfedit\fR searches a module path in
406 order to locate the sharable object that implements the module. The path is a
407 sequence of directory names delimited by colon (\fB:\fR) characters. In
408 addition to normal characters, the path can also contain any of the following
409 tokens:
410 .sp
411 .ne 2
412 .na
413 \fB\fB%i\fR\fR
414 .ad
415 .RS 6n
416 Expands to the current instruction set architecture (ISA) name (\fBsparc\fR,
417 \fBsparcv9\fR, \fBi386\fR, \fBamd64\fR).
418 .RE
419
420 .sp
421 .ne 2
422 .na
423 \fB\fB%I\fR\fR
427 versions of \fBelfedit\fR, but expands to the empty string for 32-bit versions.
428 .RE
429
430 .sp
431 .ne 2
432 .na
433 \fB\fB%o\fR\fR
434 .ad
435 .RS 6n
436 Expands to the old value of the path being modified. This is useful for
437 appending or prepending directories to the default path.
438 .RE
439
440 .sp
441 .ne 2
442 .na
443 \fB\fB%r\fR\fR
444 .ad
445 .RS 6n
446 Root of file system tree holding the \fBelfedit\fR program, assuming that
447 \fBelfedit\fR is installed as \fBusr/bin/elfedi\fRt within the tree. On a
448 standard system, this is simply the standard system root directory (\fB/\fR).
449 On a development system, where the copy of \fBelfedit\fR can be installed
450 elsewhere, the use of \fB%r\fR can be used to ensure that the matching set of
451 modules are used.
452 .RE
453
454 .sp
455 .ne 2
456 .na
457 \fB\fB%%\fR\fR
458 .ad
459 .RS 6n
460 Expands to a single \fB%\fR character
461 .RE
462
463 .sp
464 .LP
465 The default module search path for \fBelfedit\fR is:
466 .sp
467 .in +2
490 .ad
491 .RS 28n
492 64-bit \fBelfedit\fR (\fBsparc\fR)
493 .RE
494
495 .sp
496 .ne 2
497 .na
498 \fB\fB/usr/lib/elfedit/amd64\fR\fR
499 .ad
500 .RS 28n
501 64-bit \fBelfedit\fR (\fBx86\fR)
502 .RE
503
504 .sp
505 .LP
506 The default search path can be changed by setting the \fBELFEDIT_PATH\fR
507 environment variable, or by using the \fB-L\fR command line option. If you
508 specify both, the \fB-L\fR option supersedes the environment variable.
509 .SH OPTIONS
510 .sp
511 .LP
512 The following options are supported:
513 .sp
514 .ne 2
515 .na
516 \fB\fB-a\fR\fR
517 .ad
518 .RS 29n
519 Enable \fBautoprint\fR mode. When \fBautoprint\fR is enabled, \fBelfedit\fR
520 prints the modified values that result when the ELF file is modified. This
521 output is shown in the current output style, which can be changed using the
522 \fB-o\fR option. The default output style is the style used by the
523 \fBelfdump\fR(1) utility. \fBautoprint\fR mode is the default when
524 \fBelfedit\fR is used interactively (when \fBstdin\fR and \fBstdout\fR are
525 terminals). Therefore, the \fB-a\fR option only has meaning when \fBelfedit\fR
526 is used in non-interactive contexts. To disable \fBautoprint\fR in an
527 interactive session, use the \fBelfedit\fR command:
528 .sp
529 .in +2
530 .nf
531 > set a off
611 form otherwise. No titles, headers, or other supplemental output is shown.
612 .RE
613
614 .RE
615
616 .sp
617 .ne 2
618 .na
619 \fB\fB-r\fR\fR
620 .ad
621 .RS 29n
622 Read-only mode. The input file is opened for read-only access, and the results
623 of the edit session are not saved. \fBelfedit\fR does not allow the
624 \fIoutfile\fR argument when \fB-r\fR is specified. Read-only mode is highly
625 recommended when there is no intention to modify the file. In addition to
626 providing extra protection against accidental modification, it allows for the
627 examination of files for which the user does not have write permission.
628 .RE
629
630 .SH OPERANDS
631 .sp
632 .LP
633 The following operands are supported:
634 .sp
635 .ne 2
636 .na
637 \fB\fIinfile\fR\fR
638 .ad
639 .RS 11n
640 Input file containing an ELF object to process.
641 .sp
642 This can be an executable (\fBET_EXEC\fR), shared object (\fBET_DYN\fR), or
643 relocatable object file, (\fBET_REL\fR). Archives are not directly supported.
644 To edit an object in an archive, you must extract the object, edit the copy,
645 and then insert it back into the archive.
646 .sp
647 If no \fIinfile\fR is present, \fBelfedit\fR runs in a limited mode that only
648 allows executing commands from the \fBsys:\fR module. This mode is primarily to
649 allow access to the command documentation available from the help
650 (\fBsys:help\fR) command.
651 .sp
652 If \fIinfile\fR is present, and no \fIoutfile\fR is given, \fBelfedit\fR edits
655 \fBelfedit\fR not be used in this mode, and that an output file be specified.
656 Once the resulting file has been tested and validated, it can be moved into the
657 place of the original file.
658 .sp
659 The \fB-r\fR option can be used to open \fIinfile\fR for read-only access. This
660 can be useful for examining an existing file that you do not wish to modify.
661 .RE
662
663 .sp
664 .ne 2
665 .na
666 \fB\fIoutfile\fR\fR
667 .ad
668 .RS 11n
669 Output file. If both \fIinfile\fR and \fIoutfile\fR are present, \fIinfile\fR
670 is opened for read-only access, and the modified object contents are written to
671 \fIoutfile\fR.
672 .RE
673
674 .SH USAGE
675 .sp
676 .LP
677 When supported by the system, \fBelfedit\fR runs as a 64-bit application,
678 capable of processing files greater than or equal to 2 Gbytes (2^31 bytes).
679 .sp
680 .LP
681 At startup, \fBelfedit\fR uses \fBlibelf\fR to open the input file and cache a
682 copy of its contents in memory for editing. It can then execute one or more
683 commands. A session finishes by optionally writing the modified object to the
684 output file, and then exiting.
685 .sp
686 .LP
687 If no \fIinfile\fR is present, \fBelfedit\fR runs in a limited mode that only
688 allows executing commands from the \fBsys\fR module. This mode is primarily to
689 allow access to the command documentation available from the help
690 (\fBsys:help\fR) command.
691 .sp
692 .LP
693 If one or more \fB-e\fR options are specified, the commands they supply are
694 executed in the order given. \fBelfedit\fR adds implicit calls to write
695 (\fBsys:write\fR) and quit (\fBsys:qui\fRt) immediately following the given
696 commands, causing the output file to be written and the \fBelfedit\fR process
697 to exit. This form of use is convenient in shell scripts and makefiles.
698 .sp
699 .LP
700 If no \fB-e\fR options are specified, \fBelfedit\fR reads commands from
701 \fBstdin\fR and executes them in the order given. The caller must explicitly
702 issue the write (\fBsys:write\fR) and quit (\fBsys:quit\fR) commands to save
703 their work and exit when running in this mode.
704 .SH EXIT STATUS
705 .sp
706 .LP
707 The following exit values are returned:
708 .sp
709 .ne 2
710 .na
711 \fB\fB0\fR\fR
712 .ad
713 .RS 5n
714 Successful completion.
715 .RE
716
717 .sp
718 .ne 2
719 .na
720 \fB\fB1\fR\fR
721 .ad
722 .RS 5n
723 A fatal error occurred.
724 .RE
725
726 .sp
727 .ne 2
728 .na
729 \fB\fB2\fR\fR
730 .ad
731 .RS 5n
732 Invalid command line options were specified.
733 .RE
734
735 .SH EXAMPLES
736 .sp
737 .LP
738 In the following examples, interactive use of \fBelfedit\fR is shown with the
739 shell prompt (\fB%\fR) and the \fBelfedit\fR prompt (\fB>\fR). Neither of these
740 characters should be entered by the user.
741 .LP
742 \fBExample 1 \fRChanging the Runpath of an Executable
743 .sp
744 .LP
745 The following example presupposes an executable named \fBprog\fR, installed in
746 a bin directory that has an adjacent lib directory for sharable objects. The
747 following command sets the \fBrunpath\fR of that executable to the \fBlib\fR
748 directory:
749
750 .sp
751 .in +2
752 .nf
753 elfedit -e 'dyn:runpath $ORIGIN/../lib'
754 .fi
755 .in -2
756 .sp
757
849 and protecting against accidental damage to an important system executable. The
850 \fBnum\fR output style is used in order to obtain only the desired value,
851 without any extraneous text.
852
853 .sp
854 .LP
855 Similarly, the following extracts the symbol type of the symbol \fBunlink\fR
856 from the C runtime library:
857
858 .sp
859 .in +2
860 .nf
861 % TYPE=`elfedit -r -osimple -e 'sym:st_type unlink' /lib/libc.so`
862 % echo $TYPE
863 STT_FUNC
864 .fi
865 .in -2
866 .sp
867
868 .SH ENVIRONMENT VARIABLES
869 .sp
870 .ne 2
871 .na
872 \fB\fBELFEDIT_PATH\fR\fR
873 .ad
874 .RS 16n
875 Alters the default module search path. Module search paths are discussed in the
876 \fBModule Search Path\fR section of this manual page.
877 .RE
878
879 .sp
880 .ne 2
881 .na
882 \fB\fBLD_NOEXEC_64\fR\fR
883 .ad
884 .RS 16n
885 Suppresses the automatic execution of the 64-bit \fBelfedit\fR. By default, the
886 64-bit version of \fBelfedit\fR runs if the system is 64-bit capable.
887 .RE
888
889 .sp
890 .ne 2
891 .na
892 \fB\fBPAGER\fR\fR
893 .ad
894 .RS 16n
895 Interactively delivers output from \fBelfedit\fR to the screen. If not set,
896 \fBmore\fR is used. See \fBmore\fR(1).
897 .RE
898
899 .SH FILES
900 .sp
901 .ne 2
902 .na
903 \fB\fB/usr/lib/elfedit\fR\fR
904 .ad
905 .RS 20n
906 Default directory for \fBelfedit\fR modules that are loaded on demand to supply
907 editing commands.
908 .RE
909
910 .sp
911 .ne 2
912 .na
913 \fB\fB~/.teclarc\fR\fR
914 .ad
915 .RS 20n
916 Personal \fBtecla\fR customization file for command line editing. See
917 \fBtecla\fR(5).
918 .RE
919
920 .SH ATTRIBUTES
921 .sp
922 .LP
923 See \fBattributes\fR(5) for descriptions of the following attributes:
924 .sp
925
926 .sp
927 .TS
928 box;
929 c | c
930 l | l .
931 ATTRIBUTE TYPE ATTRIBUTE VALUE
932 _
933 Interface Stability Committed
934 .TE
935
936 .SH SEE ALSO
937 .sp
938 .LP
939 \fBdump\fR(1), \fBelfdump\fR(1), \fBld.so.1\fR(1), \fBmore\fR(1), \fBnm\fR(1),
940 \fBpvs\fR(1), \fBelf\fR(3ELF), \fBlibelf\fR(3LIB), \fBtecla\fR(5),
941 \fBattributes\fR(5)
942 .sp
943 .LP
944 \fILinker and Libraries Guide\fR
945 .SH WARNINGS
946 .sp
947 .LP
948 \fBelfedit\fR is designed to be a tool for testing and development of the ELF
949 system. It offers the ability to examine and change nearly every piece of ELF
950 metadata in the object. It quietly allows edits that can produce an invalid or
951 unusable ELF file. The user is expected to have knowledge of the ELF format and
952 of the rules and conventions that govern them. The \fILinker and Libraries
953 Guide\fR can be helpful when using \fBelfedit\fR.
954 .sp
955 .LP
956 \fBelfedit\fR allows the user to alter the ELF metadata in an object, but
957 cannot understand or alter the code of the actual program. Setting ELF
958 attributes such as types, sizes, alignments, and so forth in a manner that does
959 not agree with the actual contents of the file is therefore likely to yield a
960 broken and unusable output object. Such changes might be useful for testing of
961 linker components, but should be avoided otherwise.
962 .sp
963 .LP
964 Higher level operations, such as the use of the \fBdyn:runpath\fR command to
965 change the \fBrunpath\fR of an object, are safe, and can be carried out without
966 the sort of risk detailed in this section.
967 .SH NOTES
968 .sp
969 .LP
970 Not every ELF operation supported by \fBelfedit\fR can be successfully carried
971 out on every ELF object. \fBelfedit\fR is constrained by the existing sections
972 found in the file.
973 .sp
974 .LP
975 One area of particular interest is that \fBelfedit\fR might not be able to
976 modify the \fBrunpath\fR of a given object. To modify a \fBrunpath\fR, the
977 following must be true:
978 .RS +4
979 .TP
980 .ie t \(bu
981 .el o
982 The desired string must already exist in the dynamic string table, or there
983 must be enough reserved space within this section for the new string to be
984 added. If your object has a string table reservation area, the value of the
985 \fB\&.dynamic DT_SUNW_STRPAD\fR element indicates the size of the area. The
986 following \fBelfedit\fR command can be used to check this:
987 .sp
988 .in +2
989 .nf
|
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems Inc. All
3 .\" Rights Reserved.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH ELFEDIT 1 "May 17, 2020"
8 .SH NAME
9 elfedit \- examine or edit ELF files
10 .SH SYNOPSIS
11 .nf
12 \fBelfedit\fR [\fB-adr\fR] [\fB-e\fR \fIcmd\fR] [\fB-L\fR \fIpath\fR] [\fB-o\fR \fBdefault\fR | \fBsimple\fR | \fBnum\fR]
13 [\fIinfile\fR] [\fIoutfile\fR]
14 .fi
15
16 .SH DESCRIPTION
17 \fBelfedit\fR is a tool for examining or modifying the contents of an existing
18 ELF object. Specifically, \fBelfedit\fR is used to modify the ELF metadata
19 contained in the object. Access is provided to most of the ELF data contained
20 in an object, including the ELF header, section header table, program header
21 table, dynamic section, hardware and software capabilities, string tables, and
22 symbol tables.
23 .SS "Syntax"
24 \fBelfedit\fR processes commands from the command line (\fB-e\fR option) or
25 from standard input. If standard input is a terminal, \fBelfedit\fR provides
26 terminal editing capabilities, as well as extensive command completion. ELF
27 uses many standard symbolic names for special integer values and bit masks.
28 \fBelfedit\fR is aware of most possible completions for such names. You can
29 press TAB at any point while entering an \fBelfedit\fR command to cause
30 \fBelfedit\fR to display a usage message and any known completions for the text
31 at the current cursor.
32 .sp
33 .LP
34 \fBelfedit\fR functionality is organized in the form of modules. Each module
35 delivers a set of commands, focused on related functionality. A command is
36 specified by combining the module and command names with a colon (\fB:\fR)
37 delimiter, with no intervening white space. For example, \fBdyn:runpath\fR
38 refers to the \fBrunpath\fR command provided by the \fBdyn\fR module. Module
39 names must be unique. The command names within a given module are unique within
40 that module, but the same command names can be used in more than one module.
41 .sp
42 .LP
43 Some modules designate one of their commands to be the default command for that
280
281 .sp
282 .ne 2
283 .na
284 \fB\fBsyminfo\fR\fR
285 .ad
286 .RS 11n
287 \fBSyminfo\fR Section
288 .RE
289
290 .sp
291 .ne 2
292 .na
293 \fB\fBsys\fR\fR
294 .ad
295 .RS 11n
296 Core built in \fBelfedit\fR commands
297 .RE
298
299 .SS "Status And Command Documentation"
300 Status And Command Documentation
301 .sp
302 .LP
303 The status (\fBsys:status\fR) command displays information about the current
304 \fBelfedit\fR session:
305 .RS +4
306 .TP
307 .ie t \(bu
308 .el o
309 Input and output files
310 .RE
311 .RS +4
312 .TP
313 .ie t \(bu
314 .el o
315 Option setting
316 .RE
317 .RS +4
318 .TP
319 .ie t \(bu
375 .in +2
376 .nf
377 > help dyn
378 > help dyn:runpath
379 .fi
380 .in -2
381 .sp
382
383 .sp
384 .LP
385 help (\fBsys:help\fR) can be used to obtain help on itself:
386 .sp
387 .in +2
388 .nf
389 > help help
390 .fi
391 .in -2
392 .sp
393
394 .SS "Module Search Path"
395 \fBelfedit\fR modules are implemented as sharable objects which are loaded on
396 demand. When a module is required, \fBelfedit\fR searches a module path in
397 order to locate the sharable object that implements the module. The path is a
398 sequence of directory names delimited by colon (\fB:\fR) characters. In
399 addition to normal characters, the path can also contain any of the following
400 tokens:
401 .sp
402 .ne 2
403 .na
404 \fB\fB%i\fR\fR
405 .ad
406 .RS 6n
407 Expands to the current instruction set architecture (ISA) name (\fBsparc\fR,
408 \fBsparcv9\fR, \fBi386\fR, \fBamd64\fR).
409 .RE
410
411 .sp
412 .ne 2
413 .na
414 \fB\fB%I\fR\fR
418 versions of \fBelfedit\fR, but expands to the empty string for 32-bit versions.
419 .RE
420
421 .sp
422 .ne 2
423 .na
424 \fB\fB%o\fR\fR
425 .ad
426 .RS 6n
427 Expands to the old value of the path being modified. This is useful for
428 appending or prepending directories to the default path.
429 .RE
430
431 .sp
432 .ne 2
433 .na
434 \fB\fB%r\fR\fR
435 .ad
436 .RS 6n
437 Root of file system tree holding the \fBelfedit\fR program, assuming that
438 \fBelfedit\fR is installed as \fBusr/bin/elfedit\fR within the tree. On a
439 standard system, this is simply the standard system root directory (\fB/\fR).
440 On a development system, where the copy of \fBelfedit\fR can be installed
441 elsewhere, the use of \fB%r\fR can be used to ensure that the matching set of
442 modules are used.
443 .RE
444
445 .sp
446 .ne 2
447 .na
448 \fB\fB%%\fR\fR
449 .ad
450 .RS 6n
451 Expands to a single \fB%\fR character
452 .RE
453
454 .sp
455 .LP
456 The default module search path for \fBelfedit\fR is:
457 .sp
458 .in +2
481 .ad
482 .RS 28n
483 64-bit \fBelfedit\fR (\fBsparc\fR)
484 .RE
485
486 .sp
487 .ne 2
488 .na
489 \fB\fB/usr/lib/elfedit/amd64\fR\fR
490 .ad
491 .RS 28n
492 64-bit \fBelfedit\fR (\fBx86\fR)
493 .RE
494
495 .sp
496 .LP
497 The default search path can be changed by setting the \fBELFEDIT_PATH\fR
498 environment variable, or by using the \fB-L\fR command line option. If you
499 specify both, the \fB-L\fR option supersedes the environment variable.
500 .SH OPTIONS
501 The following options are supported:
502 .sp
503 .ne 2
504 .na
505 \fB\fB-a\fR\fR
506 .ad
507 .RS 29n
508 Enable \fBautoprint\fR mode. When \fBautoprint\fR is enabled, \fBelfedit\fR
509 prints the modified values that result when the ELF file is modified. This
510 output is shown in the current output style, which can be changed using the
511 \fB-o\fR option. The default output style is the style used by the
512 \fBelfdump\fR(1) utility. \fBautoprint\fR mode is the default when
513 \fBelfedit\fR is used interactively (when \fBstdin\fR and \fBstdout\fR are
514 terminals). Therefore, the \fB-a\fR option only has meaning when \fBelfedit\fR
515 is used in non-interactive contexts. To disable \fBautoprint\fR in an
516 interactive session, use the \fBelfedit\fR command:
517 .sp
518 .in +2
519 .nf
520 > set a off
600 form otherwise. No titles, headers, or other supplemental output is shown.
601 .RE
602
603 .RE
604
605 .sp
606 .ne 2
607 .na
608 \fB\fB-r\fR\fR
609 .ad
610 .RS 29n
611 Read-only mode. The input file is opened for read-only access, and the results
612 of the edit session are not saved. \fBelfedit\fR does not allow the
613 \fIoutfile\fR argument when \fB-r\fR is specified. Read-only mode is highly
614 recommended when there is no intention to modify the file. In addition to
615 providing extra protection against accidental modification, it allows for the
616 examination of files for which the user does not have write permission.
617 .RE
618
619 .SH OPERANDS
620 The following operands are supported:
621 .sp
622 .ne 2
623 .na
624 \fB\fIinfile\fR\fR
625 .ad
626 .RS 11n
627 Input file containing an ELF object to process.
628 .sp
629 This can be an executable (\fBET_EXEC\fR), shared object (\fBET_DYN\fR), or
630 relocatable object file, (\fBET_REL\fR). Archives are not directly supported.
631 To edit an object in an archive, you must extract the object, edit the copy,
632 and then insert it back into the archive.
633 .sp
634 If no \fIinfile\fR is present, \fBelfedit\fR runs in a limited mode that only
635 allows executing commands from the \fBsys:\fR module. This mode is primarily to
636 allow access to the command documentation available from the help
637 (\fBsys:help\fR) command.
638 .sp
639 If \fIinfile\fR is present, and no \fIoutfile\fR is given, \fBelfedit\fR edits
642 \fBelfedit\fR not be used in this mode, and that an output file be specified.
643 Once the resulting file has been tested and validated, it can be moved into the
644 place of the original file.
645 .sp
646 The \fB-r\fR option can be used to open \fIinfile\fR for read-only access. This
647 can be useful for examining an existing file that you do not wish to modify.
648 .RE
649
650 .sp
651 .ne 2
652 .na
653 \fB\fIoutfile\fR\fR
654 .ad
655 .RS 11n
656 Output file. If both \fIinfile\fR and \fIoutfile\fR are present, \fIinfile\fR
657 is opened for read-only access, and the modified object contents are written to
658 \fIoutfile\fR.
659 .RE
660
661 .SH USAGE
662 When supported by the system, \fBelfedit\fR runs as a 64-bit application,
663 capable of processing files greater than or equal to 2 Gbytes (2^31 bytes).
664 .sp
665 .LP
666 At startup, \fBelfedit\fR uses \fBlibelf\fR to open the input file and cache a
667 copy of its contents in memory for editing. It can then execute one or more
668 commands. A session finishes by optionally writing the modified object to the
669 output file, and then exiting.
670 .sp
671 .LP
672 If no \fIinfile\fR is present, \fBelfedit\fR runs in a limited mode that only
673 allows executing commands from the \fBsys\fR module. This mode is primarily to
674 allow access to the command documentation available from the help
675 (\fBsys:help\fR) command.
676 .sp
677 .LP
678 If one or more \fB-e\fR options are specified, the commands they supply are
679 executed in the order given. \fBelfedit\fR adds implicit calls to write
680 (\fBsys:write\fR) and quit (\fBsys:qui\fRt) immediately following the given
681 commands, causing the output file to be written and the \fBelfedit\fR process
682 to exit. This form of use is convenient in shell scripts and makefiles.
683 .sp
684 .LP
685 If no \fB-e\fR options are specified, \fBelfedit\fR reads commands from
686 \fBstdin\fR and executes them in the order given. The caller must explicitly
687 issue the write (\fBsys:write\fR) and quit (\fBsys:quit\fR) commands to save
688 their work and exit when running in this mode.
689 .SH EXIT STATUS
690 The following exit values are returned:
691 .sp
692 .ne 2
693 .na
694 \fB\fB0\fR\fR
695 .ad
696 .RS 5n
697 Successful completion.
698 .RE
699
700 .sp
701 .ne 2
702 .na
703 \fB\fB1\fR\fR
704 .ad
705 .RS 5n
706 A fatal error occurred.
707 .RE
708
709 .sp
710 .ne 2
711 .na
712 \fB\fB2\fR\fR
713 .ad
714 .RS 5n
715 Invalid command line options were specified.
716 .RE
717
718 .SH EXAMPLES
719 In the following examples, interactive use of \fBelfedit\fR is shown with the
720 shell prompt (\fB%\fR) and the \fBelfedit\fR prompt (\fB>\fR). Neither of these
721 characters should be entered by the user.
722 .LP
723 \fBExample 1 \fRChanging the Runpath of an Executable
724 .sp
725 .LP
726 The following example presupposes an executable named \fBprog\fR, installed in
727 a bin directory that has an adjacent lib directory for sharable objects. The
728 following command sets the \fBrunpath\fR of that executable to the \fBlib\fR
729 directory:
730
731 .sp
732 .in +2
733 .nf
734 elfedit -e 'dyn:runpath $ORIGIN/../lib'
735 .fi
736 .in -2
737 .sp
738
830 and protecting against accidental damage to an important system executable. The
831 \fBnum\fR output style is used in order to obtain only the desired value,
832 without any extraneous text.
833
834 .sp
835 .LP
836 Similarly, the following extracts the symbol type of the symbol \fBunlink\fR
837 from the C runtime library:
838
839 .sp
840 .in +2
841 .nf
842 % TYPE=`elfedit -r -osimple -e 'sym:st_type unlink' /lib/libc.so`
843 % echo $TYPE
844 STT_FUNC
845 .fi
846 .in -2
847 .sp
848
849 .SH ENVIRONMENT VARIABLES
850 .ne 2
851 .na
852 \fB\fBELFEDIT_PATH\fR\fR
853 .ad
854 .RS 16n
855 Alters the default module search path. Module search paths are discussed in the
856 \fBModule Search Path\fR section of this manual page.
857 .RE
858
859 .sp
860 .ne 2
861 .na
862 \fB\fBLD_NOEXEC_64\fR\fR
863 .ad
864 .RS 16n
865 Suppresses the automatic execution of the 64-bit \fBelfedit\fR. By default, the
866 64-bit version of \fBelfedit\fR runs if the system is 64-bit capable.
867 .RE
868
869 .sp
870 .ne 2
871 .na
872 \fB\fBPAGER\fR\fR
873 .ad
874 .RS 16n
875 Interactively delivers output from \fBelfedit\fR to the screen. If not set,
876 \fBmore\fR is used. See \fBmore\fR(1).
877 .RE
878
879 .SH FILES
880 .ne 2
881 .na
882 \fB\fB/usr/lib/elfedit\fR\fR
883 .ad
884 .RS 20n
885 Default directory for \fBelfedit\fR modules that are loaded on demand to supply
886 editing commands.
887 .RE
888
889 .sp
890 .ne 2
891 .na
892 \fB\fB~/.teclarc\fR\fR
893 .ad
894 .RS 20n
895 Personal \fBtecla\fR customization file for command line editing. See
896 \fBtecla\fR(5).
897 .RE
898
899 .SH ATTRIBUTES
900 See \fBattributes\fR(5) for descriptions of the following attributes:
901 .sp
902
903 .sp
904 .TS
905 box;
906 c | c
907 l | l .
908 ATTRIBUTE TYPE ATTRIBUTE VALUE
909 _
910 Interface Stability Committed
911 .TE
912
913 .SH SEE ALSO
914 \fBdump\fR(1), \fBelfdump\fR(1), \fBld.so.1\fR(1), \fBmore\fR(1), \fBnm\fR(1),
915 \fBpvs\fR(1), \fBelf\fR(3ELF), \fBlibelf\fR(3LIB), \fBtecla\fR(5),
916 \fBattributes\fR(5)
917 .sp
918 .LP
919 \fILinker and Libraries Guide\fR
920 .SH WARNINGS
921 \fBelfedit\fR is designed to be a tool for testing and development of the ELF
922 system. It offers the ability to examine and change nearly every piece of ELF
923 metadata in the object. It quietly allows edits that can produce an invalid or
924 unusable ELF file. The user is expected to have knowledge of the ELF format and
925 of the rules and conventions that govern them. The \fILinker and Libraries
926 Guide\fR can be helpful when using \fBelfedit\fR.
927 .sp
928 .LP
929 \fBelfedit\fR allows the user to alter the ELF metadata in an object, but
930 cannot understand or alter the code of the actual program. Setting ELF
931 attributes such as types, sizes, alignments, and so forth in a manner that does
932 not agree with the actual contents of the file is therefore likely to yield a
933 broken and unusable output object. Such changes might be useful for testing of
934 linker components, but should be avoided otherwise.
935 .sp
936 .LP
937 Higher level operations, such as the use of the \fBdyn:runpath\fR command to
938 change the \fBrunpath\fR of an object, are safe, and can be carried out without
939 the sort of risk detailed in this section.
940 .SH NOTES
941 Not every ELF operation supported by \fBelfedit\fR can be successfully carried
942 out on every ELF object. \fBelfedit\fR is constrained by the existing sections
943 found in the file.
944 .sp
945 .LP
946 One area of particular interest is that \fBelfedit\fR might not be able to
947 modify the \fBrunpath\fR of a given object. To modify a \fBrunpath\fR, the
948 following must be true:
949 .RS +4
950 .TP
951 .ie t \(bu
952 .el o
953 The desired string must already exist in the dynamic string table, or there
954 must be enough reserved space within this section for the new string to be
955 added. If your object has a string table reservation area, the value of the
956 \fB\&.dynamic DT_SUNW_STRPAD\fR element indicates the size of the area. The
957 following \fBelfedit\fR command can be used to check this:
958 .sp
959 .in +2
960 .nf
|