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
44 module. This command is run when the user specifies only a module name. Most
45 \fBelfedit\fR modules supply a command named dump, which produces the same
46 information displayed by the \fBelfdump\fR utility for the part of the ELF file
47 covered by the module. It is common for a module to specify dump as its default
48 command.
49 .sp
50 .LP
51 The syntax used to execute an \fBelfedit\fR command is intended to be familiar
52 to anyone who uses UNIX command line utilities. It consists of white space
53 delimited tokens. The first token is the command name. Options, which are
54 arguments that start with the hyphen (\fB-\fR) character follow the command.
55 Plain arguments (operands) follow the options. There can be \fB0\fR or more
56 options and operands for a given command, but if they are present, options
57 always precede plain arguments. The special option, \fB--\fR, (two hyphens) can
58 be used to delimit the end of the options. When it is encountered, any
59 remaining arguments are considered to be plain arguments even if they start
60 with a \fB-\fR.
61 .sp
62 .LP
63 The interpretation of the characters in an \fBelfedit\fR token depends on the
64 style of quoting used:
65 .sp
66 .ne 2
67 .na
68 \fBUnquoted\fR
69 .ad
70 .RS 17n
71 Outside of single (') or double (") quotes, backslash (\) acts as an escape
72 character. When a backslash character is seen, \fBelfedit\fR ignores it, and
73 treats the character following it literally (even if the following character is
74 itself a backslash). This feature can be used to insert a white space character
75 into a string argument to a command without having it split the string into two
76 separate tokens. Similarly, it can be used to insert a quote or backslash as a
77 literal character.
78 .RE
79
80 .sp
81 .ne 2
82 .na
83 \fBSingle Quotes\fR
84 .ad
85 .RS 17n
86 Within single quotes ('), white space characters do not delimit tokens, and are
87 interpreted as literal characters within the token. Double quote (") and
88 backslash (\) characters are interpreted as literal characters, and have no
89 special meaning.
90 .RE
91
92 .sp
93 .ne 2
94 .na
95 \fBDouble Quotes\fR
96 .ad
97 .RS 17n
98 Within double quotes ("), white space characters do not delimit tokens. Single
99 quote characters are interpreted literally and do not have a quoting function.
100 Backslash (\) is an escape character which operates similarly to the way it is
101 used in the C programming language within a string literal:
102 .sp
103 .ne 2
104 .na
105 \fB\ea\fR
106 .ad
107 .RS 8n
108 alert (bell)
109 .RE
110
111 .sp
112 .ne 2
113 .na
114 \fB\\b\fR
115 .ad
116 .RS 8n
117 backspace
118 .RE
119
120 .sp
121 .ne 2
122 .na
123 \fB\ef\fR
124 .ad
125 .RS 8n
126 form feed
127 .RE
128
129 .sp
130 .ne 2
131 .na
132 \fB\en\fR
133 .ad
134 .RS 8n
135 newline
136 .RE
137
138 .sp
139 .ne 2
140 .na
141 \fB\er\fR
142 .ad
143 .RS 8n
144 return
145 .RE
146
147 .sp
148 .ne 2
149 .na
150 \fB\et\fR
151 .ad
152 .RS 8n
153 horizontal tab
154 .RE
155
156 .sp
157 .ne 2
158 .na
159 \fB\\v\fR
160 .ad
161 .RS 8n
162 vertical tab
163 .RE
164
165 .sp
166 .ne 2
167 .na
168 \fB\\\fR
169 .ad
170 .RS 8n
171 backslash
172 .RE
173
174 .sp
175 .ne 2
176 .na
177 \fB\'\fR
178 .ad
179 .RS 8n
180 single quote
181 .RE
182
183 .sp
184 .ne 2
185 .na
186 \fB\e"\fR
187 .ad
188 .RS 8n
189 double quote
190 .RE
191
192 .sp
193 .ne 2
194 .na
195 \fB\\ooo\fR
196 .ad
197 .RS 8n
198 An octal constant, where ooo is one to three octal digits (0...7)
199 .RE
200
201 Any other character following a backslash is an error.
202 .RE
203
204 .sp
205 .LP
206 The core commands belong to an internal module named \fBsys\fR. All other
207 modules are packaged as dynamically loadable sharable objects. \fBelfedit\fR
208 loads modules on demand, when a command that requires it is executed, or as the
209 result of executing the \fBsys:load\fR command. Due to its special built in
210 status, and because its commands are used heavily, \fBelfedit\fR allows you to
211 specify commands from the \fBsys\fR module without including the \fBsys:\fR
212 prefix, for example, \fBload\fR rather than \fBsys:load\fR. To access a command
213 from any other module, you must specify the full \fImodule\fR\fB:\fR\fIcmd\fR
214 form.
215 .sp
216 .LP
217 \fBelfedit\fR is delivered with the following standard modules:
218 .sp
219 .ne 2
220 .na
221 \fB\fBcap\fR\fR
222 .ad
223 .RS 11n
224 Capabilities Section
225 .RE
226
227 .sp
228 .ne 2
229 .na
230 \fB\fBdyn\fR\fR
231 .ad
232 .RS 11n
233 Dynamic Section
234 .RE
235
236 .sp
237 .ne 2
238 .na
239 \fB\fBehdr\fR\fR
240 .ad
241 .RS 11n
242 ELF Header
243 .RE
244
245 .sp
246 .ne 2
247 .na
248 \fB\fBphdr\fR\fR
249 .ad
250 .RS 11n
251 Program Header Array
252 .RE
253
254 .sp
255 .ne 2
256 .na
257 \fB\fBshdr\fR\fR
258 .ad
259 .RS 11n
260 Section Header Array
261 .RE
262
263 .sp
264 .ne 2
265 .na
266 \fB\fBstr\fR\fR
267 .ad
268 .RS 11n
269 String Table Section
270 .RE
271
272 .sp
273 .ne 2
274 .na
275 \fB\fBsym\fR\fR
276 .ad
277 .RS 11n
278 Symbol Table Section
279 .RE
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
320 .el o
321 Module search path
322 .RE
323 .RS +4
324 .TP
325 .ie t \(bu
326 .el o
327 Modules loaded
328 .RE
329 .sp
330 .LP
331 Included with every \fBelfedit\fR module is extensive online documentation for
332 every command, in a format similar to UNIX manual pages. The \fBhelp\fR
333 (\fBsys:help\fR) command is used to display this information. To learn more
334 about \fBelfedit\fR, start \fBelfedit\fR and use the help command without
335 arguments:
336 .sp
337 .in +2
338 .nf
339 % elfedit
340 > help
341 .fi
342 .in -2
343 .sp
344
345 .sp
346 .LP
347 \fBelfedit\fR displays a welcome message with more information about
348 \fBelfedit\fR, and on how to use the help system.
349 .sp
350 .LP
351 To obtain summary information for a module:
352 .sp
353 .in +2
354 .nf
355 > help module
356 .fi
357 .in -2
358 .sp
359
360 .sp
361 .LP
362 To obtain the full documentation for a specific command provided by a module:
363 .sp
364 .in +2
365 .nf
366 > help module:command
367 .fi
368 .in -2
369 .sp
370
371 .sp
372 .LP
373 Using the \fBdyn\fR module and \fBdyn:runpath\fR commands as examples:
374 .sp
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
415 .ad
416 .RS 6n
417 Expands to the 64-bit ISA. This is the same thing as \fB%i\fR for 64-bit
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
459 .nf
460 %r/usr/lib/elfedit/%I
461 .fi
462 .in -2
463 .sp
464
465 .sp
466 .LP
467 Expanding the tokens, this is:
468 .sp
469 .ne 2
470 .na
471 \fB\fB/usr/lib/elfedit\fR\fR
472 .ad
473 .RS 28n
474 32-bit \fBelfedit\fR
475 .RE
476
477 .sp
478 .ne 2
479 .na
480 \fB\fB/usr/lib/elfedit/sparcv9\fR\fR
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
521 .fi
522 .in -2
523 .sp
524
525 .RE
526
527 .sp
528 .ne 2
529 .na
530 \fB\fB-d\fR\fR
531 .ad
532 .RS 29n
533 If set, this option causes \fBelfedit\fR to issue informational messages
534 describing its internal operations and details of the ELF object being
535 processed. This can be useful when a deep understanding of the operation being
536 carried out is desired.
537 .RE
538
539 .sp
540 .ne 2
541 .na
542 \fB\fB-e\fR \fIcmd\fR\fR
543 .ad
544 .RS 29n
545 Specifies an edit command. Multiple \fB-e\fR options can be specified. If edit
546 commands are present on the command line, \fBelfedit\fR operates in batch mode.
547 After opening the file, \fBelfedit\fR executes each command in the order given,
548 after which the modified file is saved and \fBelfedit\fR exits. Batch mode is
549 useful for performing simple operations from shell scripts and makefiles.
550 .RE
551
552 .sp
553 .ne 2
554 .na
555 \fB\fB-L\fR \fIpath\fR\fR
556 .ad
557 .RS 29n
558 Sets default path for locating \fBelfedit\fR modules. Modules are described in
559 \fBModule Search Path\fR section of this manual page..
560 .RE
561
562 .sp
563 .ne 2
564 .na
565 \fB\fB-o\fR \fBdefault\fR | \fBsimple\fR | \fBnum\fR\fR
566 .ad
567 .RS 29n
568 The style used to display ELF data. This option establishes the current style
569 for the session. It can be changed from within the \fBelfedit\fR session by
570 using the set (\fBsys:set\fR) command, or by providing \fB-o\fR options to the
571 individual commands executed within the session.
572 .sp
573 .ne 2
574 .na
575 \fB\fBdefault\fR\fR
576 .ad
577 .RS 11n
578 The default style is to display output in a format intended for human viewing.
579 This style is similar to that used by the \fBelfdump\fR utility.
580 .RE
581
582 .sp
583 .ne 2
584 .na
585 \fB\fBnum\fR\fR
586 .ad
587 .RS 11n
588 Integer values are always shown in integer form. Strings are shown as the
589 integer offset into the containing string table.
590 .RE
591
592 .sp
593 .ne 2
594 .na
595 \fB\fBsimple\fR\fR
596 .ad
597 .RS 11n
598 When displaying strings from within the ELF file, only the string is displayed.
599 Integer values are displayed as symbolic constants if possible, and in integer
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
640 the file in place, and writes the results into the same file, causing the
641 original file contents to be overwritten. It is usually recommended that
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
739 .sp
740 .LP
741 The use of single quotes with the argument to the \fB-e\fR option is necessary
742 to ensure that the shell passes the entire command as a single argument to
743 \fBelfedit\fR.
744
745 .sp
746 .LP
747 Alternatively, the same operation can be done using \fBelfedit\fR in its
748 non-batch mode:
749
750 .sp
751 .in +2
752 .nf
753 % elfedit prog
754 > dyn:runpath $ORIGIN/../lib
755 index tag value
756 [30] RUNPATH 0x3e6 $ORIGIN/../lib
757 > write
758 > quit
759 .fi
760 .in -2
761 .sp
762
763 .sp
764 .LP
765 The addition or modification of elements such as \fBrunpath\fR or needed
766 entries might only be achievable when \fBpadding\fR exists within the objects.
767 See \fBNotes\fR.
768
769 .LP
770 \fBExample 2 \fRRemoving a Hardware Capability Bit
771 .sp
772 .LP
773 Objects that require optional hardware support to run are built with a
774 capability section that contains a mask of bits specifying which capabilities
775 they need. The runtime linker (\fBld.so.1\fR) checks this mask against the
776 attributes of the running system to determine whether a given object is able to
777 be run by the current system. Programs that require abilities not available on
778 the system are prevented from running.
779
780 .sp
781 .LP
782 This check prevents a naive program that does not explicitly check for the
783 hardware support it requires from crashing in a confusing manner. However, it
784 can be inconvenient for a program that is written to explicitly check the
785 system capabilities at runtime. Such a program might have optimized code to use
786 when the hardware supports it while providing a generic fallback version that
787 can be run, albeit more slowly, otherwise. In this case, the hardware
788 compatibility mask prevents such a program from running on the older hardware.
789 In such a case, removing the relevant bit from the mask allows the program to
790 run.
791
792 .sp
793 .LP
794 The following example removes the \fBAV_386_SSE\fR3 hardware capability from an
795 x86 binary that uses the SSE3 CPU extension. This transfers responsibility for
796 validating the ability to use SSE3 from the runtime linker to the program
797 itself:
798
799 .sp
800 .in +2
801 .nf
802 elfedit -e 'cap:hw1 -and -cmp sse3' prog
803 .fi
804 .in -2
805 .sp
806
807 .LP
808 \fBExample 3 \fRReading Information From an Object
809 .sp
810 .LP
811 \fBelfedit\fR can be used to extract specific targeted information from an
812 object. The following shell command reads the number of section headers
813 contained in the file \fB/usr/bin/ls\fR:
814
815 .sp
816 .in +2
817 .nf
818 % SHNUM=`elfedit -r -onum -e 'ehdr:e_shnum' /usr/bin/ls`
819 % echo $SHNUM
820 29
821 .fi
822 .in -2
823 .sp
824
825 .sp
826 .LP
827 You might get a different value, depending on the version of Solaris and type
828 of machine that you are using. The \fB-r\fR option causes the file to be opened
829 read-only, allowing a user with ordinary access permissions to open the file,
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
961 % elfedit -r -e 'dyn:tag DT_SUNW_STRPAD' file
962 .fi
963 .in -2
964 .sp
965
966 .RE
967 .RS +4
968 .TP
969 .ie t \(bu
970 .el o
971 The dynamic section must already have a \fBrunpath\fR element, or there must be
972 an unused dynamic slot available where one can be inserted. To test for the
973 presence of an existing \fBrunpath\fR:
974 .sp
975 .in +2
976 .nf
977 % elfedit -r -e 'dyn:runpath' file
978 .fi
979 .in -2
980 .sp
981
982 A dynamic section uses an element of type \fBDT_NULL\fR to terminate the array
983 found in that section. The final \fBDT_NULL\fR cannot be changed, but if there
984 are more than one of these, \fBelfedit\fR can convert one of them into a
985 \fBrunpath\fR element. To test for extra dynamic slots:
986 .sp
987 .in +2
988 .nf
989 % elfedit -r -e 'dyn:tag DT_NULL' file
990 .fi
991 .in -2
992 .sp
993
994 .RE
995 .sp
996 .LP
997 Older objects do not have the extra space necessary to complete such
998 operations. The space necessary to do so was introduced in the Solaris Express
999 Community Edition release.
1000 .sp
1001 .LP
1002 When an operation fails, the detailed information printed using the \fB-d\fR
1003 (debug) option can be very helpful in uncovering the reason why.
1004 .sp
1005 .LP
1006 \fBelfedit\fR modules follow a convention by which commands that directly
1007 manipulate a field in an ELF structure have the same name as the field, while
1008 commands that implement higher level concepts do not. For instance, the command
1009 to manipulate the \fBe_flags\fR field in the ELF header is named
1010 \fBehdr:e_flags\fR. Therefore, you generally find the command to modify ELF
1011 fields by identifying the module and looking for a command with the name of the
1012 field.