Print this page
12745 man page typos
Split |
Close |
Expand all |
Collapse all |
--- old/usr/src/man/man1/elfedit.1
+++ new/usr/src/man/man1/elfedit.1
1 1 '\" te
2 2 .\" Copyright (c) 2008, Sun Microsystems Inc. All
3 3 .\" Rights Reserved.
4 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 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 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"
7 +.TH ELFEDIT 1 "May 17, 2020"
8 8 .SH NAME
9 9 elfedit \- examine or edit ELF files
10 10 .SH SYNOPSIS
11 -.LP
12 11 .nf
13 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]
14 13 [\fIinfile\fR] [\fIoutfile\fR]
15 14 .fi
16 15
17 16 .SH DESCRIPTION
18 -.sp
19 -.LP
20 17 \fBelfedit\fR is a tool for examining or modifying the contents of an existing
21 18 ELF object. Specifically, \fBelfedit\fR is used to modify the ELF metadata
22 19 contained in the object. Access is provided to most of the ELF data contained
23 20 in an object, including the ELF header, section header table, program header
24 21 table, dynamic section, hardware and software capabilities, string tables, and
25 22 symbol tables.
26 23 .SS "Syntax"
27 -.sp
28 -.LP
29 24 \fBelfedit\fR processes commands from the command line (\fB-e\fR option) or
30 25 from standard input. If standard input is a terminal, \fBelfedit\fR provides
31 26 terminal editing capabilities, as well as extensive command completion. ELF
32 27 uses many standard symbolic names for special integer values and bit masks.
33 28 \fBelfedit\fR is aware of most possible completions for such names. You can
34 29 press TAB at any point while entering an \fBelfedit\fR command to cause
35 30 \fBelfedit\fR to display a usage message and any known completions for the text
36 31 at the current cursor.
37 32 .sp
38 33 .LP
39 34 \fBelfedit\fR functionality is organized in the form of modules. Each module
40 35 delivers a set of commands, focused on related functionality. A command is
41 36 specified by combining the module and command names with a colon (\fB:\fR)
42 37 delimiter, with no intervening white space. For example, \fBdyn:runpath\fR
43 38 refers to the \fBrunpath\fR command provided by the \fBdyn\fR module. Module
44 39 names must be unique. The command names within a given module are unique within
45 40 that module, but the same command names can be used in more than one module.
46 41 .sp
47 42 .LP
48 43 Some modules designate one of their commands to be the default command for that
49 44 module. This command is run when the user specifies only a module name. Most
50 45 \fBelfedit\fR modules supply a command named dump, which produces the same
51 46 information displayed by the \fBelfdump\fR utility for the part of the ELF file
52 47 covered by the module. It is common for a module to specify dump as its default
53 48 command.
54 49 .sp
55 50 .LP
56 51 The syntax used to execute an \fBelfedit\fR command is intended to be familiar
57 52 to anyone who uses UNIX command line utilities. It consists of white space
58 53 delimited tokens. The first token is the command name. Options, which are
59 54 arguments that start with the hyphen (\fB-\fR) character follow the command.
60 55 Plain arguments (operands) follow the options. There can be \fB0\fR or more
61 56 options and operands for a given command, but if they are present, options
62 57 always precede plain arguments. The special option, \fB--\fR, (two hyphens) can
63 58 be used to delimit the end of the options. When it is encountered, any
64 59 remaining arguments are considered to be plain arguments even if they start
65 60 with a \fB-\fR.
66 61 .sp
67 62 .LP
68 63 The interpretation of the characters in an \fBelfedit\fR token depends on the
69 64 style of quoting used:
70 65 .sp
71 66 .ne 2
72 67 .na
73 68 \fBUnquoted\fR
74 69 .ad
75 70 .RS 17n
76 71 Outside of single (') or double (") quotes, backslash (\) acts as an escape
77 72 character. When a backslash character is seen, \fBelfedit\fR ignores it, and
78 73 treats the character following it literally (even if the following character is
79 74 itself a backslash). This feature can be used to insert a white space character
80 75 into a string argument to a command without having it split the string into two
81 76 separate tokens. Similarly, it can be used to insert a quote or backslash as a
82 77 literal character.
83 78 .RE
84 79
85 80 .sp
86 81 .ne 2
87 82 .na
88 83 \fBSingle Quotes\fR
89 84 .ad
90 85 .RS 17n
91 86 Within single quotes ('), white space characters do not delimit tokens, and are
92 87 interpreted as literal characters within the token. Double quote (") and
93 88 backslash (\) characters are interpreted as literal characters, and have no
94 89 special meaning.
95 90 .RE
96 91
97 92 .sp
98 93 .ne 2
99 94 .na
100 95 \fBDouble Quotes\fR
101 96 .ad
102 97 .RS 17n
103 98 Within double quotes ("), white space characters do not delimit tokens. Single
104 99 quote characters are interpreted literally and do not have a quoting function.
105 100 Backslash (\) is an escape character which operates similarly to the way it is
106 101 used in the C programming language within a string literal:
107 102 .sp
108 103 .ne 2
109 104 .na
110 105 \fB\ea\fR
111 106 .ad
112 107 .RS 8n
113 108 alert (bell)
114 109 .RE
115 110
116 111 .sp
117 112 .ne 2
118 113 .na
119 114 \fB\\b\fR
120 115 .ad
121 116 .RS 8n
122 117 backspace
123 118 .RE
124 119
125 120 .sp
126 121 .ne 2
127 122 .na
128 123 \fB\ef\fR
129 124 .ad
130 125 .RS 8n
131 126 form feed
132 127 .RE
133 128
134 129 .sp
135 130 .ne 2
136 131 .na
137 132 \fB\en\fR
138 133 .ad
139 134 .RS 8n
140 135 newline
141 136 .RE
142 137
143 138 .sp
144 139 .ne 2
145 140 .na
146 141 \fB\er\fR
147 142 .ad
148 143 .RS 8n
149 144 return
150 145 .RE
151 146
152 147 .sp
153 148 .ne 2
154 149 .na
155 150 \fB\et\fR
156 151 .ad
157 152 .RS 8n
158 153 horizontal tab
159 154 .RE
160 155
161 156 .sp
162 157 .ne 2
163 158 .na
164 159 \fB\\v\fR
165 160 .ad
166 161 .RS 8n
167 162 vertical tab
168 163 .RE
169 164
170 165 .sp
171 166 .ne 2
172 167 .na
173 168 \fB\\\fR
174 169 .ad
175 170 .RS 8n
176 171 backslash
177 172 .RE
178 173
179 174 .sp
180 175 .ne 2
181 176 .na
182 177 \fB\'\fR
183 178 .ad
184 179 .RS 8n
185 180 single quote
186 181 .RE
187 182
188 183 .sp
189 184 .ne 2
190 185 .na
191 186 \fB\e"\fR
192 187 .ad
193 188 .RS 8n
194 189 double quote
195 190 .RE
196 191
197 192 .sp
198 193 .ne 2
199 194 .na
200 195 \fB\\ooo\fR
201 196 .ad
202 197 .RS 8n
203 198 An octal constant, where ooo is one to three octal digits (0...7)
204 199 .RE
205 200
206 201 Any other character following a backslash is an error.
207 202 .RE
208 203
209 204 .sp
210 205 .LP
211 206 The core commands belong to an internal module named \fBsys\fR. All other
212 207 modules are packaged as dynamically loadable sharable objects. \fBelfedit\fR
213 208 loads modules on demand, when a command that requires it is executed, or as the
214 209 result of executing the \fBsys:load\fR command. Due to its special built in
215 210 status, and because its commands are used heavily, \fBelfedit\fR allows you to
216 211 specify commands from the \fBsys\fR module without including the \fBsys:\fR
217 212 prefix, for example, \fBload\fR rather than \fBsys:load\fR. To access a command
218 213 from any other module, you must specify the full \fImodule\fR\fB:\fR\fIcmd\fR
219 214 form.
220 215 .sp
221 216 .LP
222 217 \fBelfedit\fR is delivered with the following standard modules:
223 218 .sp
224 219 .ne 2
225 220 .na
226 221 \fB\fBcap\fR\fR
227 222 .ad
228 223 .RS 11n
229 224 Capabilities Section
230 225 .RE
231 226
232 227 .sp
233 228 .ne 2
234 229 .na
235 230 \fB\fBdyn\fR\fR
236 231 .ad
237 232 .RS 11n
238 233 Dynamic Section
239 234 .RE
240 235
241 236 .sp
242 237 .ne 2
243 238 .na
244 239 \fB\fBehdr\fR\fR
245 240 .ad
246 241 .RS 11n
247 242 ELF Header
248 243 .RE
249 244
250 245 .sp
251 246 .ne 2
252 247 .na
253 248 \fB\fBphdr\fR\fR
254 249 .ad
255 250 .RS 11n
256 251 Program Header Array
257 252 .RE
258 253
259 254 .sp
260 255 .ne 2
261 256 .na
262 257 \fB\fBshdr\fR\fR
263 258 .ad
264 259 .RS 11n
265 260 Section Header Array
266 261 .RE
267 262
268 263 .sp
269 264 .ne 2
270 265 .na
271 266 \fB\fBstr\fR\fR
272 267 .ad
273 268 .RS 11n
274 269 String Table Section
275 270 .RE
276 271
277 272 .sp
278 273 .ne 2
279 274 .na
280 275 \fB\fBsym\fR\fR
281 276 .ad
282 277 .RS 11n
283 278 Symbol Table Section
284 279 .RE
285 280
286 281 .sp
287 282 .ne 2
288 283 .na
289 284 \fB\fBsyminfo\fR\fR
290 285 .ad
291 286 .RS 11n
292 287 \fBSyminfo\fR Section
293 288 .RE
294 289
↓ open down ↓ |
256 lines elided |
↑ open up ↑ |
295 290 .sp
296 291 .ne 2
297 292 .na
298 293 \fB\fBsys\fR\fR
299 294 .ad
300 295 .RS 11n
301 296 Core built in \fBelfedit\fR commands
302 297 .RE
303 298
304 299 .SS "Status And Command Documentation"
305 -.sp
306 -.LP
307 300 Status And Command Documentation
308 301 .sp
309 302 .LP
310 303 The status (\fBsys:status\fR) command displays information about the current
311 304 \fBelfedit\fR session:
312 305 .RS +4
313 306 .TP
314 307 .ie t \(bu
315 308 .el o
316 309 Input and output files
317 310 .RE
318 311 .RS +4
319 312 .TP
320 313 .ie t \(bu
321 314 .el o
322 315 Option setting
323 316 .RE
324 317 .RS +4
325 318 .TP
326 319 .ie t \(bu
327 320 .el o
328 321 Module search path
329 322 .RE
330 323 .RS +4
331 324 .TP
332 325 .ie t \(bu
333 326 .el o
334 327 Modules loaded
335 328 .RE
336 329 .sp
337 330 .LP
338 331 Included with every \fBelfedit\fR module is extensive online documentation for
339 332 every command, in a format similar to UNIX manual pages. The \fBhelp\fR
340 333 (\fBsys:help\fR) command is used to display this information. To learn more
341 334 about \fBelfedit\fR, start \fBelfedit\fR and use the help command without
342 335 arguments:
343 336 .sp
344 337 .in +2
345 338 .nf
346 339 % elfedit
347 340 > help
348 341 .fi
349 342 .in -2
350 343 .sp
351 344
352 345 .sp
353 346 .LP
354 347 \fBelfedit\fR displays a welcome message with more information about
355 348 \fBelfedit\fR, and on how to use the help system.
356 349 .sp
357 350 .LP
358 351 To obtain summary information for a module:
359 352 .sp
360 353 .in +2
361 354 .nf
362 355 > help module
363 356 .fi
364 357 .in -2
365 358 .sp
366 359
367 360 .sp
368 361 .LP
369 362 To obtain the full documentation for a specific command provided by a module:
370 363 .sp
371 364 .in +2
372 365 .nf
373 366 > help module:command
374 367 .fi
375 368 .in -2
376 369 .sp
377 370
378 371 .sp
379 372 .LP
380 373 Using the \fBdyn\fR module and \fBdyn:runpath\fR commands as examples:
381 374 .sp
382 375 .in +2
383 376 .nf
384 377 > help dyn
385 378 > help dyn:runpath
386 379 .fi
387 380 .in -2
388 381 .sp
389 382
390 383 .sp
391 384 .LP
↓ open down ↓ |
75 lines elided |
↑ open up ↑ |
392 385 help (\fBsys:help\fR) can be used to obtain help on itself:
393 386 .sp
394 387 .in +2
395 388 .nf
396 389 > help help
397 390 .fi
398 391 .in -2
399 392 .sp
400 393
401 394 .SS "Module Search Path"
402 -.sp
403 -.LP
404 395 \fBelfedit\fR modules are implemented as sharable objects which are loaded on
405 396 demand. When a module is required, \fBelfedit\fR searches a module path in
406 397 order to locate the sharable object that implements the module. The path is a
407 398 sequence of directory names delimited by colon (\fB:\fR) characters. In
408 399 addition to normal characters, the path can also contain any of the following
409 400 tokens:
410 401 .sp
411 402 .ne 2
412 403 .na
413 404 \fB\fB%i\fR\fR
414 405 .ad
415 406 .RS 6n
416 407 Expands to the current instruction set architecture (ISA) name (\fBsparc\fR,
417 408 \fBsparcv9\fR, \fBi386\fR, \fBamd64\fR).
418 409 .RE
419 410
420 411 .sp
421 412 .ne 2
422 413 .na
423 414 \fB\fB%I\fR\fR
424 415 .ad
425 416 .RS 6n
426 417 Expands to the 64-bit ISA. This is the same thing as \fB%i\fR for 64-bit
427 418 versions of \fBelfedit\fR, but expands to the empty string for 32-bit versions.
428 419 .RE
429 420
430 421 .sp
431 422 .ne 2
432 423 .na
433 424 \fB\fB%o\fR\fR
434 425 .ad
435 426 .RS 6n
436 427 Expands to the old value of the path being modified. This is useful for
↓ open down ↓ |
23 lines elided |
↑ open up ↑ |
437 428 appending or prepending directories to the default path.
438 429 .RE
439 430
440 431 .sp
441 432 .ne 2
442 433 .na
443 434 \fB\fB%r\fR\fR
444 435 .ad
445 436 .RS 6n
446 437 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
438 +\fBelfedit\fR is installed as \fBusr/bin/elfedit\fR within the tree. On a
448 439 standard system, this is simply the standard system root directory (\fB/\fR).
449 440 On a development system, where the copy of \fBelfedit\fR can be installed
450 441 elsewhere, the use of \fB%r\fR can be used to ensure that the matching set of
451 442 modules are used.
452 443 .RE
453 444
454 445 .sp
455 446 .ne 2
456 447 .na
457 448 \fB\fB%%\fR\fR
458 449 .ad
459 450 .RS 6n
460 451 Expands to a single \fB%\fR character
461 452 .RE
462 453
463 454 .sp
464 455 .LP
465 456 The default module search path for \fBelfedit\fR is:
466 457 .sp
467 458 .in +2
468 459 .nf
469 460 %r/usr/lib/elfedit/%I
470 461 .fi
471 462 .in -2
472 463 .sp
473 464
474 465 .sp
475 466 .LP
476 467 Expanding the tokens, this is:
477 468 .sp
478 469 .ne 2
479 470 .na
480 471 \fB\fB/usr/lib/elfedit\fR\fR
481 472 .ad
482 473 .RS 28n
483 474 32-bit \fBelfedit\fR
484 475 .RE
485 476
486 477 .sp
487 478 .ne 2
488 479 .na
489 480 \fB\fB/usr/lib/elfedit/sparcv9\fR\fR
490 481 .ad
491 482 .RS 28n
492 483 64-bit \fBelfedit\fR (\fBsparc\fR)
493 484 .RE
494 485
495 486 .sp
496 487 .ne 2
497 488 .na
498 489 \fB\fB/usr/lib/elfedit/amd64\fR\fR
499 490 .ad
↓ open down ↓ |
42 lines elided |
↑ open up ↑ |
500 491 .RS 28n
501 492 64-bit \fBelfedit\fR (\fBx86\fR)
502 493 .RE
503 494
504 495 .sp
505 496 .LP
506 497 The default search path can be changed by setting the \fBELFEDIT_PATH\fR
507 498 environment variable, or by using the \fB-L\fR command line option. If you
508 499 specify both, the \fB-L\fR option supersedes the environment variable.
509 500 .SH OPTIONS
510 -.sp
511 -.LP
512 501 The following options are supported:
513 502 .sp
514 503 .ne 2
515 504 .na
516 505 \fB\fB-a\fR\fR
517 506 .ad
518 507 .RS 29n
519 508 Enable \fBautoprint\fR mode. When \fBautoprint\fR is enabled, \fBelfedit\fR
520 509 prints the modified values that result when the ELF file is modified. This
521 510 output is shown in the current output style, which can be changed using the
522 511 \fB-o\fR option. The default output style is the style used by the
523 512 \fBelfdump\fR(1) utility. \fBautoprint\fR mode is the default when
524 513 \fBelfedit\fR is used interactively (when \fBstdin\fR and \fBstdout\fR are
525 514 terminals). Therefore, the \fB-a\fR option only has meaning when \fBelfedit\fR
526 515 is used in non-interactive contexts. To disable \fBautoprint\fR in an
527 516 interactive session, use the \fBelfedit\fR command:
528 517 .sp
529 518 .in +2
530 519 .nf
531 520 > set a off
532 521 .fi
533 522 .in -2
534 523 .sp
535 524
536 525 .RE
537 526
538 527 .sp
539 528 .ne 2
540 529 .na
541 530 \fB\fB-d\fR\fR
542 531 .ad
543 532 .RS 29n
544 533 If set, this option causes \fBelfedit\fR to issue informational messages
545 534 describing its internal operations and details of the ELF object being
546 535 processed. This can be useful when a deep understanding of the operation being
547 536 carried out is desired.
548 537 .RE
549 538
550 539 .sp
551 540 .ne 2
552 541 .na
553 542 \fB\fB-e\fR \fIcmd\fR\fR
554 543 .ad
555 544 .RS 29n
556 545 Specifies an edit command. Multiple \fB-e\fR options can be specified. If edit
557 546 commands are present on the command line, \fBelfedit\fR operates in batch mode.
558 547 After opening the file, \fBelfedit\fR executes each command in the order given,
559 548 after which the modified file is saved and \fBelfedit\fR exits. Batch mode is
560 549 useful for performing simple operations from shell scripts and makefiles.
561 550 .RE
562 551
563 552 .sp
564 553 .ne 2
565 554 .na
566 555 \fB\fB-L\fR \fIpath\fR\fR
567 556 .ad
568 557 .RS 29n
569 558 Sets default path for locating \fBelfedit\fR modules. Modules are described in
570 559 \fBModule Search Path\fR section of this manual page..
571 560 .RE
572 561
573 562 .sp
574 563 .ne 2
575 564 .na
576 565 \fB\fB-o\fR \fBdefault\fR | \fBsimple\fR | \fBnum\fR\fR
577 566 .ad
578 567 .RS 29n
579 568 The style used to display ELF data. This option establishes the current style
580 569 for the session. It can be changed from within the \fBelfedit\fR session by
581 570 using the set (\fBsys:set\fR) command, or by providing \fB-o\fR options to the
582 571 individual commands executed within the session.
583 572 .sp
584 573 .ne 2
585 574 .na
586 575 \fB\fBdefault\fR\fR
587 576 .ad
588 577 .RS 11n
589 578 The default style is to display output in a format intended for human viewing.
590 579 This style is similar to that used by the \fBelfdump\fR utility.
591 580 .RE
592 581
593 582 .sp
594 583 .ne 2
595 584 .na
596 585 \fB\fBnum\fR\fR
597 586 .ad
598 587 .RS 11n
599 588 Integer values are always shown in integer form. Strings are shown as the
600 589 integer offset into the containing string table.
601 590 .RE
602 591
603 592 .sp
604 593 .ne 2
605 594 .na
606 595 \fB\fBsimple\fR\fR
607 596 .ad
608 597 .RS 11n
609 598 When displaying strings from within the ELF file, only the string is displayed.
610 599 Integer values are displayed as symbolic constants if possible, and in integer
611 600 form otherwise. No titles, headers, or other supplemental output is shown.
612 601 .RE
613 602
614 603 .RE
615 604
616 605 .sp
617 606 .ne 2
618 607 .na
619 608 \fB\fB-r\fR\fR
620 609 .ad
↓ open down ↓ |
99 lines elided |
↑ open up ↑ |
621 610 .RS 29n
622 611 Read-only mode. The input file is opened for read-only access, and the results
623 612 of the edit session are not saved. \fBelfedit\fR does not allow the
624 613 \fIoutfile\fR argument when \fB-r\fR is specified. Read-only mode is highly
625 614 recommended when there is no intention to modify the file. In addition to
626 615 providing extra protection against accidental modification, it allows for the
627 616 examination of files for which the user does not have write permission.
628 617 .RE
629 618
630 619 .SH OPERANDS
631 -.sp
632 -.LP
633 620 The following operands are supported:
634 621 .sp
635 622 .ne 2
636 623 .na
637 624 \fB\fIinfile\fR\fR
638 625 .ad
639 626 .RS 11n
640 627 Input file containing an ELF object to process.
641 628 .sp
642 629 This can be an executable (\fBET_EXEC\fR), shared object (\fBET_DYN\fR), or
643 630 relocatable object file, (\fBET_REL\fR). Archives are not directly supported.
644 631 To edit an object in an archive, you must extract the object, edit the copy,
645 632 and then insert it back into the archive.
646 633 .sp
647 634 If no \fIinfile\fR is present, \fBelfedit\fR runs in a limited mode that only
648 635 allows executing commands from the \fBsys:\fR module. This mode is primarily to
649 636 allow access to the command documentation available from the help
650 637 (\fBsys:help\fR) command.
651 638 .sp
652 639 If \fIinfile\fR is present, and no \fIoutfile\fR is given, \fBelfedit\fR edits
653 640 the file in place, and writes the results into the same file, causing the
654 641 original file contents to be overwritten. It is usually recommended that
655 642 \fBelfedit\fR not be used in this mode, and that an output file be specified.
656 643 Once the resulting file has been tested and validated, it can be moved into the
657 644 place of the original file.
658 645 .sp
659 646 The \fB-r\fR option can be used to open \fIinfile\fR for read-only access. This
660 647 can be useful for examining an existing file that you do not wish to modify.
661 648 .RE
662 649
663 650 .sp
664 651 .ne 2
↓ open down ↓ |
22 lines elided |
↑ open up ↑ |
665 652 .na
666 653 \fB\fIoutfile\fR\fR
667 654 .ad
668 655 .RS 11n
669 656 Output file. If both \fIinfile\fR and \fIoutfile\fR are present, \fIinfile\fR
670 657 is opened for read-only access, and the modified object contents are written to
671 658 \fIoutfile\fR.
672 659 .RE
673 660
674 661 .SH USAGE
675 -.sp
676 -.LP
677 662 When supported by the system, \fBelfedit\fR runs as a 64-bit application,
678 663 capable of processing files greater than or equal to 2 Gbytes (2^31 bytes).
679 664 .sp
680 665 .LP
681 666 At startup, \fBelfedit\fR uses \fBlibelf\fR to open the input file and cache a
682 667 copy of its contents in memory for editing. It can then execute one or more
683 668 commands. A session finishes by optionally writing the modified object to the
684 669 output file, and then exiting.
685 670 .sp
686 671 .LP
687 672 If no \fIinfile\fR is present, \fBelfedit\fR runs in a limited mode that only
688 673 allows executing commands from the \fBsys\fR module. This mode is primarily to
689 674 allow access to the command documentation available from the help
690 675 (\fBsys:help\fR) command.
691 676 .sp
692 677 .LP
693 678 If one or more \fB-e\fR options are specified, the commands they supply are
694 679 executed in the order given. \fBelfedit\fR adds implicit calls to write
↓ open down ↓ |
8 lines elided |
↑ open up ↑ |
695 680 (\fBsys:write\fR) and quit (\fBsys:qui\fRt) immediately following the given
696 681 commands, causing the output file to be written and the \fBelfedit\fR process
697 682 to exit. This form of use is convenient in shell scripts and makefiles.
698 683 .sp
699 684 .LP
700 685 If no \fB-e\fR options are specified, \fBelfedit\fR reads commands from
701 686 \fBstdin\fR and executes them in the order given. The caller must explicitly
702 687 issue the write (\fBsys:write\fR) and quit (\fBsys:quit\fR) commands to save
703 688 their work and exit when running in this mode.
704 689 .SH EXIT STATUS
705 -.sp
706 -.LP
707 690 The following exit values are returned:
708 691 .sp
709 692 .ne 2
710 693 .na
711 694 \fB\fB0\fR\fR
712 695 .ad
713 696 .RS 5n
714 697 Successful completion.
715 698 .RE
716 699
717 700 .sp
718 701 .ne 2
719 702 .na
720 703 \fB\fB1\fR\fR
721 704 .ad
722 705 .RS 5n
723 706 A fatal error occurred.
724 707 .RE
725 708
↓ open down ↓ |
9 lines elided |
↑ open up ↑ |
726 709 .sp
727 710 .ne 2
728 711 .na
729 712 \fB\fB2\fR\fR
730 713 .ad
731 714 .RS 5n
732 715 Invalid command line options were specified.
733 716 .RE
734 717
735 718 .SH EXAMPLES
736 -.sp
737 -.LP
738 719 In the following examples, interactive use of \fBelfedit\fR is shown with the
739 720 shell prompt (\fB%\fR) and the \fBelfedit\fR prompt (\fB>\fR). Neither of these
740 721 characters should be entered by the user.
741 722 .LP
742 723 \fBExample 1 \fRChanging the Runpath of an Executable
743 724 .sp
744 725 .LP
745 726 The following example presupposes an executable named \fBprog\fR, installed in
746 727 a bin directory that has an adjacent lib directory for sharable objects. The
747 728 following command sets the \fBrunpath\fR of that executable to the \fBlib\fR
748 729 directory:
749 730
750 731 .sp
751 732 .in +2
752 733 .nf
753 734 elfedit -e 'dyn:runpath $ORIGIN/../lib'
754 735 .fi
755 736 .in -2
756 737 .sp
757 738
758 739 .sp
759 740 .LP
760 741 The use of single quotes with the argument to the \fB-e\fR option is necessary
761 742 to ensure that the shell passes the entire command as a single argument to
762 743 \fBelfedit\fR.
763 744
764 745 .sp
765 746 .LP
766 747 Alternatively, the same operation can be done using \fBelfedit\fR in its
767 748 non-batch mode:
768 749
769 750 .sp
770 751 .in +2
771 752 .nf
772 753 % elfedit prog
773 754 > dyn:runpath $ORIGIN/../lib
774 755 index tag value
775 756 [30] RUNPATH 0x3e6 $ORIGIN/../lib
776 757 > write
777 758 > quit
778 759 .fi
779 760 .in -2
780 761 .sp
781 762
782 763 .sp
783 764 .LP
784 765 The addition or modification of elements such as \fBrunpath\fR or needed
785 766 entries might only be achievable when \fBpadding\fR exists within the objects.
786 767 See \fBNotes\fR.
787 768
788 769 .LP
789 770 \fBExample 2 \fRRemoving a Hardware Capability Bit
790 771 .sp
791 772 .LP
792 773 Objects that require optional hardware support to run are built with a
793 774 capability section that contains a mask of bits specifying which capabilities
794 775 they need. The runtime linker (\fBld.so.1\fR) checks this mask against the
795 776 attributes of the running system to determine whether a given object is able to
796 777 be run by the current system. Programs that require abilities not available on
797 778 the system are prevented from running.
798 779
799 780 .sp
800 781 .LP
801 782 This check prevents a naive program that does not explicitly check for the
802 783 hardware support it requires from crashing in a confusing manner. However, it
803 784 can be inconvenient for a program that is written to explicitly check the
804 785 system capabilities at runtime. Such a program might have optimized code to use
805 786 when the hardware supports it while providing a generic fallback version that
806 787 can be run, albeit more slowly, otherwise. In this case, the hardware
807 788 compatibility mask prevents such a program from running on the older hardware.
808 789 In such a case, removing the relevant bit from the mask allows the program to
809 790 run.
810 791
811 792 .sp
812 793 .LP
813 794 The following example removes the \fBAV_386_SSE\fR3 hardware capability from an
814 795 x86 binary that uses the SSE3 CPU extension. This transfers responsibility for
815 796 validating the ability to use SSE3 from the runtime linker to the program
816 797 itself:
817 798
818 799 .sp
819 800 .in +2
820 801 .nf
821 802 elfedit -e 'cap:hw1 -and -cmp sse3' prog
822 803 .fi
823 804 .in -2
824 805 .sp
825 806
826 807 .LP
827 808 \fBExample 3 \fRReading Information From an Object
828 809 .sp
829 810 .LP
830 811 \fBelfedit\fR can be used to extract specific targeted information from an
831 812 object. The following shell command reads the number of section headers
832 813 contained in the file \fB/usr/bin/ls\fR:
833 814
834 815 .sp
835 816 .in +2
836 817 .nf
837 818 % SHNUM=`elfedit -r -onum -e 'ehdr:e_shnum' /usr/bin/ls`
838 819 % echo $SHNUM
839 820 29
840 821 .fi
841 822 .in -2
842 823 .sp
843 824
844 825 .sp
845 826 .LP
846 827 You might get a different value, depending on the version of Solaris and type
847 828 of machine that you are using. The \fB-r\fR option causes the file to be opened
848 829 read-only, allowing a user with ordinary access permissions to open the file,
849 830 and protecting against accidental damage to an important system executable. The
850 831 \fBnum\fR output style is used in order to obtain only the desired value,
851 832 without any extraneous text.
852 833
853 834 .sp
854 835 .LP
855 836 Similarly, the following extracts the symbol type of the symbol \fBunlink\fR
856 837 from the C runtime library:
857 838
858 839 .sp
↓ open down ↓ |
111 lines elided |
↑ open up ↑ |
859 840 .in +2
860 841 .nf
861 842 % TYPE=`elfedit -r -osimple -e 'sym:st_type unlink' /lib/libc.so`
862 843 % echo $TYPE
863 844 STT_FUNC
864 845 .fi
865 846 .in -2
866 847 .sp
867 848
868 849 .SH ENVIRONMENT VARIABLES
869 -.sp
870 850 .ne 2
871 851 .na
872 852 \fB\fBELFEDIT_PATH\fR\fR
873 853 .ad
874 854 .RS 16n
875 855 Alters the default module search path. Module search paths are discussed in the
876 856 \fBModule Search Path\fR section of this manual page.
877 857 .RE
878 858
879 859 .sp
880 860 .ne 2
881 861 .na
882 862 \fB\fBLD_NOEXEC_64\fR\fR
883 863 .ad
884 864 .RS 16n
885 865 Suppresses the automatic execution of the 64-bit \fBelfedit\fR. By default, the
886 866 64-bit version of \fBelfedit\fR runs if the system is 64-bit capable.
887 867 .RE
888 868
889 869 .sp
↓ open down ↓ |
10 lines elided |
↑ open up ↑ |
890 870 .ne 2
891 871 .na
892 872 \fB\fBPAGER\fR\fR
893 873 .ad
894 874 .RS 16n
895 875 Interactively delivers output from \fBelfedit\fR to the screen. If not set,
896 876 \fBmore\fR is used. See \fBmore\fR(1).
897 877 .RE
898 878
899 879 .SH FILES
900 -.sp
901 880 .ne 2
902 881 .na
903 882 \fB\fB/usr/lib/elfedit\fR\fR
904 883 .ad
905 884 .RS 20n
906 885 Default directory for \fBelfedit\fR modules that are loaded on demand to supply
907 886 editing commands.
908 887 .RE
909 888
910 889 .sp
911 890 .ne 2
912 891 .na
913 892 \fB\fB~/.teclarc\fR\fR
914 893 .ad
915 894 .RS 20n
916 895 Personal \fBtecla\fR customization file for command line editing. See
917 896 \fBtecla\fR(5).
918 897 .RE
919 898
920 899 .SH ATTRIBUTES
921 -.sp
922 -.LP
923 900 See \fBattributes\fR(5) for descriptions of the following attributes:
924 901 .sp
925 902
926 903 .sp
927 904 .TS
928 905 box;
929 906 c | c
930 907 l | l .
931 908 ATTRIBUTE TYPE ATTRIBUTE VALUE
932 909 _
933 910 Interface Stability Committed
934 911 .TE
935 912
936 913 .SH SEE ALSO
937 -.sp
938 -.LP
939 914 \fBdump\fR(1), \fBelfdump\fR(1), \fBld.so.1\fR(1), \fBmore\fR(1), \fBnm\fR(1),
940 915 \fBpvs\fR(1), \fBelf\fR(3ELF), \fBlibelf\fR(3LIB), \fBtecla\fR(5),
941 916 \fBattributes\fR(5)
942 917 .sp
943 918 .LP
944 919 \fILinker and Libraries Guide\fR
945 920 .SH WARNINGS
946 -.sp
947 -.LP
948 921 \fBelfedit\fR is designed to be a tool for testing and development of the ELF
949 922 system. It offers the ability to examine and change nearly every piece of ELF
950 923 metadata in the object. It quietly allows edits that can produce an invalid or
951 924 unusable ELF file. The user is expected to have knowledge of the ELF format and
952 925 of the rules and conventions that govern them. The \fILinker and Libraries
953 926 Guide\fR can be helpful when using \fBelfedit\fR.
954 927 .sp
955 928 .LP
956 929 \fBelfedit\fR allows the user to alter the ELF metadata in an object, but
957 930 cannot understand or alter the code of the actual program. Setting ELF
958 931 attributes such as types, sizes, alignments, and so forth in a manner that does
959 932 not agree with the actual contents of the file is therefore likely to yield a
960 933 broken and unusable output object. Such changes might be useful for testing of
961 934 linker components, but should be avoided otherwise.
962 935 .sp
963 936 .LP
964 937 Higher level operations, such as the use of the \fBdyn:runpath\fR command to
965 938 change the \fBrunpath\fR of an object, are safe, and can be carried out without
966 939 the sort of risk detailed in this section.
967 940 .SH NOTES
968 -.sp
969 -.LP
970 941 Not every ELF operation supported by \fBelfedit\fR can be successfully carried
971 942 out on every ELF object. \fBelfedit\fR is constrained by the existing sections
972 943 found in the file.
973 944 .sp
974 945 .LP
975 946 One area of particular interest is that \fBelfedit\fR might not be able to
976 947 modify the \fBrunpath\fR of a given object. To modify a \fBrunpath\fR, the
977 948 following must be true:
978 949 .RS +4
979 950 .TP
980 951 .ie t \(bu
981 952 .el o
982 953 The desired string must already exist in the dynamic string table, or there
983 954 must be enough reserved space within this section for the new string to be
984 955 added. If your object has a string table reservation area, the value of the
985 956 \fB\&.dynamic DT_SUNW_STRPAD\fR element indicates the size of the area. The
986 957 following \fBelfedit\fR command can be used to check this:
987 958 .sp
988 959 .in +2
989 960 .nf
990 961 % elfedit -r -e 'dyn:tag DT_SUNW_STRPAD' file
991 962 .fi
992 963 .in -2
993 964 .sp
994 965
995 966 .RE
996 967 .RS +4
997 968 .TP
998 969 .ie t \(bu
999 970 .el o
1000 971 The dynamic section must already have a \fBrunpath\fR element, or there must be
1001 972 an unused dynamic slot available where one can be inserted. To test for the
1002 973 presence of an existing \fBrunpath\fR:
1003 974 .sp
1004 975 .in +2
1005 976 .nf
1006 977 % elfedit -r -e 'dyn:runpath' file
1007 978 .fi
1008 979 .in -2
1009 980 .sp
1010 981
1011 982 A dynamic section uses an element of type \fBDT_NULL\fR to terminate the array
1012 983 found in that section. The final \fBDT_NULL\fR cannot be changed, but if there
1013 984 are more than one of these, \fBelfedit\fR can convert one of them into a
1014 985 \fBrunpath\fR element. To test for extra dynamic slots:
1015 986 .sp
1016 987 .in +2
1017 988 .nf
1018 989 % elfedit -r -e 'dyn:tag DT_NULL' file
1019 990 .fi
1020 991 .in -2
1021 992 .sp
1022 993
1023 994 .RE
1024 995 .sp
1025 996 .LP
1026 997 Older objects do not have the extra space necessary to complete such
1027 998 operations. The space necessary to do so was introduced in the Solaris Express
1028 999 Community Edition release.
1029 1000 .sp
1030 1001 .LP
1031 1002 When an operation fails, the detailed information printed using the \fB-d\fR
1032 1003 (debug) option can be very helpful in uncovering the reason why.
1033 1004 .sp
1034 1005 .LP
1035 1006 \fBelfedit\fR modules follow a convention by which commands that directly
1036 1007 manipulate a field in an ELF structure have the same name as the field, while
1037 1008 commands that implement higher level concepts do not. For instance, the command
1038 1009 to manipulate the \fBe_flags\fR field in the ELF header is named
1039 1010 \fBehdr:e_flags\fR. Therefore, you generally find the command to modify ELF
1040 1011 fields by identifying the module and looking for a command with the name of the
1041 1012 field.
↓ open down ↓ |
62 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX