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