Add --input-type and --output-type to elfedit
[deliverable/binutils-gdb.git] / binutils / doc / binutils.texi
1 \input texinfo @c -*- Texinfo -*-
2 @setfilename binutils.info
3 @settitle @sc{gnu} Binary Utilities
4 @finalout
5 @synindex ky cp
6
7 @c man begin INCLUDE
8 @include bfdver.texi
9 @c man end
10
11 @copying
12 @c man begin COPYRIGHT
13 Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
14 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
15 Free Software Foundation, Inc.
16
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.3
19 or any later version published by the Free Software Foundation;
20 with no Invariant Sections, with no Front-Cover Texts, and with no
21 Back-Cover Texts. A copy of the license is included in the
22 section entitled ``GNU Free Documentation License''.
23
24 @c man end
25 @end copying
26
27 @dircategory Software development
28 @direntry
29 * Binutils: (binutils). The GNU binary utilities.
30 @end direntry
31
32 @dircategory Individual utilities
33 @direntry
34 * addr2line: (binutils)addr2line. Convert addresses to file and line.
35 * ar: (binutils)ar. Create, modify, and extract from archives.
36 * c++filt: (binutils)c++filt. Filter to demangle encoded C++ symbols.
37 * cxxfilt: (binutils)c++filt. MS-DOS name for c++filt.
38 * dlltool: (binutils)dlltool. Create files needed to build and use DLLs.
39 * nlmconv: (binutils)nlmconv. Converts object code into an NLM.
40 * nm: (binutils)nm. List symbols from object files.
41 * objcopy: (binutils)objcopy. Copy and translate object files.
42 * objdump: (binutils)objdump. Display information from object files.
43 * ranlib: (binutils)ranlib. Generate index to archive contents.
44 * readelf: (binutils)readelf. Display the contents of ELF format files.
45 * size: (binutils)size. List section sizes and total size.
46 * strings: (binutils)strings. List printable strings from files.
47 * strip: (binutils)strip. Discard symbols.
48 * elfedit: (binutils)elfedit. Update the ELF header of ELF files.
49 * windmc: (binutils)windmc. Generator for Windows message resources.
50 * windres: (binutils)windres. Manipulate Windows resources.
51 @end direntry
52
53 @titlepage
54 @title The @sc{gnu} Binary Utilities
55 @ifset VERSION_PACKAGE
56 @subtitle @value{VERSION_PACKAGE}
57 @end ifset
58 @subtitle Version @value{VERSION}
59 @sp 1
60 @subtitle @value{UPDATED}
61 @author Roland H. Pesch
62 @author Jeffrey M. Osier
63 @author Cygnus Support
64 @page
65
66 @tex
67 {\parskip=0pt \hfill Cygnus Support\par \hfill
68 Texinfo \texinfoversion\par }
69 @end tex
70
71 @vskip 0pt plus 1filll
72 @insertcopying
73 @end titlepage
74 @contents
75
76 @node Top
77 @top Introduction
78
79 @cindex version
80 This brief manual contains documentation for the @sc{gnu} binary
81 utilities
82 @ifset VERSION_PACKAGE
83 @value{VERSION_PACKAGE}
84 @end ifset
85 version @value{VERSION}:
86
87 @iftex
88 @table @code
89 @item ar
90 Create, modify, and extract from archives
91
92 @item nm
93 List symbols from object files
94
95 @item objcopy
96 Copy and translate object files
97
98 @item objdump
99 Display information from object files
100
101 @item ranlib
102 Generate index to archive contents
103
104 @item readelf
105 Display the contents of ELF format files.
106
107 @item size
108 List file section sizes and total size
109
110 @item strings
111 List printable strings from files
112
113 @item strip
114 Discard symbols
115
116 @item elfedit
117 Update the ELF header of ELF files.
118
119 @item c++filt
120 Demangle encoded C++ symbols (on MS-DOS, this program is named
121 @code{cxxfilt})
122
123 @item addr2line
124 Convert addresses into file names and line numbers
125
126 @item nlmconv
127 Convert object code into a Netware Loadable Module
128
129 @item windres
130 Manipulate Windows resources
131
132 @item windmc
133 Genertor for Windows message resources
134
135 @item dlltool
136 Create the files needed to build and use Dynamic Link Libraries
137 @end table
138 @end iftex
139
140 This document is distributed under the terms of the GNU Free
141 Documentation License version 1.3. A copy of the license is included
142 in the section entitled ``GNU Free Documentation License''.
143
144 @menu
145 * ar:: Create, modify, and extract from archives
146 * nm:: List symbols from object files
147 * objcopy:: Copy and translate object files
148 * objdump:: Display information from object files
149 * ranlib:: Generate index to archive contents
150 * readelf:: Display the contents of ELF format files
151 * size:: List section sizes and total size
152 * strings:: List printable strings from files
153 * strip:: Discard symbols
154 * elfedit:: Update the ELF header of ELF files
155 * c++filt:: Filter to demangle encoded C++ symbols
156 * cxxfilt: c++filt. MS-DOS name for c++filt
157 * addr2line:: Convert addresses to file and line
158 * nlmconv:: Converts object code into an NLM
159 * windres:: Manipulate Windows resources
160 * windmc:: Generator for Windows message resources
161 * dlltool:: Create files needed to build and use DLLs
162 * Common Options:: Command-line options for all utilities
163 * Selecting the Target System:: How these utilities determine the target
164 * Reporting Bugs:: Reporting Bugs
165 * GNU Free Documentation License:: GNU Free Documentation License
166 * Binutils Index:: Binutils Index
167 @end menu
168
169 @node ar
170 @chapter ar
171
172 @kindex ar
173 @cindex archives
174 @cindex collections of files
175
176 @c man title ar create, modify, and extract from archives
177
178 @smallexample
179 ar [@option{--plugin} @var{name}] [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
180 ar -M [ <mri-script ]
181 @end smallexample
182
183 @c man begin DESCRIPTION ar
184
185 The @sc{gnu} @command{ar} program creates, modifies, and extracts from
186 archives. An @dfn{archive} is a single file holding a collection of
187 other files in a structure that makes it possible to retrieve
188 the original individual files (called @dfn{members} of the archive).
189
190 The original files' contents, mode (permissions), timestamp, owner, and
191 group are preserved in the archive, and can be restored on
192 extraction.
193
194 @cindex name length
195 @sc{gnu} @command{ar} can maintain archives whose members have names of any
196 length; however, depending on how @command{ar} is configured on your
197 system, a limit on member-name length may be imposed for compatibility
198 with archive formats maintained with other tools. If it exists, the
199 limit is often 15 characters (typical of formats related to a.out) or 16
200 characters (typical of formats related to coff).
201
202 @cindex libraries
203 @command{ar} is considered a binary utility because archives of this sort
204 are most often used as @dfn{libraries} holding commonly needed
205 subroutines.
206
207 @cindex symbol index
208 @command{ar} creates an index to the symbols defined in relocatable
209 object modules in the archive when you specify the modifier @samp{s}.
210 Once created, this index is updated in the archive whenever @command{ar}
211 makes a change to its contents (save for the @samp{q} update operation).
212 An archive with such an index speeds up linking to the library, and
213 allows routines in the library to call each other without regard to
214 their placement in the archive.
215
216 You may use @samp{nm -s} or @samp{nm --print-armap} to list this index
217 table. If an archive lacks the table, another form of @command{ar} called
218 @command{ranlib} can be used to add just the table.
219
220 @cindex thin archives
221 @sc{gnu} @command{ar} can optionally create a @emph{thin} archive,
222 which contains a symbol index and references to the original copies
223 of the member files of the archives. Such an archive is useful
224 for building libraries for use within a local build, where the
225 relocatable objects are expected to remain available, and copying the
226 contents of each object would only waste time and space. Thin archives
227 are also @emph{flattened}, so that adding one or more archives to a
228 thin archive will add the elements of the nested archive individually.
229 The paths to the elements of the archive are stored relative to the
230 archive itself.
231
232 @cindex compatibility, @command{ar}
233 @cindex @command{ar} compatibility
234 @sc{gnu} @command{ar} is designed to be compatible with two different
235 facilities. You can control its activity using command-line options,
236 like the different varieties of @command{ar} on Unix systems; or, if you
237 specify the single command-line option @option{-M}, you can control it
238 with a script supplied via standard input, like the MRI ``librarian''
239 program.
240
241 @c man end
242
243 @menu
244 * ar cmdline:: Controlling @command{ar} on the command line
245 * ar scripts:: Controlling @command{ar} with a script
246 @end menu
247
248 @page
249 @node ar cmdline
250 @section Controlling @command{ar} on the Command Line
251
252 @smallexample
253 @c man begin SYNOPSIS ar
254 ar [@option{--plugin} @var{name}] [@option{-X32_64}] [@option{-}]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
255 @c man end
256 @end smallexample
257
258 @cindex Unix compatibility, @command{ar}
259 When you use @command{ar} in the Unix style, @command{ar} insists on at least two
260 arguments to execute: one keyletter specifying the @emph{operation}
261 (optionally accompanied by other keyletters specifying
262 @emph{modifiers}), and the archive name to act on.
263
264 Most operations can also accept further @var{member} arguments,
265 specifying particular files to operate on.
266
267 @c man begin OPTIONS ar
268
269 @sc{gnu} @command{ar} allows you to mix the operation code @var{p} and modifier
270 flags @var{mod} in any order, within the first command-line argument.
271
272 If you wish, you may begin the first command-line argument with a
273 dash.
274
275 @cindex operations on archive
276 The @var{p} keyletter specifies what operation to execute; it may be
277 any of the following, but you must specify only one of them:
278
279 @table @samp
280 @item d
281 @cindex deleting from archive
282 @emph{Delete} modules from the archive. Specify the names of modules to
283 be deleted as @var{member}@dots{}; the archive is untouched if you
284 specify no files to delete.
285
286 If you specify the @samp{v} modifier, @command{ar} lists each module
287 as it is deleted.
288
289 @item m
290 @cindex moving in archive
291 Use this operation to @emph{move} members in an archive.
292
293 The ordering of members in an archive can make a difference in how
294 programs are linked using the library, if a symbol is defined in more
295 than one member.
296
297 If no modifiers are used with @code{m}, any members you name in the
298 @var{member} arguments are moved to the @emph{end} of the archive;
299 you can use the @samp{a}, @samp{b}, or @samp{i} modifiers to move them to a
300 specified place instead.
301
302 @item p
303 @cindex printing from archive
304 @emph{Print} the specified members of the archive, to the standard
305 output file. If the @samp{v} modifier is specified, show the member
306 name before copying its contents to standard output.
307
308 If you specify no @var{member} arguments, all the files in the archive are
309 printed.
310
311 @item q
312 @cindex quick append to archive
313 @emph{Quick append}; Historically, add the files @var{member}@dots{} to the end of
314 @var{archive}, without checking for replacement.
315
316 The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this
317 operation; new members are always placed at the end of the archive.
318
319 The modifier @samp{v} makes @command{ar} list each file as it is appended.
320
321 Since the point of this operation is speed, the archive's symbol table
322 index is not updated, even if it already existed; you can use @samp{ar s} or
323 @command{ranlib} explicitly to update the symbol table index.
324
325 However, too many different systems assume quick append rebuilds the
326 index, so @sc{gnu} @command{ar} implements @samp{q} as a synonym for @samp{r}.
327
328 @item r
329 @cindex replacement in archive
330 Insert the files @var{member}@dots{} into @var{archive} (with
331 @emph{replacement}). This operation differs from @samp{q} in that any
332 previously existing members are deleted if their names match those being
333 added.
334
335 If one of the files named in @var{member}@dots{} does not exist, @command{ar}
336 displays an error message, and leaves undisturbed any existing members
337 of the archive matching that name.
338
339 By default, new members are added at the end of the file; but you may
340 use one of the modifiers @samp{a}, @samp{b}, or @samp{i} to request
341 placement relative to some existing member.
342
343 The modifier @samp{v} used with this operation elicits a line of
344 output for each file inserted, along with one of the letters @samp{a} or
345 @samp{r} to indicate whether the file was appended (no old member
346 deleted) or replaced.
347
348 @item t
349 @cindex contents of archive
350 Display a @emph{table} listing the contents of @var{archive}, or those
351 of the files listed in @var{member}@dots{} that are present in the
352 archive. Normally only the member name is shown; if you also want to
353 see the modes (permissions), timestamp, owner, group, and size, you can
354 request that by also specifying the @samp{v} modifier.
355
356 If you do not specify a @var{member}, all files in the archive
357 are listed.
358
359 @cindex repeated names in archive
360 @cindex name duplication in archive
361 If there is more than one file with the same name (say, @samp{fie}) in
362 an archive (say @samp{b.a}), @samp{ar t b.a fie} lists only the
363 first instance; to see them all, you must ask for a complete
364 listing---in our example, @samp{ar t b.a}.
365 @c WRS only; per Gumby, this is implementation-dependent, and in a more
366 @c recent case in fact works the other way.
367
368 @item x
369 @cindex extract from archive
370 @emph{Extract} members (named @var{member}) from the archive. You can
371 use the @samp{v} modifier with this operation, to request that
372 @command{ar} list each name as it extracts it.
373
374 If you do not specify a @var{member}, all files in the archive
375 are extracted.
376
377 Files cannot be extracted from a thin archive.
378
379 @end table
380
381 A number of modifiers (@var{mod}) may immediately follow the @var{p}
382 keyletter, to specify variations on an operation's behavior:
383
384 @table @samp
385 @item a
386 @cindex relative placement in archive
387 Add new files @emph{after} an existing member of the
388 archive. If you use the modifier @samp{a}, the name of an existing archive
389 member must be present as the @var{relpos} argument, before the
390 @var{archive} specification.
391
392 @item b
393 Add new files @emph{before} an existing member of the
394 archive. If you use the modifier @samp{b}, the name of an existing archive
395 member must be present as the @var{relpos} argument, before the
396 @var{archive} specification. (same as @samp{i}).
397
398 @item c
399 @cindex creating archives
400 @emph{Create} the archive. The specified @var{archive} is always
401 created if it did not exist, when you request an update. But a warning is
402 issued unless you specify in advance that you expect to create it, by
403 using this modifier.
404
405 @item D
406 @cindex deterministic archives
407 Operate in @emph{deterministic} mode. When adding files and the archive
408 index use zero for UIDs, GIDs, timestamps, and use consistent file modes
409 for all files. When this option is used, if @command{ar} is used with
410 identical options and identical input files, multiple runs will create
411 identical output files regardless of the input files' owners, groups,
412 file modes, or modification times.
413
414 @item f
415 Truncate names in the archive. @sc{gnu} @command{ar} will normally permit file
416 names of any length. This will cause it to create archives which are
417 not compatible with the native @command{ar} program on some systems. If
418 this is a concern, the @samp{f} modifier may be used to truncate file
419 names when putting them in the archive.
420
421 @item i
422 Insert new files @emph{before} an existing member of the
423 archive. If you use the modifier @samp{i}, the name of an existing archive
424 member must be present as the @var{relpos} argument, before the
425 @var{archive} specification. (same as @samp{b}).
426
427 @item l
428 This modifier is accepted but not used.
429 @c whaffor ar l modifier??? presumably compat; with
430 @c what???---doc@@cygnus.com, 25jan91
431
432 @item N
433 Uses the @var{count} parameter. This is used if there are multiple
434 entries in the archive with the same name. Extract or delete instance
435 @var{count} of the given name from the archive.
436
437 @item o
438 @cindex dates in archive
439 Preserve the @emph{original} dates of members when extracting them. If
440 you do not specify this modifier, files extracted from the archive
441 are stamped with the time of extraction.
442
443 @item P
444 Use the full path name when matching names in the archive. @sc{gnu}
445 @command{ar} can not create an archive with a full path name (such archives
446 are not POSIX complaint), but other archive creators can. This option
447 will cause @sc{gnu} @command{ar} to match file names using a complete path
448 name, which can be convenient when extracting a single file from an
449 archive created by another tool.
450
451 @item s
452 @cindex writing archive index
453 Write an object-file index into the archive, or update an existing one,
454 even if no other change is made to the archive. You may use this modifier
455 flag either with any operation, or alone. Running @samp{ar s} on an
456 archive is equivalent to running @samp{ranlib} on it.
457
458 @item S
459 @cindex not writing archive index
460 Do not generate an archive symbol table. This can speed up building a
461 large library in several steps. The resulting archive can not be used
462 with the linker. In order to build a symbol table, you must omit the
463 @samp{S} modifier on the last execution of @samp{ar}, or you must run
464 @samp{ranlib} on the archive.
465
466 @item T
467 @cindex creating thin archive
468 Make the specified @var{archive} a @emph{thin} archive. If it already
469 exists and is a regular archive, the existing members must be present
470 in the same directory as @var{archive}.
471
472 @item u
473 @cindex updating an archive
474 Normally, @samp{ar r}@dots{} inserts all files
475 listed into the archive. If you would like to insert @emph{only} those
476 of the files you list that are newer than existing members of the same
477 names, use this modifier. The @samp{u} modifier is allowed only for the
478 operation @samp{r} (replace). In particular, the combination @samp{qu} is
479 not allowed, since checking the timestamps would lose any speed
480 advantage from the operation @samp{q}.
481
482 @item v
483 This modifier requests the @emph{verbose} version of an operation. Many
484 operations display additional information, such as filenames processed,
485 when the modifier @samp{v} is appended.
486
487 @item V
488 This modifier shows the version number of @command{ar}.
489 @end table
490
491 @command{ar} ignores an initial option spelt @samp{-X32_64}, for
492 compatibility with AIX. The behaviour produced by this option is the
493 default for @sc{gnu} @command{ar}. @command{ar} does not support any of the other
494 @samp{-X} options; in particular, it does not support @option{-X32}
495 which is the default for AIX @command{ar}.
496
497 The optional command line switch @option{--plugin} @var{name} causes
498 @command{ar} to load the plugin called @var{name} which adds support
499 for more file formats. This option is only available if the toolchain
500 has been built with plugin support enabled.
501
502 @c man end
503
504 @ignore
505 @c man begin SEEALSO ar
506 nm(1), ranlib(1), and the Info entries for @file{binutils}.
507 @c man end
508 @end ignore
509
510 @node ar scripts
511 @section Controlling @command{ar} with a Script
512
513 @smallexample
514 ar -M [ <@var{script} ]
515 @end smallexample
516
517 @cindex MRI compatibility, @command{ar}
518 @cindex scripts, @command{ar}
519 If you use the single command-line option @samp{-M} with @command{ar}, you
520 can control its operation with a rudimentary command language. This
521 form of @command{ar} operates interactively if standard input is coming
522 directly from a terminal. During interactive use, @command{ar} prompts for
523 input (the prompt is @samp{AR >}), and continues executing even after
524 errors. If you redirect standard input to a script file, no prompts are
525 issued, and @command{ar} abandons execution (with a nonzero exit code)
526 on any error.
527
528 The @command{ar} command language is @emph{not} designed to be equivalent
529 to the command-line options; in fact, it provides somewhat less control
530 over archives. The only purpose of the command language is to ease the
531 transition to @sc{gnu} @command{ar} for developers who already have scripts
532 written for the MRI ``librarian'' program.
533
534 The syntax for the @command{ar} command language is straightforward:
535 @itemize @bullet
536 @item
537 commands are recognized in upper or lower case; for example, @code{LIST}
538 is the same as @code{list}. In the following descriptions, commands are
539 shown in upper case for clarity.
540
541 @item
542 a single command may appear on each line; it is the first word on the
543 line.
544
545 @item
546 empty lines are allowed, and have no effect.
547
548 @item
549 comments are allowed; text after either of the characters @samp{*}
550 or @samp{;} is ignored.
551
552 @item
553 Whenever you use a list of names as part of the argument to an @command{ar}
554 command, you can separate the individual names with either commas or
555 blanks. Commas are shown in the explanations below, for clarity.
556
557 @item
558 @samp{+} is used as a line continuation character; if @samp{+} appears
559 at the end of a line, the text on the following line is considered part
560 of the current command.
561 @end itemize
562
563 Here are the commands you can use in @command{ar} scripts, or when using
564 @command{ar} interactively. Three of them have special significance:
565
566 @code{OPEN} or @code{CREATE} specify a @dfn{current archive}, which is
567 a temporary file required for most of the other commands.
568
569 @code{SAVE} commits the changes so far specified by the script. Prior
570 to @code{SAVE}, commands affect only the temporary copy of the current
571 archive.
572
573 @table @code
574 @item ADDLIB @var{archive}
575 @itemx ADDLIB @var{archive} (@var{module}, @var{module}, @dots{} @var{module})
576 Add all the contents of @var{archive} (or, if specified, each named
577 @var{module} from @var{archive}) to the current archive.
578
579 Requires prior use of @code{OPEN} or @code{CREATE}.
580
581 @item ADDMOD @var{member}, @var{member}, @dots{} @var{member}
582 @c FIXME! w/Replacement?? If so, like "ar r @var{archive} @var{names}"
583 @c else like "ar q..."
584 Add each named @var{member} as a module in the current archive.
585
586 Requires prior use of @code{OPEN} or @code{CREATE}.
587
588 @item CLEAR
589 Discard the contents of the current archive, canceling the effect of
590 any operations since the last @code{SAVE}. May be executed (with no
591 effect) even if no current archive is specified.
592
593 @item CREATE @var{archive}
594 Creates an archive, and makes it the current archive (required for many
595 other commands). The new archive is created with a temporary name; it
596 is not actually saved as @var{archive} until you use @code{SAVE}.
597 You can overwrite existing archives; similarly, the contents of any
598 existing file named @var{archive} will not be destroyed until @code{SAVE}.
599
600 @item DELETE @var{module}, @var{module}, @dots{} @var{module}
601 Delete each listed @var{module} from the current archive; equivalent to
602 @samp{ar -d @var{archive} @var{module} @dots{} @var{module}}.
603
604 Requires prior use of @code{OPEN} or @code{CREATE}.
605
606 @item DIRECTORY @var{archive} (@var{module}, @dots{} @var{module})
607 @itemx DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) @var{outputfile}
608 List each named @var{module} present in @var{archive}. The separate
609 command @code{VERBOSE} specifies the form of the output: when verbose
610 output is off, output is like that of @samp{ar -t @var{archive}
611 @var{module}@dots{}}. When verbose output is on, the listing is like
612 @samp{ar -tv @var{archive} @var{module}@dots{}}.
613
614 Output normally goes to the standard output stream; however, if you
615 specify @var{outputfile} as a final argument, @command{ar} directs the
616 output to that file.
617
618 @item END
619 Exit from @command{ar}, with a @code{0} exit code to indicate successful
620 completion. This command does not save the output file; if you have
621 changed the current archive since the last @code{SAVE} command, those
622 changes are lost.
623
624 @item EXTRACT @var{module}, @var{module}, @dots{} @var{module}
625 Extract each named @var{module} from the current archive, writing them
626 into the current directory as separate files. Equivalent to @samp{ar -x
627 @var{archive} @var{module}@dots{}}.
628
629 Requires prior use of @code{OPEN} or @code{CREATE}.
630
631 @ignore
632 @c FIXME Tokens but no commands???
633 @item FULLDIR
634
635 @item HELP
636 @end ignore
637
638 @item LIST
639 Display full contents of the current archive, in ``verbose'' style
640 regardless of the state of @code{VERBOSE}. The effect is like @samp{ar
641 tv @var{archive}}. (This single command is a @sc{gnu} @command{ar}
642 enhancement, rather than present for MRI compatibility.)
643
644 Requires prior use of @code{OPEN} or @code{CREATE}.
645
646 @item OPEN @var{archive}
647 Opens an existing archive for use as the current archive (required for
648 many other commands). Any changes as the result of subsequent commands
649 will not actually affect @var{archive} until you next use @code{SAVE}.
650
651 @item REPLACE @var{module}, @var{module}, @dots{} @var{module}
652 In the current archive, replace each existing @var{module} (named in
653 the @code{REPLACE} arguments) from files in the current working directory.
654 To execute this command without errors, both the file, and the module in
655 the current archive, must exist.
656
657 Requires prior use of @code{OPEN} or @code{CREATE}.
658
659 @item VERBOSE
660 Toggle an internal flag governing the output from @code{DIRECTORY}.
661 When the flag is on, @code{DIRECTORY} output matches output from
662 @samp{ar -tv }@dots{}.
663
664 @item SAVE
665 Commit your changes to the current archive, and actually save it as a
666 file with the name specified in the last @code{CREATE} or @code{OPEN}
667 command.
668
669 Requires prior use of @code{OPEN} or @code{CREATE}.
670
671 @end table
672
673 @iftex
674 @node ld
675 @chapter ld
676 @cindex linker
677 @kindex ld
678 The @sc{gnu} linker @command{ld} is now described in a separate manual.
679 @xref{Top,, Overview,, Using LD: the @sc{gnu} linker}.
680 @end iftex
681
682 @node nm
683 @chapter nm
684 @cindex symbols
685 @kindex nm
686
687 @c man title nm list symbols from object files
688
689 @smallexample
690 @c man begin SYNOPSIS nm
691 nm [@option{-a}|@option{--debug-syms}]
692 [@option{-g}|@option{--extern-only}][@option{--plugin} @var{name}]
693 [@option{-B}] [@option{-C}|@option{--demangle}[=@var{style}]] [@option{-D}|@option{--dynamic}]
694 [@option{-S}|@option{--print-size}] [@option{-s}|@option{--print-armap}]
695 [@option{-A}|@option{-o}|@option{--print-file-name}][@option{--special-syms}]
696 [@option{-n}|@option{-v}|@option{--numeric-sort}] [@option{-p}|@option{--no-sort}]
697 [@option{-r}|@option{--reverse-sort}] [@option{--size-sort}] [@option{-u}|@option{--undefined-only}]
698 [@option{-t} @var{radix}|@option{--radix=}@var{radix}] [@option{-P}|@option{--portability}]
699 [@option{--target=}@var{bfdname}] [@option{-f}@var{format}|@option{--format=}@var{format}]
700 [@option{--defined-only}] [@option{-l}|@option{--line-numbers}] [@option{--no-demangle}]
701 [@option{-V}|@option{--version}] [@option{-X 32_64}] [@option{--help}] [@var{objfile}@dots{}]
702 @c man end
703 @end smallexample
704
705 @c man begin DESCRIPTION nm
706 @sc{gnu} @command{nm} lists the symbols from object files @var{objfile}@dots{}.
707 If no object files are listed as arguments, @command{nm} assumes the file
708 @file{a.out}.
709
710 For each symbol, @command{nm} shows:
711
712 @itemize @bullet
713 @item
714 The symbol value, in the radix selected by options (see below), or
715 hexadecimal by default.
716
717 @item
718 The symbol type. At least the following types are used; others are, as
719 well, depending on the object file format. If lowercase, the symbol is
720 local; if uppercase, the symbol is global (external).
721
722 @c Some more detail on exactly what these symbol types are used for
723 @c would be nice.
724 @table @code
725 @item A
726 The symbol's value is absolute, and will not be changed by further
727 linking.
728
729 @item B
730 @itemx b
731 The symbol is in the uninitialized data section (known as BSS).
732
733 @item C
734 The symbol is common. Common symbols are uninitialized data. When
735 linking, multiple common symbols may appear with the same name. If the
736 symbol is defined anywhere, the common symbols are treated as undefined
737 references.
738 @ifclear man
739 For more details on common symbols, see the discussion of
740 --warn-common in @ref{Options,,Linker options,ld.info,The GNU linker}.
741 @end ifclear
742
743 @item D
744 @itemx d
745 The symbol is in the initialized data section.
746
747 @item G
748 @itemx g
749 The symbol is in an initialized data section for small objects. Some
750 object file formats permit more efficient access to small data objects,
751 such as a global int variable as opposed to a large global array.
752
753 @item i
754 For PE format files this indicates that the symbol is in a section
755 specific to the implementation of DLLs. For ELF format files this
756 indicates that the symbol is an indirect function. This is a GNU
757 extension to the standard set of ELF symbol types. It indicates a
758 symbol which if referenced by a relocation does not evaluate to its
759 address, but instead must be invoked at runtime. The runtime
760 execution will then return the value to be used in the relocation.
761
762 @item N
763 The symbol is a debugging symbol.
764
765 @item p
766 The symbols is in a stack unwind section.
767
768 @item R
769 @itemx r
770 The symbol is in a read only data section.
771
772 @item S
773 @itemx s
774 The symbol is in an uninitialized data section for small objects.
775
776 @item T
777 @itemx t
778 The symbol is in the text (code) section.
779
780 @item U
781 The symbol is undefined.
782
783 @item u
784 The symbol is a unique global symbol. This is a GNU extension to the
785 standard set of ELF symbol bindings. For such a symbol the dynamic linker
786 will make sure that in the entire process there is just one symbol with
787 this name and type in use.
788
789 @item V
790 @itemx v
791 The symbol is a weak object. When a weak defined symbol is linked with
792 a normal defined symbol, the normal defined symbol is used with no error.
793 When a weak undefined symbol is linked and the symbol is not defined,
794 the value of the weak symbol becomes zero with no error. On some
795 systems, uppercase indicates that a default value has been specified.
796
797 @item W
798 @itemx w
799 The symbol is a weak symbol that has not been specifically tagged as a
800 weak object symbol. When a weak defined symbol is linked with a normal
801 defined symbol, the normal defined symbol is used with no error.
802 When a weak undefined symbol is linked and the symbol is not defined,
803 the value of the symbol is determined in a system-specific manner without
804 error. On some systems, uppercase indicates that a default value has been
805 specified.
806
807 @item -
808 The symbol is a stabs symbol in an a.out object file. In this case, the
809 next values printed are the stabs other field, the stabs desc field, and
810 the stab type. Stabs symbols are used to hold debugging information.
811 @ifclear man
812 For more information, see @ref{Top,Stabs,Stabs Overview,stabs.info, The
813 ``stabs'' debug format}.
814 @end ifclear
815
816 @item ?
817 The symbol type is unknown, or object file format specific.
818 @end table
819
820 @item
821 The symbol name.
822 @end itemize
823
824 @c man end
825
826 @c man begin OPTIONS nm
827 The long and short forms of options, shown here as alternatives, are
828 equivalent.
829
830 @table @env
831 @item -A
832 @itemx -o
833 @itemx --print-file-name
834 @cindex input file name
835 @cindex file name
836 @cindex source file name
837 Precede each symbol by the name of the input file (or archive member)
838 in which it was found, rather than identifying the input file once only,
839 before all of its symbols.
840
841 @item -a
842 @itemx --debug-syms
843 @cindex debugging symbols
844 Display all symbols, even debugger-only symbols; normally these are not
845 listed.
846
847 @item -B
848 @cindex @command{nm} format
849 @cindex @command{nm} compatibility
850 The same as @option{--format=bsd} (for compatibility with the MIPS @command{nm}).
851
852 @item -C
853 @itemx --demangle[=@var{style}]
854 @cindex demangling in nm
855 Decode (@dfn{demangle}) low-level symbol names into user-level names.
856 Besides removing any initial underscore prepended by the system, this
857 makes C++ function names readable. Different compilers have different
858 mangling styles. The optional demangling style argument can be used to
859 choose an appropriate demangling style for your compiler. @xref{c++filt},
860 for more information on demangling.
861
862 @item --no-demangle
863 Do not demangle low-level symbol names. This is the default.
864
865 @item -D
866 @itemx --dynamic
867 @cindex dynamic symbols
868 Display the dynamic symbols rather than the normal symbols. This is
869 only meaningful for dynamic objects, such as certain types of shared
870 libraries.
871
872 @item -f @var{format}
873 @itemx --format=@var{format}
874 @cindex @command{nm} format
875 @cindex @command{nm} compatibility
876 Use the output format @var{format}, which can be @code{bsd},
877 @code{sysv}, or @code{posix}. The default is @code{bsd}.
878 Only the first character of @var{format} is significant; it can be
879 either upper or lower case.
880
881 @item -g
882 @itemx --extern-only
883 @cindex external symbols
884 Display only external symbols.
885
886 @item --plugin @var{name}
887 @cindex load plugin
888 Load the plugin called @var{name} to add support for extra target
889 types. This option is only available if the toolchain has been built
890 with plugin support enabled.
891
892 @item -l
893 @itemx --line-numbers
894 @cindex symbol line numbers
895 For each symbol, use debugging information to try to find a filename and
896 line number. For a defined symbol, look for the line number of the
897 address of the symbol. For an undefined symbol, look for the line
898 number of a relocation entry which refers to the symbol. If line number
899 information can be found, print it after the other symbol information.
900
901 @item -n
902 @itemx -v
903 @itemx --numeric-sort
904 Sort symbols numerically by their addresses, rather than alphabetically
905 by their names.
906
907 @item -p
908 @itemx --no-sort
909 @cindex sorting symbols
910 Do not bother to sort the symbols in any order; print them in the order
911 encountered.
912
913 @item -P
914 @itemx --portability
915 Use the POSIX.2 standard output format instead of the default format.
916 Equivalent to @samp{-f posix}.
917
918 @item -S
919 @itemx --print-size
920 Print both value and size of defined symbols for the @code{bsd} output style.
921 This option has no effect for object formats that do not record symbol
922 sizes, unless @samp{--size-sort} is also used in which case a
923 calculated size is displayed.
924
925 @item -s
926 @itemx --print-armap
927 @cindex symbol index, listing
928 When listing symbols from archive members, include the index: a mapping
929 (stored in the archive by @command{ar} or @command{ranlib}) of which modules
930 contain definitions for which names.
931
932 @item -r
933 @itemx --reverse-sort
934 Reverse the order of the sort (whether numeric or alphabetic); let the
935 last come first.
936
937 @item --size-sort
938 Sort symbols by size. The size is computed as the difference between
939 the value of the symbol and the value of the symbol with the next higher
940 value. If the @code{bsd} output format is used the size of the symbol
941 is printed, rather than the value, and @samp{-S} must be used in order
942 both size and value to be printed.
943
944 @item --special-syms
945 Display symbols which have a target-specific special meaning. These
946 symbols are usually used by the target for some special processing and
947 are not normally helpful when included included in the normal symbol
948 lists. For example for ARM targets this option would skip the mapping
949 symbols used to mark transitions between ARM code, THUMB code and
950 data.
951
952 @item -t @var{radix}
953 @itemx --radix=@var{radix}
954 Use @var{radix} as the radix for printing the symbol values. It must be
955 @samp{d} for decimal, @samp{o} for octal, or @samp{x} for hexadecimal.
956
957 @item --target=@var{bfdname}
958 @cindex object code format
959 Specify an object code format other than your system's default format.
960 @xref{Target Selection}, for more information.
961
962 @item -u
963 @itemx --undefined-only
964 @cindex external symbols
965 @cindex undefined symbols
966 Display only undefined symbols (those external to each object file).
967
968 @item --defined-only
969 @cindex external symbols
970 @cindex undefined symbols
971 Display only defined symbols for each object file.
972
973 @item -V
974 @itemx --version
975 Show the version number of @command{nm} and exit.
976
977 @item -X
978 This option is ignored for compatibility with the AIX version of
979 @command{nm}. It takes one parameter which must be the string
980 @option{32_64}. The default mode of AIX @command{nm} corresponds
981 to @option{-X 32}, which is not supported by @sc{gnu} @command{nm}.
982
983 @item --help
984 Show a summary of the options to @command{nm} and exit.
985 @end table
986
987 @c man end
988
989 @ignore
990 @c man begin SEEALSO nm
991 ar(1), objdump(1), ranlib(1), and the Info entries for @file{binutils}.
992 @c man end
993 @end ignore
994
995 @node objcopy
996 @chapter objcopy
997
998 @c man title objcopy copy and translate object files
999
1000 @smallexample
1001 @c man begin SYNOPSIS objcopy
1002 objcopy [@option{-F} @var{bfdname}|@option{--target=}@var{bfdname}]
1003 [@option{-I} @var{bfdname}|@option{--input-target=}@var{bfdname}]
1004 [@option{-O} @var{bfdname}|@option{--output-target=}@var{bfdname}]
1005 [@option{-B} @var{bfdarch}|@option{--binary-architecture=}@var{bfdarch}]
1006 [@option{-S}|@option{--strip-all}]
1007 [@option{-g}|@option{--strip-debug}]
1008 [@option{-K} @var{symbolname}|@option{--keep-symbol=}@var{symbolname}]
1009 [@option{-N} @var{symbolname}|@option{--strip-symbol=}@var{symbolname}]
1010 [@option{--strip-unneeded-symbol=}@var{symbolname}]
1011 [@option{-G} @var{symbolname}|@option{--keep-global-symbol=}@var{symbolname}]
1012 [@option{--localize-hidden}]
1013 [@option{-L} @var{symbolname}|@option{--localize-symbol=}@var{symbolname}]
1014 [@option{--globalize-symbol=}@var{symbolname}]
1015 [@option{-W} @var{symbolname}|@option{--weaken-symbol=}@var{symbolname}]
1016 [@option{-w}|@option{--wildcard}]
1017 [@option{-x}|@option{--discard-all}]
1018 [@option{-X}|@option{--discard-locals}]
1019 [@option{-b} @var{byte}|@option{--byte=}@var{byte}]
1020 [@option{-i} @var{interleave}|@option{--interleave=}@var{interleave}]
1021 [@option{-j} @var{sectionname}|@option{--only-section=}@var{sectionname}]
1022 [@option{-R} @var{sectionname}|@option{--remove-section=}@var{sectionname}]
1023 [@option{-p}|@option{--preserve-dates}]
1024 [@option{--debugging}]
1025 [@option{--gap-fill=}@var{val}]
1026 [@option{--pad-to=}@var{address}]
1027 [@option{--set-start=}@var{val}]
1028 [@option{--adjust-start=}@var{incr}]
1029 [@option{--change-addresses=}@var{incr}]
1030 [@option{--change-section-address} @var{section}@{=,+,-@}@var{val}]
1031 [@option{--change-section-lma} @var{section}@{=,+,-@}@var{val}]
1032 [@option{--change-section-vma} @var{section}@{=,+,-@}@var{val}]
1033 [@option{--change-warnings}] [@option{--no-change-warnings}]
1034 [@option{--set-section-flags} @var{section}=@var{flags}]
1035 [@option{--add-section} @var{sectionname}=@var{filename}]
1036 [@option{--rename-section} @var{oldname}=@var{newname}[,@var{flags}]]
1037 [@option{--long-section-names} @{enable,disable,keep@}]
1038 [@option{--change-leading-char}] [@option{--remove-leading-char}]
1039 [@option{--reverse-bytes=}@var{num}]
1040 [@option{--srec-len=}@var{ival}] [@option{--srec-forceS3}]
1041 [@option{--redefine-sym} @var{old}=@var{new}]
1042 [@option{--redefine-syms=}@var{filename}]
1043 [@option{--weaken}]
1044 [@option{--keep-symbols=}@var{filename}]
1045 [@option{--strip-symbols=}@var{filename}]
1046 [@option{--strip-unneeded-symbols=}@var{filename}]
1047 [@option{--keep-global-symbols=}@var{filename}]
1048 [@option{--localize-symbols=}@var{filename}]
1049 [@option{--globalize-symbols=}@var{filename}]
1050 [@option{--weaken-symbols=}@var{filename}]
1051 [@option{--alt-machine-code=}@var{index}]
1052 [@option{--prefix-symbols=}@var{string}]
1053 [@option{--prefix-sections=}@var{string}]
1054 [@option{--prefix-alloc-sections=}@var{string}]
1055 [@option{--add-gnu-debuglink=}@var{path-to-file}]
1056 [@option{--keep-file-symbols}]
1057 [@option{--only-keep-debug}]
1058 [@option{--extract-symbol}]
1059 [@option{--writable-text}]
1060 [@option{--readonly-text}]
1061 [@option{--pure}]
1062 [@option{--impure}]
1063 [@option{--file-alignment=}@var{num}]
1064 [@option{--heap=}@var{size}]
1065 [@option{--image-base=}@var{address}]
1066 [@option{--section-alignment=}@var{num}]
1067 [@option{--stack=}@var{size}]
1068 [@option{--subsystem=}@var{which}:@var{major}.@var{minor}]
1069 [@option{-v}|@option{--verbose}]
1070 [@option{-V}|@option{--version}]
1071 [@option{--help}] [@option{--info}]
1072 @var{infile} [@var{outfile}]
1073 @c man end
1074 @end smallexample
1075
1076 @c man begin DESCRIPTION objcopy
1077 The @sc{gnu} @command{objcopy} utility copies the contents of an object
1078 file to another. @command{objcopy} uses the @sc{gnu} @sc{bfd} Library to
1079 read and write the object files. It can write the destination object
1080 file in a format different from that of the source object file. The
1081 exact behavior of @command{objcopy} is controlled by command-line options.
1082 Note that @command{objcopy} should be able to copy a fully linked file
1083 between any two formats. However, copying a relocatable object file
1084 between any two formats may not work as expected.
1085
1086 @command{objcopy} creates temporary files to do its translations and
1087 deletes them afterward. @command{objcopy} uses @sc{bfd} to do all its
1088 translation work; it has access to all the formats described in @sc{bfd}
1089 and thus is able to recognize most formats without being told
1090 explicitly. @xref{BFD,,BFD,ld.info,Using LD}.
1091
1092 @command{objcopy} can be used to generate S-records by using an output
1093 target of @samp{srec} (e.g., use @samp{-O srec}).
1094
1095 @command{objcopy} can be used to generate a raw binary file by using an
1096 output target of @samp{binary} (e.g., use @option{-O binary}). When
1097 @command{objcopy} generates a raw binary file, it will essentially produce
1098 a memory dump of the contents of the input object file. All symbols and
1099 relocation information will be discarded. The memory dump will start at
1100 the load address of the lowest section copied into the output file.
1101
1102 When generating an S-record or a raw binary file, it may be helpful to
1103 use @option{-S} to remove sections containing debugging information. In
1104 some cases @option{-R} will be useful to remove sections which contain
1105 information that is not needed by the binary file.
1106
1107 Note---@command{objcopy} is not able to change the endianness of its input
1108 files. If the input format has an endianness (some formats do not),
1109 @command{objcopy} can only copy the inputs into file formats that have the
1110 same endianness or which have no endianness (e.g., @samp{srec}).
1111 (However, see the @option{--reverse-bytes} option.)
1112
1113 @c man end
1114
1115 @c man begin OPTIONS objcopy
1116
1117 @table @env
1118 @item @var{infile}
1119 @itemx @var{outfile}
1120 The input and output files, respectively.
1121 If you do not specify @var{outfile}, @command{objcopy} creates a
1122 temporary file and destructively renames the result with
1123 the name of @var{infile}.
1124
1125 @item -I @var{bfdname}
1126 @itemx --input-target=@var{bfdname}
1127 Consider the source file's object format to be @var{bfdname}, rather than
1128 attempting to deduce it. @xref{Target Selection}, for more information.
1129
1130 @item -O @var{bfdname}
1131 @itemx --output-target=@var{bfdname}
1132 Write the output file using the object format @var{bfdname}.
1133 @xref{Target Selection}, for more information.
1134
1135 @item -F @var{bfdname}
1136 @itemx --target=@var{bfdname}
1137 Use @var{bfdname} as the object format for both the input and the output
1138 file; i.e., simply transfer data from source to destination with no
1139 translation. @xref{Target Selection}, for more information.
1140
1141 @item -B @var{bfdarch}
1142 @itemx --binary-architecture=@var{bfdarch}
1143 Useful when transforming a architecture-less input file into an object file.
1144 In this case the output architecture can be set to @var{bfdarch}. This
1145 option will be ignored if the input file has a known @var{bfdarch}. You
1146 can access this binary data inside a program by referencing the special
1147 symbols that are created by the conversion process. These symbols are
1148 called _binary_@var{objfile}_start, _binary_@var{objfile}_end and
1149 _binary_@var{objfile}_size. e.g. you can transform a picture file into
1150 an object file and then access it in your code using these symbols.
1151
1152 @item -j @var{sectionname}
1153 @itemx --only-section=@var{sectionname}
1154 Copy only the named section from the input file to the output file.
1155 This option may be given more than once. Note that using this option
1156 inappropriately may make the output file unusable.
1157
1158 @item -R @var{sectionname}
1159 @itemx --remove-section=@var{sectionname}
1160 Remove any section named @var{sectionname} from the output file. This
1161 option may be given more than once. Note that using this option
1162 inappropriately may make the output file unusable.
1163
1164 @item -S
1165 @itemx --strip-all
1166 Do not copy relocation and symbol information from the source file.
1167
1168 @item -g
1169 @itemx --strip-debug
1170 Do not copy debugging symbols or sections from the source file.
1171
1172 @item --strip-unneeded
1173 Strip all symbols that are not needed for relocation processing.
1174
1175 @item -K @var{symbolname}
1176 @itemx --keep-symbol=@var{symbolname}
1177 When stripping symbols, keep symbol @var{symbolname} even if it would
1178 normally be stripped. This option may be given more than once.
1179
1180 @item -N @var{symbolname}
1181 @itemx --strip-symbol=@var{symbolname}
1182 Do not copy symbol @var{symbolname} from the source file. This option
1183 may be given more than once.
1184
1185 @item --strip-unneeded-symbol=@var{symbolname}
1186 Do not copy symbol @var{symbolname} from the source file unless it is needed
1187 by a relocation. This option may be given more than once.
1188
1189 @item -G @var{symbolname}
1190 @itemx --keep-global-symbol=@var{symbolname}
1191 Keep only symbol @var{symbolname} global. Make all other symbols local
1192 to the file, so that they are not visible externally. This option may
1193 be given more than once.
1194
1195 @item --localize-hidden
1196 In an ELF object, mark all symbols that have hidden or internal visibility
1197 as local. This option applies on top of symbol-specific localization options
1198 such as @option{-L}.
1199
1200 @item -L @var{symbolname}
1201 @itemx --localize-symbol=@var{symbolname}
1202 Make symbol @var{symbolname} local to the file, so that it is not
1203 visible externally. This option may be given more than once.
1204
1205 @item -W @var{symbolname}
1206 @itemx --weaken-symbol=@var{symbolname}
1207 Make symbol @var{symbolname} weak. This option may be given more than once.
1208
1209 @item --globalize-symbol=@var{symbolname}
1210 Give symbol @var{symbolname} global scoping so that it is visible
1211 outside of the file in which it is defined. This option may be given
1212 more than once.
1213
1214 @item -w
1215 @itemx --wildcard
1216 Permit regular expressions in @var{symbolname}s used in other command
1217 line options. The question mark (?), asterisk (*), backslash (\) and
1218 square brackets ([]) operators can be used anywhere in the symbol
1219 name. If the first character of the symbol name is the exclamation
1220 point (!) then the sense of the switch is reversed for that symbol.
1221 For example:
1222
1223 @smallexample
1224 -w -W !foo -W fo*
1225 @end smallexample
1226
1227 would cause objcopy to weaken all symbols that start with ``fo''
1228 except for the symbol ``foo''.
1229
1230 @item -x
1231 @itemx --discard-all
1232 Do not copy non-global symbols from the source file.
1233 @c FIXME any reason to prefer "non-global" to "local" here?
1234
1235 @item -X
1236 @itemx --discard-locals
1237 Do not copy compiler-generated local symbols.
1238 (These usually start with @samp{L} or @samp{.}.)
1239
1240 @item -b @var{byte}
1241 @itemx --byte=@var{byte}
1242 Keep only every @var{byte}th byte of the input file (header data is not
1243 affected). @var{byte} can be in the range from 0 to @var{interleave}-1,
1244 where @var{interleave} is given by the @option{-i} or @option{--interleave}
1245 option, or the default of 4. This option is useful for creating files
1246 to program @sc{rom}. It is typically used with an @code{srec} output
1247 target.
1248
1249 @item -i @var{interleave}
1250 @itemx --interleave=@var{interleave}
1251 Only copy one out of every @var{interleave} bytes. Select which byte to
1252 copy with the @option{-b} or @option{--byte} option. The default is 4.
1253 @command{objcopy} ignores this option if you do not specify either @option{-b} or
1254 @option{--byte}.
1255
1256 @item -p
1257 @itemx --preserve-dates
1258 Set the access and modification dates of the output file to be the same
1259 as those of the input file.
1260
1261 @item --debugging
1262 Convert debugging information, if possible. This is not the default
1263 because only certain debugging formats are supported, and the
1264 conversion process can be time consuming.
1265
1266 @item --gap-fill @var{val}
1267 Fill gaps between sections with @var{val}. This operation applies to
1268 the @emph{load address} (LMA) of the sections. It is done by increasing
1269 the size of the section with the lower address, and filling in the extra
1270 space created with @var{val}.
1271
1272 @item --pad-to @var{address}
1273 Pad the output file up to the load address @var{address}. This is
1274 done by increasing the size of the last section. The extra space is
1275 filled in with the value specified by @option{--gap-fill} (default zero).
1276
1277 @item --set-start @var{val}
1278 Set the start address of the new file to @var{val}. Not all object file
1279 formats support setting the start address.
1280
1281 @item --change-start @var{incr}
1282 @itemx --adjust-start @var{incr}
1283 @cindex changing start address
1284 Change the start address by adding @var{incr}. Not all object file
1285 formats support setting the start address.
1286
1287 @item --change-addresses @var{incr}
1288 @itemx --adjust-vma @var{incr}
1289 @cindex changing object addresses
1290 Change the VMA and LMA addresses of all sections, as well as the start
1291 address, by adding @var{incr}. Some object file formats do not permit
1292 section addresses to be changed arbitrarily. Note that this does not
1293 relocate the sections; if the program expects sections to be loaded at a
1294 certain address, and this option is used to change the sections such
1295 that they are loaded at a different address, the program may fail.
1296
1297 @item --change-section-address @var{section}@{=,+,-@}@var{val}
1298 @itemx --adjust-section-vma @var{section}@{=,+,-@}@var{val}
1299 @cindex changing section address
1300 Set or change both the VMA address and the LMA address of the named
1301 @var{section}. If @samp{=} is used, the section address is set to
1302 @var{val}. Otherwise, @var{val} is added to or subtracted from the
1303 section address. See the comments under @option{--change-addresses},
1304 above. If @var{section} does not exist in the input file, a warning will
1305 be issued, unless @option{--no-change-warnings} is used.
1306
1307 @item --change-section-lma @var{section}@{=,+,-@}@var{val}
1308 @cindex changing section LMA
1309 Set or change the LMA address of the named @var{section}. The LMA
1310 address is the address where the section will be loaded into memory at
1311 program load time. Normally this is the same as the VMA address, which
1312 is the address of the section at program run time, but on some systems,
1313 especially those where a program is held in ROM, the two can be
1314 different. If @samp{=} is used, the section address is set to
1315 @var{val}. Otherwise, @var{val} is added to or subtracted from the
1316 section address. See the comments under @option{--change-addresses},
1317 above. If @var{section} does not exist in the input file, a warning
1318 will be issued, unless @option{--no-change-warnings} is used.
1319
1320 @item --change-section-vma @var{section}@{=,+,-@}@var{val}
1321 @cindex changing section VMA
1322 Set or change the VMA address of the named @var{section}. The VMA
1323 address is the address where the section will be located once the
1324 program has started executing. Normally this is the same as the LMA
1325 address, which is the address where the section will be loaded into
1326 memory, but on some systems, especially those where a program is held in
1327 ROM, the two can be different. If @samp{=} is used, the section address
1328 is set to @var{val}. Otherwise, @var{val} is added to or subtracted
1329 from the section address. See the comments under
1330 @option{--change-addresses}, above. If @var{section} does not exist in
1331 the input file, a warning will be issued, unless
1332 @option{--no-change-warnings} is used.
1333
1334 @item --change-warnings
1335 @itemx --adjust-warnings
1336 If @option{--change-section-address} or @option{--change-section-lma} or
1337 @option{--change-section-vma} is used, and the named section does not
1338 exist, issue a warning. This is the default.
1339
1340 @item --no-change-warnings
1341 @itemx --no-adjust-warnings
1342 Do not issue a warning if @option{--change-section-address} or
1343 @option{--adjust-section-lma} or @option{--adjust-section-vma} is used, even
1344 if the named section does not exist.
1345
1346 @item --set-section-flags @var{section}=@var{flags}
1347 Set the flags for the named section. The @var{flags} argument is a
1348 comma separated string of flag names. The recognized names are
1349 @samp{alloc}, @samp{contents}, @samp{load}, @samp{noload},
1350 @samp{readonly}, @samp{code}, @samp{data}, @samp{rom}, @samp{share}, and
1351 @samp{debug}. You can set the @samp{contents} flag for a section which
1352 does not have contents, but it is not meaningful to clear the
1353 @samp{contents} flag of a section which does have contents--just remove
1354 the section instead. Not all flags are meaningful for all object file
1355 formats.
1356
1357 @item --add-section @var{sectionname}=@var{filename}
1358 Add a new section named @var{sectionname} while copying the file. The
1359 contents of the new section are taken from the file @var{filename}. The
1360 size of the section will be the size of the file. This option only
1361 works on file formats which can support sections with arbitrary names.
1362
1363 @item --rename-section @var{oldname}=@var{newname}[,@var{flags}]
1364 Rename a section from @var{oldname} to @var{newname}, optionally
1365 changing the section's flags to @var{flags} in the process. This has
1366 the advantage over usng a linker script to perform the rename in that
1367 the output stays as an object file and does not become a linked
1368 executable.
1369
1370 This option is particularly helpful when the input format is binary,
1371 since this will always create a section called .data. If for example,
1372 you wanted instead to create a section called .rodata containing binary
1373 data you could use the following command line to achieve it:
1374
1375 @smallexample
1376 objcopy -I binary -O <output_format> -B <architecture> \
1377 --rename-section .data=.rodata,alloc,load,readonly,data,contents \
1378 <input_binary_file> <output_object_file>
1379 @end smallexample
1380
1381 @item --long-section-names @{enable,disable,keep@}
1382 Controls the handling of long section names when processing @code{COFF}
1383 and @code{PE-COFF} object formats. The default behaviour, @samp{keep},
1384 is to preserve long section names if any are present in the input file.
1385 The @samp{enable} and @samp{disable} options forcibly enable or disable
1386 the use of long section names in the output object; when @samp{disable}
1387 is in effect, any long section names in the input object will be truncated.
1388 The @samp{enable} option will only emit long section names if any are
1389 present in the inputs; this is mostly the same as @samp{keep}, but it
1390 is left undefined whether the @samp{enable} option might force the
1391 creation of an empty string table in the output file.
1392
1393 @item --change-leading-char
1394 Some object file formats use special characters at the start of
1395 symbols. The most common such character is underscore, which compilers
1396 often add before every symbol. This option tells @command{objcopy} to
1397 change the leading character of every symbol when it converts between
1398 object file formats. If the object file formats use the same leading
1399 character, this option has no effect. Otherwise, it will add a
1400 character, or remove a character, or change a character, as
1401 appropriate.
1402
1403 @item --remove-leading-char
1404 If the first character of a global symbol is a special symbol leading
1405 character used by the object file format, remove the character. The
1406 most common symbol leading character is underscore. This option will
1407 remove a leading underscore from all global symbols. This can be useful
1408 if you want to link together objects of different file formats with
1409 different conventions for symbol names. This is different from
1410 @option{--change-leading-char} because it always changes the symbol name
1411 when appropriate, regardless of the object file format of the output
1412 file.
1413
1414 @item --reverse-bytes=@var{num}
1415 Reverse the bytes in a section with output contents. A section length must
1416 be evenly divisible by the value given in order for the swap to be able to
1417 take place. Reversing takes place before the interleaving is performed.
1418
1419 This option is used typically in generating ROM images for problematic
1420 target systems. For example, on some target boards, the 32-bit words
1421 fetched from 8-bit ROMs are re-assembled in little-endian byte order
1422 regardless of the CPU byte order. Depending on the programming model, the
1423 endianness of the ROM may need to be modified.
1424
1425 Consider a simple file with a section containing the following eight
1426 bytes: @code{12345678}.
1427
1428 Using @samp{--reverse-bytes=2} for the above example, the bytes in the
1429 output file would be ordered @code{21436587}.
1430
1431 Using @samp{--reverse-bytes=4} for the above example, the bytes in the
1432 output file would be ordered @code{43218765}.
1433
1434 By using @samp{--reverse-bytes=2} for the above example, followed by
1435 @samp{--reverse-bytes=4} on the output file, the bytes in the second
1436 output file would be ordered @code{34127856}.
1437
1438 @item --srec-len=@var{ival}
1439 Meaningful only for srec output. Set the maximum length of the Srecords
1440 being produced to @var{ival}. This length covers both address, data and
1441 crc fields.
1442
1443 @item --srec-forceS3
1444 Meaningful only for srec output. Avoid generation of S1/S2 records,
1445 creating S3-only record format.
1446
1447 @item --redefine-sym @var{old}=@var{new}
1448 Change the name of a symbol @var{old}, to @var{new}. This can be useful
1449 when one is trying link two things together for which you have no
1450 source, and there are name collisions.
1451
1452 @item --redefine-syms=@var{filename}
1453 Apply @option{--redefine-sym} to each symbol pair "@var{old} @var{new}"
1454 listed in the file @var{filename}. @var{filename} is simply a flat file,
1455 with one symbol pair per line. Line comments may be introduced by the hash
1456 character. This option may be given more than once.
1457
1458 @item --weaken
1459 Change all global symbols in the file to be weak. This can be useful
1460 when building an object which will be linked against other objects using
1461 the @option{-R} option to the linker. This option is only effective when
1462 using an object file format which supports weak symbols.
1463
1464 @item --keep-symbols=@var{filename}
1465 Apply @option{--keep-symbol} option to each symbol listed in the file
1466 @var{filename}. @var{filename} is simply a flat file, with one symbol
1467 name per line. Line comments may be introduced by the hash character.
1468 This option may be given more than once.
1469
1470 @item --strip-symbols=@var{filename}
1471 Apply @option{--strip-symbol} option to each symbol listed in the file
1472 @var{filename}. @var{filename} is simply a flat file, with one symbol
1473 name per line. Line comments may be introduced by the hash character.
1474 This option may be given more than once.
1475
1476 @item --strip-unneeded-symbols=@var{filename}
1477 Apply @option{--strip-unneeded-symbol} option to each symbol listed in
1478 the file @var{filename}. @var{filename} is simply a flat file, with one
1479 symbol name per line. Line comments may be introduced by the hash
1480 character. This option may be given more than once.
1481
1482 @item --keep-global-symbols=@var{filename}
1483 Apply @option{--keep-global-symbol} option to each symbol listed in the
1484 file @var{filename}. @var{filename} is simply a flat file, with one
1485 symbol name per line. Line comments may be introduced by the hash
1486 character. This option may be given more than once.
1487
1488 @item --localize-symbols=@var{filename}
1489 Apply @option{--localize-symbol} option to each symbol listed in the file
1490 @var{filename}. @var{filename} is simply a flat file, with one symbol
1491 name per line. Line comments may be introduced by the hash character.
1492 This option may be given more than once.
1493
1494 @item --globalize-symbols=@var{filename}
1495 Apply @option{--globalize-symbol} option to each symbol listed in the file
1496 @var{filename}. @var{filename} is simply a flat file, with one symbol
1497 name per line. Line comments may be introduced by the hash character.
1498 This option may be given more than once.
1499
1500 @item --weaken-symbols=@var{filename}
1501 Apply @option{--weaken-symbol} option to each symbol listed in the file
1502 @var{filename}. @var{filename} is simply a flat file, with one symbol
1503 name per line. Line comments may be introduced by the hash character.
1504 This option may be given more than once.
1505
1506 @item --alt-machine-code=@var{index}
1507 If the output architecture has alternate machine codes, use the
1508 @var{index}th code instead of the default one. This is useful in case
1509 a machine is assigned an official code and the tool-chain adopts the
1510 new code, but other applications still depend on the original code
1511 being used. For ELF based architectures if the @var{index}
1512 alternative does not exist then the value is treated as an absolute
1513 number to be stored in the e_machine field of the ELF header.
1514
1515 @item --writable-text
1516 Mark the output text as writable. This option isn't meaningful for all
1517 object file formats.
1518
1519 @item --readonly-text
1520 Make the output text write protected. This option isn't meaningful for all
1521 object file formats.
1522
1523 @item --pure
1524 Mark the output file as demand paged. This option isn't meaningful for all
1525 object file formats.
1526
1527 @item --impure
1528 Mark the output file as impure. This option isn't meaningful for all
1529 object file formats.
1530
1531 @item --prefix-symbols=@var{string}
1532 Prefix all symbols in the output file with @var{string}.
1533
1534 @item --prefix-sections=@var{string}
1535 Prefix all section names in the output file with @var{string}.
1536
1537 @item --prefix-alloc-sections=@var{string}
1538 Prefix all the names of all allocated sections in the output file with
1539 @var{string}.
1540
1541 @item --add-gnu-debuglink=@var{path-to-file}
1542 Creates a .gnu_debuglink section which contains a reference to @var{path-to-file}
1543 and adds it to the output file.
1544
1545 @item --keep-file-symbols
1546 When stripping a file, perhaps with @option{--strip-debug} or
1547 @option{--strip-unneeded}, retain any symbols specifying source file names,
1548 which would otherwise get stripped.
1549
1550 @item --only-keep-debug
1551 Strip a file, removing contents of any sections that would not be
1552 stripped by @option{--strip-debug} and leaving the debugging sections
1553 intact. In ELF files, this preserves all note sections in the output.
1554
1555 The intention is that this option will be used in conjunction with
1556 @option{--add-gnu-debuglink} to create a two part executable. One a
1557 stripped binary which will occupy less space in RAM and in a
1558 distribution and the second a debugging information file which is only
1559 needed if debugging abilities are required. The suggested procedure
1560 to create these files is as follows:
1561
1562 @enumerate
1563 @item Link the executable as normal. Assuming that is is called
1564 @code{foo} then...
1565 @item Run @code{objcopy --only-keep-debug foo foo.dbg} to
1566 create a file containing the debugging info.
1567 @item Run @code{objcopy --strip-debug foo} to create a
1568 stripped executable.
1569 @item Run @code{objcopy --add-gnu-debuglink=foo.dbg foo}
1570 to add a link to the debugging info into the stripped executable.
1571 @end enumerate
1572
1573 Note---the choice of @code{.dbg} as an extension for the debug info
1574 file is arbitrary. Also the @code{--only-keep-debug} step is
1575 optional. You could instead do this:
1576
1577 @enumerate
1578 @item Link the executable as normal.
1579 @item Copy @code{foo} to @code{foo.full}
1580 @item Run @code{objcopy --strip-debug foo}
1581 @item Run @code{objcopy --add-gnu-debuglink=foo.full foo}
1582 @end enumerate
1583
1584 i.e., the file pointed to by the @option{--add-gnu-debuglink} can be the
1585 full executable. It does not have to be a file created by the
1586 @option{--only-keep-debug} switch.
1587
1588 Note---this switch is only intended for use on fully linked files. It
1589 does not make sense to use it on object files where the debugging
1590 information may be incomplete. Besides the gnu_debuglink feature
1591 currently only supports the presence of one filename containing
1592 debugging information, not multiple filenames on a one-per-object-file
1593 basis.
1594
1595 @item --file-alignment @var{num}
1596 Specify the file alignment. Sections in the file will always begin at
1597 file offsets which are multiples of this number. This defaults to
1598 512.
1599 [This option is specific to PE targets.]
1600
1601 @item --heap @var{reserve}
1602 @itemx --heap @var{reserve},@var{commit}
1603 Specify the number of bytes of memory to reserve (and optionally commit)
1604 to be used as heap for this program.
1605 [This option is specific to PE targets.]
1606
1607 @item --image-base @var{value}
1608 Use @var{value} as the base address of your program or dll. This is
1609 the lowest memory location that will be used when your program or dll
1610 is loaded. To reduce the need to relocate and improve performance of
1611 your dlls, each should have a unique base address and not overlap any
1612 other dlls. The default is 0x400000 for executables, and 0x10000000
1613 for dlls.
1614 [This option is specific to PE targets.]
1615
1616 @item --section-alignment @var{num}
1617 Sets the section alignment. Sections in memory will always begin at
1618 addresses which are a multiple of this number. Defaults to 0x1000.
1619 [This option is specific to PE targets.]
1620
1621 @item --stack @var{reserve}
1622 @itemx --stack @var{reserve},@var{commit}
1623 Specify the number of bytes of memory to reserve (and optionally commit)
1624 to be used as stack for this program.
1625 [This option is specific to PE targets.]
1626
1627 @item --subsystem @var{which}
1628 @itemx --subsystem @var{which}:@var{major}
1629 @itemx --subsystem @var{which}:@var{major}.@var{minor}
1630 Specifies the subsystem under which your program will execute. The
1631 legal values for @var{which} are @code{native}, @code{windows},
1632 @code{console}, @code{posix}, @code{efi-app}, @code{efi-bsd},
1633 @code{efi-rtd}, @code{sal-rtd}, and @code{xbox}. You may optionally set
1634 the subsystem version also. Numeric values are also accepted for
1635 @var{which}.
1636 [This option is specific to PE targets.]
1637
1638 @item --extract-symbol
1639 Keep the file's section flags and symbols but remove all section data.
1640 Specifically, the option:
1641
1642 @itemize
1643 @item removes the contents of all sections;
1644 @item sets the size of every section to zero; and
1645 @item sets the file's start address to zero.
1646 @end itemize
1647
1648 This option is used to build a @file{.sym} file for a VxWorks kernel.
1649 It can also be a useful way of reducing the size of a @option{--just-symbols}
1650 linker input file.
1651
1652 @item -V
1653 @itemx --version
1654 Show the version number of @command{objcopy}.
1655
1656 @item -v
1657 @itemx --verbose
1658 Verbose output: list all object files modified. In the case of
1659 archives, @samp{objcopy -V} lists all members of the archive.
1660
1661 @item --help
1662 Show a summary of the options to @command{objcopy}.
1663
1664 @item --info
1665 Display a list showing all architectures and object formats available.
1666 @end table
1667
1668 @c man end
1669
1670 @ignore
1671 @c man begin SEEALSO objcopy
1672 ld(1), objdump(1), and the Info entries for @file{binutils}.
1673 @c man end
1674 @end ignore
1675
1676 @node objdump
1677 @chapter objdump
1678
1679 @cindex object file information
1680 @kindex objdump
1681
1682 @c man title objdump display information from object files.
1683
1684 @smallexample
1685 @c man begin SYNOPSIS objdump
1686 objdump [@option{-a}|@option{--archive-headers}]
1687 [@option{-b} @var{bfdname}|@option{--target=@var{bfdname}}]
1688 [@option{-C}|@option{--demangle}[=@var{style}] ]
1689 [@option{-d}|@option{--disassemble}]
1690 [@option{-D}|@option{--disassemble-all}]
1691 [@option{-z}|@option{--disassemble-zeroes}]
1692 [@option{-EB}|@option{-EL}|@option{--endian=}@{big | little @}]
1693 [@option{-f}|@option{--file-headers}]
1694 [@option{-F}|@option{--file-offsets}]
1695 [@option{--file-start-context}]
1696 [@option{-g}|@option{--debugging}]
1697 [@option{-e}|@option{--debugging-tags}]
1698 [@option{-h}|@option{--section-headers}|@option{--headers}]
1699 [@option{-i}|@option{--info}]
1700 [@option{-j} @var{section}|@option{--section=}@var{section}]
1701 [@option{-l}|@option{--line-numbers}]
1702 [@option{-S}|@option{--source}]
1703 [@option{-m} @var{machine}|@option{--architecture=}@var{machine}]
1704 [@option{-M} @var{options}|@option{--disassembler-options=}@var{options}]
1705 [@option{-p}|@option{--private-headers}]
1706 [@option{-r}|@option{--reloc}]
1707 [@option{-R}|@option{--dynamic-reloc}]
1708 [@option{-s}|@option{--full-contents}]
1709 [@option{-W[lLiaprmfFsoRt]}|
1710 @option{--dwarf}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes]]
1711 [@option{-G}|@option{--stabs}]
1712 [@option{-t}|@option{--syms}]
1713 [@option{-T}|@option{--dynamic-syms}]
1714 [@option{-x}|@option{--all-headers}]
1715 [@option{-w}|@option{--wide}]
1716 [@option{--start-address=}@var{address}]
1717 [@option{--stop-address=}@var{address}]
1718 [@option{--prefix-addresses}]
1719 [@option{--[no-]show-raw-insn}]
1720 [@option{--adjust-vma=}@var{offset}]
1721 [@option{--special-syms}]
1722 [@option{--prefix=}@var{prefix}]
1723 [@option{--prefix-strip=}@var{level}]
1724 [@option{--insn-width=}@var{width}]
1725 [@option{-V}|@option{--version}]
1726 [@option{-H}|@option{--help}]
1727 @var{objfile}@dots{}
1728 @c man end
1729 @end smallexample
1730
1731 @c man begin DESCRIPTION objdump
1732
1733 @command{objdump} displays information about one or more object files.
1734 The options control what particular information to display. This
1735 information is mostly useful to programmers who are working on the
1736 compilation tools, as opposed to programmers who just want their
1737 program to compile and work.
1738
1739 @var{objfile}@dots{} are the object files to be examined. When you
1740 specify archives, @command{objdump} shows information on each of the member
1741 object files.
1742
1743 @c man end
1744
1745 @c man begin OPTIONS objdump
1746
1747 The long and short forms of options, shown here as alternatives, are
1748 equivalent. At least one option from the list
1749 @option{-a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-r,-R,-s,-S,-t,-T,-V,-x} must be given.
1750
1751 @table @env
1752 @item -a
1753 @itemx --archive-header
1754 @cindex archive headers
1755 If any of the @var{objfile} files are archives, display the archive
1756 header information (in a format similar to @samp{ls -l}). Besides the
1757 information you could list with @samp{ar tv}, @samp{objdump -a} shows
1758 the object file format of each archive member.
1759
1760 @item --adjust-vma=@var{offset}
1761 @cindex section addresses in objdump
1762 @cindex VMA in objdump
1763 When dumping information, first add @var{offset} to all the section
1764 addresses. This is useful if the section addresses do not correspond to
1765 the symbol table, which can happen when putting sections at particular
1766 addresses when using a format which can not represent section addresses,
1767 such as a.out.
1768
1769 @item -b @var{bfdname}
1770 @itemx --target=@var{bfdname}
1771 @cindex object code format
1772 Specify that the object-code format for the object files is
1773 @var{bfdname}. This option may not be necessary; @var{objdump} can
1774 automatically recognize many formats.
1775
1776 For example,
1777 @example
1778 objdump -b oasys -m vax -h fu.o
1779 @end example
1780 @noindent
1781 displays summary information from the section headers (@option{-h}) of
1782 @file{fu.o}, which is explicitly identified (@option{-m}) as a VAX object
1783 file in the format produced by Oasys compilers. You can list the
1784 formats available with the @option{-i} option.
1785 @xref{Target Selection}, for more information.
1786
1787 @item -C
1788 @itemx --demangle[=@var{style}]
1789 @cindex demangling in objdump
1790 Decode (@dfn{demangle}) low-level symbol names into user-level names.
1791 Besides removing any initial underscore prepended by the system, this
1792 makes C++ function names readable. Different compilers have different
1793 mangling styles. The optional demangling style argument can be used to
1794 choose an appropriate demangling style for your compiler. @xref{c++filt},
1795 for more information on demangling.
1796
1797 @item -g
1798 @itemx --debugging
1799 Display debugging information. This attempts to parse STABS and IEEE
1800 debugging format information stored in the file and print it out using
1801 a C like syntax. If neither of these formats are found this option
1802 falls back on the @option{-W} option to print any DWARF information in
1803 the file.
1804
1805 @item -e
1806 @itemx --debugging-tags
1807 Like @option{-g}, but the information is generated in a format compatible
1808 with ctags tool.
1809
1810 @item -d
1811 @itemx --disassemble
1812 @cindex disassembling object code
1813 @cindex machine instructions
1814 Display the assembler mnemonics for the machine instructions from
1815 @var{objfile}. This option only disassembles those sections which are
1816 expected to contain instructions.
1817
1818 @item -D
1819 @itemx --disassemble-all
1820 Like @option{-d}, but disassemble the contents of all sections, not just
1821 those expected to contain instructions.
1822
1823 If the target is an ARM architecture this switch also has the effect
1824 of forcing the disassembler to decode pieces of data found in code
1825 sections as if they were instructions.
1826
1827 @item --prefix-addresses
1828 When disassembling, print the complete address on each line. This is
1829 the older disassembly format.
1830
1831 @item -EB
1832 @itemx -EL
1833 @itemx --endian=@{big|little@}
1834 @cindex endianness
1835 @cindex disassembly endianness
1836 Specify the endianness of the object files. This only affects
1837 disassembly. This can be useful when disassembling a file format which
1838 does not describe endianness information, such as S-records.
1839
1840 @item -f
1841 @itemx --file-headers
1842 @cindex object file header
1843 Display summary information from the overall header of
1844 each of the @var{objfile} files.
1845
1846 @item -F
1847 @itemx --file-offsets
1848 @cindex object file offsets
1849 When disassembling sections, whenever a symbol is displayed, also
1850 display the file offset of the region of data that is about to be
1851 dumped. If zeroes are being skipped, then when disassembly resumes,
1852 tell the user how many zeroes were skipped and the file offset of the
1853 location from where the disassembly resumes. When dumping sections,
1854 display the file offset of the location from where the dump starts.
1855
1856 @item --file-start-context
1857 @cindex source code context
1858 Specify that when displaying interlisted source code/disassembly
1859 (assumes @option{-S}) from a file that has not yet been displayed, extend the
1860 context to the start of the file.
1861
1862 @item -h
1863 @itemx --section-headers
1864 @itemx --headers
1865 @cindex section headers
1866 Display summary information from the section headers of the
1867 object file.
1868
1869 File segments may be relocated to nonstandard addresses, for example by
1870 using the @option{-Ttext}, @option{-Tdata}, or @option{-Tbss} options to
1871 @command{ld}. However, some object file formats, such as a.out, do not
1872 store the starting address of the file segments. In those situations,
1873 although @command{ld} relocates the sections correctly, using @samp{objdump
1874 -h} to list the file section headers cannot show the correct addresses.
1875 Instead, it shows the usual addresses, which are implicit for the
1876 target.
1877
1878 @item -H
1879 @itemx --help
1880 Print a summary of the options to @command{objdump} and exit.
1881
1882 @item -i
1883 @itemx --info
1884 @cindex architectures available
1885 @cindex object formats available
1886 Display a list showing all architectures and object formats available
1887 for specification with @option{-b} or @option{-m}.
1888
1889 @item -j @var{name}
1890 @itemx --section=@var{name}
1891 @cindex section information
1892 Display information only for section @var{name}.
1893
1894 @item -l
1895 @itemx --line-numbers
1896 @cindex source filenames for object files
1897 Label the display (using debugging information) with the filename and
1898 source line numbers corresponding to the object code or relocs shown.
1899 Only useful with @option{-d}, @option{-D}, or @option{-r}.
1900
1901 @item -m @var{machine}
1902 @itemx --architecture=@var{machine}
1903 @cindex architecture
1904 @cindex disassembly architecture
1905 Specify the architecture to use when disassembling object files. This
1906 can be useful when disassembling object files which do not describe
1907 architecture information, such as S-records. You can list the available
1908 architectures with the @option{-i} option.
1909
1910 If the target is an ARM architecture then this switch has an
1911 additional effect. It restricts the disassembly to only those
1912 instructions supported by the architecture specified by @var{machine}.
1913 If it is necessary to use this switch because the input file does not
1914 contain any architecture information, but it is also desired to
1915 disassemble all the instructions use @option{-marm}.
1916
1917 @item -M @var{options}
1918 @itemx --disassembler-options=@var{options}
1919 Pass target specific information to the disassembler. Only supported on
1920 some targets. If it is necessary to specify more than one
1921 disassembler option then multiple @option{-M} options can be used or
1922 can be placed together into a comma separated list.
1923
1924 If the target is an ARM architecture then this switch can be used to
1925 select which register name set is used during disassembler. Specifying
1926 @option{-M reg-names-std} (the default) will select the register names as
1927 used in ARM's instruction set documentation, but with register 13 called
1928 'sp', register 14 called 'lr' and register 15 called 'pc'. Specifying
1929 @option{-M reg-names-apcs} will select the name set used by the ARM
1930 Procedure Call Standard, whilst specifying @option{-M reg-names-raw} will
1931 just use @samp{r} followed by the register number.
1932
1933 There are also two variants on the APCS register naming scheme enabled
1934 by @option{-M reg-names-atpcs} and @option{-M reg-names-special-atpcs} which
1935 use the ARM/Thumb Procedure Call Standard naming conventions. (Either
1936 with the normal register names or the special register names).
1937
1938 This option can also be used for ARM architectures to force the
1939 disassembler to interpret all instructions as Thumb instructions by
1940 using the switch @option{--disassembler-options=force-thumb}. This can be
1941 useful when attempting to disassemble thumb code produced by other
1942 compilers.
1943
1944 For the x86, some of the options duplicate functions of the @option{-m}
1945 switch, but allow finer grained control. Multiple selections from the
1946 following may be specified as a comma separated string.
1947 @option{x86-64}, @option{i386} and @option{i8086} select disassembly for
1948 the given architecture. @option{intel} and @option{att} select between
1949 intel syntax mode and AT&T syntax mode.
1950 @option{intel-mnemonic} and @option{att-mnemonic} select between
1951 intel mnemonic mode and AT&T mnemonic mode. @option{intel-mnemonic}
1952 implies @option{intel} and @option{att-mnemonic} implies @option{att}.
1953 @option{addr64}, @option{addr32},
1954 @option{addr16}, @option{data32} and @option{data16} specify the default
1955 address size and operand size. These four options will be overridden if
1956 @option{x86-64}, @option{i386} or @option{i8086} appear later in the
1957 option string. Lastly, @option{suffix}, when in AT&T mode,
1958 instructs the disassembler to print a mnemonic suffix even when the
1959 suffix could be inferred by the operands.
1960
1961 For PowerPC, @option{booke} controls the disassembly of BookE
1962 instructions. @option{32} and @option{64} select PowerPC and
1963 PowerPC64 disassembly, respectively. @option{e300} selects
1964 disassembly for the e300 family. @option{440} selects disassembly for
1965 the PowerPC 440. @option{ppcps} selects disassembly for the paired
1966 single instructions of the PPC750CL.
1967
1968 For MIPS, this option controls the printing of instruction mnemonic
1969 names and register names in disassembled instructions. Multiple
1970 selections from the following may be specified as a comma separated
1971 string, and invalid options are ignored:
1972
1973 @table @code
1974 @item no-aliases
1975 Print the 'raw' instruction mnemonic instead of some pseudo
1976 instruction mnemonic. I.e., print 'daddu' or 'or' instead of 'move',
1977 'sll' instead of 'nop', etc.
1978
1979 @item gpr-names=@var{ABI}
1980 Print GPR (general-purpose register) names as appropriate
1981 for the specified ABI. By default, GPR names are selected according to
1982 the ABI of the binary being disassembled.
1983
1984 @item fpr-names=@var{ABI}
1985 Print FPR (floating-point register) names as
1986 appropriate for the specified ABI. By default, FPR numbers are printed
1987 rather than names.
1988
1989 @item cp0-names=@var{ARCH}
1990 Print CP0 (system control coprocessor; coprocessor 0) register names
1991 as appropriate for the CPU or architecture specified by
1992 @var{ARCH}. By default, CP0 register names are selected according to
1993 the architecture and CPU of the binary being disassembled.
1994
1995 @item hwr-names=@var{ARCH}
1996 Print HWR (hardware register, used by the @code{rdhwr} instruction) names
1997 as appropriate for the CPU or architecture specified by
1998 @var{ARCH}. By default, HWR names are selected according to
1999 the architecture and CPU of the binary being disassembled.
2000
2001 @item reg-names=@var{ABI}
2002 Print GPR and FPR names as appropriate for the selected ABI.
2003
2004 @item reg-names=@var{ARCH}
2005 Print CPU-specific register names (CP0 register and HWR names)
2006 as appropriate for the selected CPU or architecture.
2007 @end table
2008
2009 For any of the options listed above, @var{ABI} or
2010 @var{ARCH} may be specified as @samp{numeric} to have numbers printed
2011 rather than names, for the selected types of registers.
2012 You can list the available values of @var{ABI} and @var{ARCH} using
2013 the @option{--help} option.
2014
2015 For VAX, you can specify function entry addresses with @option{-M
2016 entry:0xf00ba}. You can use this multiple times to properly
2017 disassemble VAX binary files that don't contain symbol tables (like
2018 ROM dumps). In these cases, the function entry mask would otherwise
2019 be decoded as VAX instructions, which would probably lead the rest
2020 of the function being wrongly disassembled.
2021
2022 @item -p
2023 @itemx --private-headers
2024 Print information that is specific to the object file format. The exact
2025 information printed depends upon the object file format. For some
2026 object file formats, no additional information is printed.
2027
2028 @item -r
2029 @itemx --reloc
2030 @cindex relocation entries, in object file
2031 Print the relocation entries of the file. If used with @option{-d} or
2032 @option{-D}, the relocations are printed interspersed with the
2033 disassembly.
2034
2035 @item -R
2036 @itemx --dynamic-reloc
2037 @cindex dynamic relocation entries, in object file
2038 Print the dynamic relocation entries of the file. This is only
2039 meaningful for dynamic objects, such as certain types of shared
2040 libraries. As for @option{-r}, if used with @option{-d} or
2041 @option{-D}, the relocations are printed interspersed with the
2042 disassembly.
2043
2044 @item -s
2045 @itemx --full-contents
2046 @cindex sections, full contents
2047 @cindex object file sections
2048 Display the full contents of any sections requested. By default all
2049 non-empty sections are displayed.
2050
2051 @item -S
2052 @itemx --source
2053 @cindex source disassembly
2054 @cindex disassembly, with source
2055 Display source code intermixed with disassembly, if possible. Implies
2056 @option{-d}.
2057
2058 @item --prefix=@var{prefix}
2059 @cindex Add prefix to absolute paths
2060 Specify @var{prefix} to add to the absolute paths when used with
2061 @option{-S}.
2062
2063 @item --prefix-strip=@var{level}
2064 @cindex Strip absolute paths
2065 Indicate how many initial directory names to strip off the hardwired
2066 absolute paths. It has no effect without @option{--prefix=}@var{prefix}.
2067
2068 @item --show-raw-insn
2069 When disassembling instructions, print the instruction in hex as well as
2070 in symbolic form. This is the default except when
2071 @option{--prefix-addresses} is used.
2072
2073 @item --no-show-raw-insn
2074 When disassembling instructions, do not print the instruction bytes.
2075 This is the default when @option{--prefix-addresses} is used.
2076
2077 @item --insn-width=@var{width}
2078 @cindex Instruction width
2079 Display @var{width} bytes on a single line when disassembling
2080 instructions.
2081
2082 @item -W[lLiaprmfFsoRt]
2083 @itemx --dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes]
2084 @cindex DWARF
2085 @cindex debug symbols
2086 Displays the contents of the debug sections in the file, if any are
2087 present. If one of the optional letters or words follows the switch
2088 then only data found in those specific sections will be dumped.
2089
2090 @item -G
2091 @itemx --stabs
2092 @cindex stab
2093 @cindex .stab
2094 @cindex debug symbols
2095 @cindex ELF object file format
2096 Display the full contents of any sections requested. Display the
2097 contents of the .stab and .stab.index and .stab.excl sections from an
2098 ELF file. This is only useful on systems (such as Solaris 2.0) in which
2099 @code{.stab} debugging symbol-table entries are carried in an ELF
2100 section. In most other file formats, debugging symbol-table entries are
2101 interleaved with linkage symbols, and are visible in the @option{--syms}
2102 output.
2103 @ifclear man
2104 For more information on stabs symbols, see @ref{Top,Stabs,Stabs
2105 Overview,stabs.info, The ``stabs'' debug format}.
2106 @end ifclear
2107
2108 @item --start-address=@var{address}
2109 @cindex start-address
2110 Start displaying data at the specified address. This affects the output
2111 of the @option{-d}, @option{-r} and @option{-s} options.
2112
2113 @item --stop-address=@var{address}
2114 @cindex stop-address
2115 Stop displaying data at the specified address. This affects the output
2116 of the @option{-d}, @option{-r} and @option{-s} options.
2117
2118 @item -t
2119 @itemx --syms
2120 @cindex symbol table entries, printing
2121 Print the symbol table entries of the file.
2122 This is similar to the information provided by the @samp{nm} program,
2123 although the display format is different. The format of the output
2124 depends upon the format of the file being dumped, but there are two main
2125 types. One looks like this:
2126
2127 @smallexample
2128 [ 4](sec 3)(fl 0x00)(ty 0)(scl 3) (nx 1) 0x00000000 .bss
2129 [ 6](sec 1)(fl 0x00)(ty 0)(scl 2) (nx 0) 0x00000000 fred
2130 @end smallexample
2131
2132 where the number inside the square brackets is the number of the entry
2133 in the symbol table, the @var{sec} number is the section number, the
2134 @var{fl} value are the symbol's flag bits, the @var{ty} number is the
2135 symbol's type, the @var{scl} number is the symbol's storage class and
2136 the @var{nx} value is the number of auxilary entries associated with
2137 the symbol. The last two fields are the symbol's value and its name.
2138
2139 The other common output format, usually seen with ELF based files,
2140 looks like this:
2141
2142 @smallexample
2143 00000000 l d .bss 00000000 .bss
2144 00000000 g .text 00000000 fred
2145 @end smallexample
2146
2147 Here the first number is the symbol's value (sometimes refered to as
2148 its address). The next field is actually a set of characters and
2149 spaces indicating the flag bits that are set on the symbol. These
2150 characters are described below. Next is the section with which the
2151 symbol is associated or @emph{*ABS*} if the section is absolute (ie
2152 not connected with any section), or @emph{*UND*} if the section is
2153 referenced in the file being dumped, but not defined there.
2154
2155 After the section name comes another field, a number, which for common
2156 symbols is the alignment and for other symbol is the size. Finally
2157 the symbol's name is displayed.
2158
2159 The flag characters are divided into 7 groups as follows:
2160 @table @code
2161 @item l
2162 @itemx g
2163 @itemx u
2164 @itemx !
2165 The symbol is a local (l), global (g), unique global (u), neither
2166 global nor local (a space) or both global and local (!). A
2167 symbol can be neither local or global for a variety of reasons, e.g.,
2168 because it is used for debugging, but it is probably an indication of
2169 a bug if it is ever both local and global. Unique global symbols are
2170 a GNU extension to the standard set of ELF symbol bindings. For such
2171 a symbol the dynamic linker will make sure that in the entire process
2172 there is just one symbol with this name and type in use.
2173
2174 @item w
2175 The symbol is weak (w) or strong (a space).
2176
2177 @item C
2178 The symbol denotes a constructor (C) or an ordinary symbol (a space).
2179
2180 @item W
2181 The symbol is a warning (W) or a normal symbol (a space). A warning
2182 symbol's name is a message to be displayed if the symbol following the
2183 warning symbol is ever referenced.
2184
2185 @item I
2186 @item i
2187 The symbol is an indirect reference to another symbol (I), a function
2188 to be evaluated during reloc processing (i) or a normal symbol (a
2189 space).
2190
2191 @item d
2192 @itemx D
2193 The symbol is a debugging symbol (d) or a dynamic symbol (D) or a
2194 normal symbol (a space).
2195
2196 @item F
2197 @item f
2198 @item O
2199 The symbol is the name of a function (F) or a file (f) or an object
2200 (O) or just a normal symbol (a space).
2201 @end table
2202
2203 @item -T
2204 @itemx --dynamic-syms
2205 @cindex dynamic symbol table entries, printing
2206 Print the dynamic symbol table entries of the file. This is only
2207 meaningful for dynamic objects, such as certain types of shared
2208 libraries. This is similar to the information provided by the @samp{nm}
2209 program when given the @option{-D} (@option{--dynamic}) option.
2210
2211 @item --special-syms
2212 When displaying symbols include those which the target considers to be
2213 special in some way and which would not normally be of interest to the
2214 user.
2215
2216 @item -V
2217 @itemx --version
2218 Print the version number of @command{objdump} and exit.
2219
2220 @item -x
2221 @itemx --all-headers
2222 @cindex all header information, object file
2223 @cindex header information, all
2224 Display all available header information, including the symbol table and
2225 relocation entries. Using @option{-x} is equivalent to specifying all of
2226 @option{-a -f -h -p -r -t}.
2227
2228 @item -w
2229 @itemx --wide
2230 @cindex wide output, printing
2231 Format some lines for output devices that have more than 80 columns.
2232 Also do not truncate symbol names when they are displayed.
2233
2234 @item -z
2235 @itemx --disassemble-zeroes
2236 Normally the disassembly output will skip blocks of zeroes. This
2237 option directs the disassembler to disassemble those blocks, just like
2238 any other data.
2239 @end table
2240
2241 @c man end
2242
2243 @ignore
2244 @c man begin SEEALSO objdump
2245 nm(1), readelf(1), and the Info entries for @file{binutils}.
2246 @c man end
2247 @end ignore
2248
2249 @node ranlib
2250 @chapter ranlib
2251
2252 @kindex ranlib
2253 @cindex archive contents
2254 @cindex symbol index
2255
2256 @c man title ranlib generate index to archive.
2257
2258 @smallexample
2259 @c man begin SYNOPSIS ranlib
2260 ranlib [@option{-vVt}] @var{archive}
2261 @c man end
2262 @end smallexample
2263
2264 @c man begin DESCRIPTION ranlib
2265
2266 @command{ranlib} generates an index to the contents of an archive and
2267 stores it in the archive. The index lists each symbol defined by a
2268 member of an archive that is a relocatable object file.
2269
2270 You may use @samp{nm -s} or @samp{nm --print-armap} to list this index.
2271
2272 An archive with such an index speeds up linking to the library and
2273 allows routines in the library to call each other without regard to
2274 their placement in the archive.
2275
2276 The @sc{gnu} @command{ranlib} program is another form of @sc{gnu} @command{ar}; running
2277 @command{ranlib} is completely equivalent to executing @samp{ar -s}.
2278 @xref{ar}.
2279
2280 @c man end
2281
2282 @c man begin OPTIONS ranlib
2283
2284 @table @env
2285 @item -v
2286 @itemx -V
2287 @itemx --version
2288 Show the version number of @command{ranlib}.
2289
2290 @item -t
2291 Update the timestamp of the symbol map of an archive.
2292 @end table
2293
2294 @c man end
2295
2296 @ignore
2297 @c man begin SEEALSO ranlib
2298 ar(1), nm(1), and the Info entries for @file{binutils}.
2299 @c man end
2300 @end ignore
2301
2302 @node size
2303 @chapter size
2304
2305 @kindex size
2306 @cindex section sizes
2307
2308 @c man title size list section sizes and total size.
2309
2310 @smallexample
2311 @c man begin SYNOPSIS size
2312 size [@option{-A}|@option{-B}|@option{--format=}@var{compatibility}]
2313 [@option{--help}]
2314 [@option{-d}|@option{-o}|@option{-x}|@option{--radix=}@var{number}]
2315 [@option{--common}]
2316 [@option{-t}|@option{--totals}]
2317 [@option{--target=}@var{bfdname}] [@option{-V}|@option{--version}]
2318 [@var{objfile}@dots{}]
2319 @c man end
2320 @end smallexample
2321
2322 @c man begin DESCRIPTION size
2323
2324 The @sc{gnu} @command{size} utility lists the section sizes---and the total
2325 size---for each of the object or archive files @var{objfile} in its
2326 argument list. By default, one line of output is generated for each
2327 object file or each module in an archive.
2328
2329 @var{objfile}@dots{} are the object files to be examined.
2330 If none are specified, the file @code{a.out} will be used.
2331
2332 @c man end
2333
2334 @c man begin OPTIONS size
2335
2336 The command line options have the following meanings:
2337
2338 @table @env
2339 @item -A
2340 @itemx -B
2341 @itemx --format=@var{compatibility}
2342 @cindex @command{size} display format
2343 Using one of these options, you can choose whether the output from @sc{gnu}
2344 @command{size} resembles output from System V @command{size} (using @option{-A},
2345 or @option{--format=sysv}), or Berkeley @command{size} (using @option{-B}, or
2346 @option{--format=berkeley}). The default is the one-line format similar to
2347 Berkeley's.
2348 @c Bonus for doc-source readers: you can also say --format=strange (or
2349 @c anything else that starts with 's') for sysv, and --format=boring (or
2350 @c anything else that starts with 'b') for Berkeley.
2351
2352 Here is an example of the Berkeley (default) format of output from
2353 @command{size}:
2354 @smallexample
2355 $ size --format=Berkeley ranlib size
2356 text data bss dec hex filename
2357 294880 81920 11592 388392 5ed28 ranlib
2358 294880 81920 11888 388688 5ee50 size
2359 @end smallexample
2360
2361 @noindent
2362 This is the same data, but displayed closer to System V conventions:
2363
2364 @smallexample
2365 $ size --format=SysV ranlib size
2366 ranlib :
2367 section size addr
2368 .text 294880 8192
2369 .data 81920 303104
2370 .bss 11592 385024
2371 Total 388392
2372
2373
2374 size :
2375 section size addr
2376 .text 294880 8192
2377 .data 81920 303104
2378 .bss 11888 385024
2379 Total 388688
2380 @end smallexample
2381
2382 @item --help
2383 Show a summary of acceptable arguments and options.
2384
2385 @item -d
2386 @itemx -o
2387 @itemx -x
2388 @itemx --radix=@var{number}
2389 @cindex @command{size} number format
2390 @cindex radix for section sizes
2391 Using one of these options, you can control whether the size of each
2392 section is given in decimal (@option{-d}, or @option{--radix=10}); octal
2393 (@option{-o}, or @option{--radix=8}); or hexadecimal (@option{-x}, or
2394 @option{--radix=16}). In @option{--radix=@var{number}}, only the three
2395 values (8, 10, 16) are supported. The total size is always given in two
2396 radices; decimal and hexadecimal for @option{-d} or @option{-x} output, or
2397 octal and hexadecimal if you're using @option{-o}.
2398
2399 @item --common
2400 Print total size of common symbols in each file. When using Berkeley
2401 format these are included in the bss size.
2402
2403 @item -t
2404 @itemx --totals
2405 Show totals of all objects listed (Berkeley format listing mode only).
2406
2407 @item --target=@var{bfdname}
2408 @cindex object code format
2409 Specify that the object-code format for @var{objfile} is
2410 @var{bfdname}. This option may not be necessary; @command{size} can
2411 automatically recognize many formats.
2412 @xref{Target Selection}, for more information.
2413
2414 @item -V
2415 @itemx --version
2416 Display the version number of @command{size}.
2417 @end table
2418
2419 @c man end
2420
2421 @ignore
2422 @c man begin SEEALSO size
2423 ar(1), objdump(1), readelf(1), and the Info entries for @file{binutils}.
2424 @c man end
2425 @end ignore
2426
2427 @node strings
2428 @chapter strings
2429 @kindex strings
2430 @cindex listings strings
2431 @cindex printing strings
2432 @cindex strings, printing
2433
2434 @c man title strings print the strings of printable characters in files.
2435
2436 @smallexample
2437 @c man begin SYNOPSIS strings
2438 strings [@option{-afovV}] [@option{-}@var{min-len}]
2439 [@option{-n} @var{min-len}] [@option{--bytes=}@var{min-len}]
2440 [@option{-t} @var{radix}] [@option{--radix=}@var{radix}]
2441 [@option{-e} @var{encoding}] [@option{--encoding=}@var{encoding}]
2442 [@option{-}] [@option{--all}] [@option{--print-file-name}]
2443 [@option{-T} @var{bfdname}] [@option{--target=}@var{bfdname}]
2444 [@option{--help}] [@option{--version}] @var{file}@dots{}
2445 @c man end
2446 @end smallexample
2447
2448 @c man begin DESCRIPTION strings
2449
2450 For each @var{file} given, @sc{gnu} @command{strings} prints the printable
2451 character sequences that are at least 4 characters long (or the number
2452 given with the options below) and are followed by an unprintable
2453 character. By default, it only prints the strings from the initialized
2454 and loaded sections of object files; for other types of files, it prints
2455 the strings from the whole file.
2456
2457 @command{strings} is mainly useful for determining the contents of non-text
2458 files.
2459
2460 @c man end
2461
2462 @c man begin OPTIONS strings
2463
2464 @table @env
2465 @item -a
2466 @itemx --all
2467 @itemx -
2468 Do not scan only the initialized and loaded sections of object files;
2469 scan the whole files.
2470
2471 @item -f
2472 @itemx --print-file-name
2473 Print the name of the file before each string.
2474
2475 @item --help
2476 Print a summary of the program usage on the standard output and exit.
2477
2478 @item -@var{min-len}
2479 @itemx -n @var{min-len}
2480 @itemx --bytes=@var{min-len}
2481 Print sequences of characters that are at least @var{min-len} characters
2482 long, instead of the default 4.
2483
2484 @item -o
2485 Like @samp{-t o}. Some other versions of @command{strings} have @option{-o}
2486 act like @samp{-t d} instead. Since we can not be compatible with both
2487 ways, we simply chose one.
2488
2489 @item -t @var{radix}
2490 @itemx --radix=@var{radix}
2491 Print the offset within the file before each string. The single
2492 character argument specifies the radix of the offset---@samp{o} for
2493 octal, @samp{x} for hexadecimal, or @samp{d} for decimal.
2494
2495 @item -e @var{encoding}
2496 @itemx --encoding=@var{encoding}
2497 Select the character encoding of the strings that are to be found.
2498 Possible values for @var{encoding} are: @samp{s} = single-7-bit-byte
2499 characters (ASCII, ISO 8859, etc., default), @samp{S} =
2500 single-8-bit-byte characters, @samp{b} = 16-bit bigendian, @samp{l} =
2501 16-bit littleendian, @samp{B} = 32-bit bigendian, @samp{L} = 32-bit
2502 littleendian. Useful for finding wide character strings. (@samp{l}
2503 and @samp{b} apply to, for example, Unicode UTF-16/UCS-2 encodings).
2504
2505 @item -T @var{bfdname}
2506 @itemx --target=@var{bfdname}
2507 @cindex object code format
2508 Specify an object code format other than your system's default format.
2509 @xref{Target Selection}, for more information.
2510
2511 @item -v
2512 @itemx -V
2513 @itemx --version
2514 Print the program version number on the standard output and exit.
2515 @end table
2516
2517 @c man end
2518
2519 @ignore
2520 @c man begin SEEALSO strings
2521 ar(1), nm(1), objdump(1), ranlib(1), readelf(1)
2522 and the Info entries for @file{binutils}.
2523 @c man end
2524 @end ignore
2525
2526 @node strip
2527 @chapter strip
2528
2529 @kindex strip
2530 @cindex removing symbols
2531 @cindex discarding symbols
2532 @cindex symbols, discarding
2533
2534 @c man title strip Discard symbols from object files.
2535
2536 @smallexample
2537 @c man begin SYNOPSIS strip
2538 strip [@option{-F} @var{bfdname} |@option{--target=}@var{bfdname}]
2539 [@option{-I} @var{bfdname} |@option{--input-target=}@var{bfdname}]
2540 [@option{-O} @var{bfdname} |@option{--output-target=}@var{bfdname}]
2541 [@option{-s}|@option{--strip-all}]
2542 [@option{-S}|@option{-g}|@option{-d}|@option{--strip-debug}]
2543 [@option{-K} @var{symbolname} |@option{--keep-symbol=}@var{symbolname}]
2544 [@option{-N} @var{symbolname} |@option{--strip-symbol=}@var{symbolname}]
2545 [@option{-w}|@option{--wildcard}]
2546 [@option{-x}|@option{--discard-all}] [@option{-X} |@option{--discard-locals}]
2547 [@option{-R} @var{sectionname} |@option{--remove-section=}@var{sectionname}]
2548 [@option{-o} @var{file}] [@option{-p}|@option{--preserve-dates}]
2549 [@option{--keep-file-symbols}]
2550 [@option{--only-keep-debug}]
2551 [@option{-v} |@option{--verbose}] [@option{-V}|@option{--version}]
2552 [@option{--help}] [@option{--info}]
2553 @var{objfile}@dots{}
2554 @c man end
2555 @end smallexample
2556
2557 @c man begin DESCRIPTION strip
2558
2559 @sc{gnu} @command{strip} discards all symbols from object files
2560 @var{objfile}. The list of object files may include archives.
2561 At least one object file must be given.
2562
2563 @command{strip} modifies the files named in its argument,
2564 rather than writing modified copies under different names.
2565
2566 @c man end
2567
2568 @c man begin OPTIONS strip
2569
2570 @table @env
2571 @item -F @var{bfdname}
2572 @itemx --target=@var{bfdname}
2573 Treat the original @var{objfile} as a file with the object
2574 code format @var{bfdname}, and rewrite it in the same format.
2575 @xref{Target Selection}, for more information.
2576
2577 @item --help
2578 Show a summary of the options to @command{strip} and exit.
2579
2580 @item --info
2581 Display a list showing all architectures and object formats available.
2582
2583 @item -I @var{bfdname}
2584 @itemx --input-target=@var{bfdname}
2585 Treat the original @var{objfile} as a file with the object
2586 code format @var{bfdname}.
2587 @xref{Target Selection}, for more information.
2588
2589 @item -O @var{bfdname}
2590 @itemx --output-target=@var{bfdname}
2591 Replace @var{objfile} with a file in the output format @var{bfdname}.
2592 @xref{Target Selection}, for more information.
2593
2594 @item -R @var{sectionname}
2595 @itemx --remove-section=@var{sectionname}
2596 Remove any section named @var{sectionname} from the output file. This
2597 option may be given more than once. Note that using this option
2598 inappropriately may make the output file unusable.
2599
2600 @item -s
2601 @itemx --strip-all
2602 Remove all symbols.
2603
2604 @item -g
2605 @itemx -S
2606 @itemx -d
2607 @itemx --strip-debug
2608 Remove debugging symbols only.
2609
2610 @item --strip-unneeded
2611 Remove all symbols that are not needed for relocation processing.
2612
2613 @item -K @var{symbolname}
2614 @itemx --keep-symbol=@var{symbolname}
2615 When stripping symbols, keep symbol @var{symbolname} even if it would
2616 normally be stripped. This option may be given more than once.
2617
2618 @item -N @var{symbolname}
2619 @itemx --strip-symbol=@var{symbolname}
2620 Remove symbol @var{symbolname} from the source file. This option may be
2621 given more than once, and may be combined with strip options other than
2622 @option{-K}.
2623
2624 @item -o @var{file}
2625 Put the stripped output in @var{file}, rather than replacing the
2626 existing file. When this argument is used, only one @var{objfile}
2627 argument may be specified.
2628
2629 @item -p
2630 @itemx --preserve-dates
2631 Preserve the access and modification dates of the file.
2632
2633 @item -w
2634 @itemx --wildcard
2635 Permit regular expressions in @var{symbolname}s used in other command
2636 line options. The question mark (?), asterisk (*), backslash (\) and
2637 square brackets ([]) operators can be used anywhere in the symbol
2638 name. If the first character of the symbol name is the exclamation
2639 point (!) then the sense of the switch is reversed for that symbol.
2640 For example:
2641
2642 @smallexample
2643 -w -K !foo -K fo*
2644 @end smallexample
2645
2646 would cause strip to only keep symbols that start with the letters
2647 ``fo'', but to discard the symbol ``foo''.
2648
2649 @item -x
2650 @itemx --discard-all
2651 Remove non-global symbols.
2652
2653 @item -X
2654 @itemx --discard-locals
2655 Remove compiler-generated local symbols.
2656 (These usually start with @samp{L} or @samp{.}.)
2657
2658 @item --keep-file-symbols
2659 When stripping a file, perhaps with @option{--strip-debug} or
2660 @option{--strip-unneeded}, retain any symbols specifying source file names,
2661 which would otherwise get stripped.
2662
2663 @item --only-keep-debug
2664 Strip a file, removing contents of any sections that would not be
2665 stripped by @option{--strip-debug} and leaving the debugging sections
2666 intact. In ELF files, this preserves all note sections in the output.
2667
2668 The intention is that this option will be used in conjunction with
2669 @option{--add-gnu-debuglink} to create a two part executable. One a
2670 stripped binary which will occupy less space in RAM and in a
2671 distribution and the second a debugging information file which is only
2672 needed if debugging abilities are required. The suggested procedure
2673 to create these files is as follows:
2674
2675 @enumerate
2676 @item Link the executable as normal. Assuming that is is called
2677 @code{foo} then...
2678 @item Run @code{objcopy --only-keep-debug foo foo.dbg} to
2679 create a file containing the debugging info.
2680 @item Run @code{objcopy --strip-debug foo} to create a
2681 stripped executable.
2682 @item Run @code{objcopy --add-gnu-debuglink=foo.dbg foo}
2683 to add a link to the debugging info into the stripped executable.
2684 @end enumerate
2685
2686 Note---the choice of @code{.dbg} as an extension for the debug info
2687 file is arbitrary. Also the @code{--only-keep-debug} step is
2688 optional. You could instead do this:
2689
2690 @enumerate
2691 @item Link the executable as normal.
2692 @item Copy @code{foo} to @code{foo.full}
2693 @item Run @code{strip --strip-debug foo}
2694 @item Run @code{objcopy --add-gnu-debuglink=foo.full foo}
2695 @end enumerate
2696
2697 i.e., the file pointed to by the @option{--add-gnu-debuglink} can be the
2698 full executable. It does not have to be a file created by the
2699 @option{--only-keep-debug} switch.
2700
2701 Note---this switch is only intended for use on fully linked files. It
2702 does not make sense to use it on object files where the debugging
2703 information may be incomplete. Besides the gnu_debuglink feature
2704 currently only supports the presence of one filename containing
2705 debugging information, not multiple filenames on a one-per-object-file
2706 basis.
2707
2708 @item -V
2709 @itemx --version
2710 Show the version number for @command{strip}.
2711
2712 @item -v
2713 @itemx --verbose
2714 Verbose output: list all object files modified. In the case of
2715 archives, @samp{strip -v} lists all members of the archive.
2716 @end table
2717
2718 @c man end
2719
2720 @ignore
2721 @c man begin SEEALSO strip
2722 the Info entries for @file{binutils}.
2723 @c man end
2724 @end ignore
2725
2726 @node c++filt, addr2line, elfedit, Top
2727 @chapter c++filt
2728
2729 @kindex c++filt
2730 @cindex demangling C++ symbols
2731
2732 @c man title cxxfilt Demangle C++ and Java symbols.
2733
2734 @smallexample
2735 @c man begin SYNOPSIS cxxfilt
2736 c++filt [@option{-_}|@option{--strip-underscores}]
2737 [@option{-n}|@option{--no-strip-underscores}]
2738 [@option{-p}|@option{--no-params}]
2739 [@option{-t}|@option{--types}]
2740 [@option{-i}|@option{--no-verbose}]
2741 [@option{-s} @var{format}|@option{--format=}@var{format}]
2742 [@option{--help}] [@option{--version}] [@var{symbol}@dots{}]
2743 @c man end
2744 @end smallexample
2745
2746 @c man begin DESCRIPTION cxxfilt
2747
2748 @kindex cxxfilt
2749 The C++ and Java languages provide function overloading, which means
2750 that you can write many functions with the same name, providing that
2751 each function takes parameters of different types. In order to be
2752 able to distinguish these similarly named functions C++ and Java
2753 encode them into a low-level assembler name which uniquely identifies
2754 each different version. This process is known as @dfn{mangling}. The
2755 @command{c++filt}
2756 @footnote{MS-DOS does not allow @kbd{+} characters in file names, so on
2757 MS-DOS this program is named @command{CXXFILT}.}
2758 program does the inverse mapping: it decodes (@dfn{demangles}) low-level
2759 names into user-level names so that they can be read.
2760
2761 Every alphanumeric word (consisting of letters, digits, underscores,
2762 dollars, or periods) seen in the input is a potential mangled name.
2763 If the name decodes into a C++ name, the C++ name replaces the
2764 low-level name in the output, otherwise the original word is output.
2765 In this way you can pass an entire assembler source file, containing
2766 mangled names, through @command{c++filt} and see the same source file
2767 containing demangled names.
2768
2769 You can also use @command{c++filt} to decipher individual symbols by
2770 passing them on the command line:
2771
2772 @example
2773 c++filt @var{symbol}
2774 @end example
2775
2776 If no @var{symbol} arguments are given, @command{c++filt} reads symbol
2777 names from the standard input instead. All the results are printed on
2778 the standard output. The difference between reading names from the
2779 command line versus reading names from the standard input is that
2780 command line arguments are expected to be just mangled names and no
2781 checking is performed to separate them from surrounding text. Thus
2782 for example:
2783
2784 @smallexample
2785 c++filt -n _Z1fv
2786 @end smallexample
2787
2788 will work and demangle the name to ``f()'' whereas:
2789
2790 @smallexample
2791 c++filt -n _Z1fv,
2792 @end smallexample
2793
2794 will not work. (Note the extra comma at the end of the mangled
2795 name which makes it invalid). This command however will work:
2796
2797 @smallexample
2798 echo _Z1fv, | c++filt -n
2799 @end smallexample
2800
2801 and will display ``f(),'', i.e., the demangled name followed by a
2802 trailing comma. This behaviour is because when the names are read
2803 from the standard input it is expected that they might be part of an
2804 assembler source file where there might be extra, extraneous
2805 characters trailing after a mangled name. For example:
2806
2807 @smallexample
2808 .type _Z1fv, @@function
2809 @end smallexample
2810
2811 @c man end
2812
2813 @c man begin OPTIONS cxxfilt
2814
2815 @table @env
2816 @item -_
2817 @itemx --strip-underscores
2818 On some systems, both the C and C++ compilers put an underscore in front
2819 of every name. For example, the C name @code{foo} gets the low-level
2820 name @code{_foo}. This option removes the initial underscore. Whether
2821 @command{c++filt} removes the underscore by default is target dependent.
2822
2823 @item -n
2824 @itemx --no-strip-underscores
2825 Do not remove the initial underscore.
2826
2827 @item -p
2828 @itemx --no-params
2829 When demangling the name of a function, do not display the types of
2830 the function's parameters.
2831
2832 @item -t
2833 @itemx --types
2834 Attempt to demangle types as well as function names. This is disabled
2835 by default since mangled types are normally only used internally in
2836 the compiler, and they can be confused with non-mangled names. For example,
2837 a function called ``a'' treated as a mangled type name would be
2838 demangled to ``signed char''.
2839
2840 @item -i
2841 @itemx --no-verbose
2842 Do not include implementation details (if any) in the demangled
2843 output.
2844
2845 @item -s @var{format}
2846 @itemx --format=@var{format}
2847 @command{c++filt} can decode various methods of mangling, used by
2848 different compilers. The argument to this option selects which
2849 method it uses:
2850
2851 @table @code
2852 @item auto
2853 Automatic selection based on executable (the default method)
2854 @item gnu
2855 the one used by the @sc{gnu} C++ compiler (g++)
2856 @item lucid
2857 the one used by the Lucid compiler (lcc)
2858 @item arm
2859 the one specified by the C++ Annotated Reference Manual
2860 @item hp
2861 the one used by the HP compiler (aCC)
2862 @item edg
2863 the one used by the EDG compiler
2864 @item gnu-v3
2865 the one used by the @sc{gnu} C++ compiler (g++) with the V3 ABI.
2866 @item java
2867 the one used by the @sc{gnu} Java compiler (gcj)
2868 @item gnat
2869 the one used by the @sc{gnu} Ada compiler (GNAT).
2870 @end table
2871
2872 @item --help
2873 Print a summary of the options to @command{c++filt} and exit.
2874
2875 @item --version
2876 Print the version number of @command{c++filt} and exit.
2877 @end table
2878
2879 @c man end
2880
2881 @ignore
2882 @c man begin SEEALSO cxxfilt
2883 the Info entries for @file{binutils}.
2884 @c man end
2885 @end ignore
2886
2887 @quotation
2888 @emph{Warning:} @command{c++filt} is a new utility, and the details of its
2889 user interface are subject to change in future releases. In particular,
2890 a command-line option may be required in the future to decode a name
2891 passed as an argument on the command line; in other words,
2892
2893 @example
2894 c++filt @var{symbol}
2895 @end example
2896
2897 @noindent
2898 may in a future release become
2899
2900 @example
2901 c++filt @var{option} @var{symbol}
2902 @end example
2903 @end quotation
2904
2905 @node addr2line
2906 @chapter addr2line
2907
2908 @kindex addr2line
2909 @cindex address to file name and line number
2910
2911 @c man title addr2line convert addresses into file names and line numbers.
2912
2913 @smallexample
2914 @c man begin SYNOPSIS addr2line
2915 addr2line [@option{-a}|@option{--addresses}]
2916 [@option{-b} @var{bfdname}|@option{--target=}@var{bfdname}]
2917 [@option{-C}|@option{--demangle}[=@var{style}]]
2918 [@option{-e} @var{filename}|@option{--exe=}@var{filename}]
2919 [@option{-f}|@option{--functions}] [@option{-s}|@option{--basename}]
2920 [@option{-i}|@option{--inlines}]
2921 [@option{-p}|@option{--pretty-print}]
2922 [@option{-j}|@option{--section=}@var{name}]
2923 [@option{-H}|@option{--help}] [@option{-V}|@option{--version}]
2924 [addr addr @dots{}]
2925 @c man end
2926 @end smallexample
2927
2928 @c man begin DESCRIPTION addr2line
2929
2930 @command{addr2line} translates addresses into file names and line numbers.
2931 Given an address in an executable or an offset in a section of a relocatable
2932 object, it uses the debugging information to figure out which file name and
2933 line number are associated with it.
2934
2935 The executable or relocatable object to use is specified with the @option{-e}
2936 option. The default is the file @file{a.out}. The section in the relocatable
2937 object to use is specified with the @option{-j} option.
2938
2939 @command{addr2line} has two modes of operation.
2940
2941 In the first, hexadecimal addresses are specified on the command line,
2942 and @command{addr2line} displays the file name and line number for each
2943 address.
2944
2945 In the second, @command{addr2line} reads hexadecimal addresses from
2946 standard input, and prints the file name and line number for each
2947 address on standard output. In this mode, @command{addr2line} may be used
2948 in a pipe to convert dynamically chosen addresses.
2949
2950 The format of the output is @samp{FILENAME:LINENO}. The file name and
2951 line number for each address is printed on a separate line. If the
2952 @command{-f} option is used, then each @samp{FILENAME:LINENO} line is
2953 preceded by a @samp{FUNCTIONNAME} line which is the name of the function
2954 containing the address. If the @command{-a} option is used, then the
2955 address read is first printed.
2956
2957 If the file name or function name can not be determined,
2958 @command{addr2line} will print two question marks in their place. If the
2959 line number can not be determined, @command{addr2line} will print 0.
2960
2961 @c man end
2962
2963 @c man begin OPTIONS addr2line
2964
2965 The long and short forms of options, shown here as alternatives, are
2966 equivalent.
2967
2968 @table @env
2969 @item -a
2970 @itemx --addresses
2971 Display address before function names or file and line number
2972 information. The address is printed with a @samp{0x} prefix to easily
2973 identify it.
2974
2975 @item -b @var{bfdname}
2976 @itemx --target=@var{bfdname}
2977 @cindex object code format
2978 Specify that the object-code format for the object files is
2979 @var{bfdname}.
2980
2981 @item -C
2982 @itemx --demangle[=@var{style}]
2983 @cindex demangling in objdump
2984 Decode (@dfn{demangle}) low-level symbol names into user-level names.
2985 Besides removing any initial underscore prepended by the system, this
2986 makes C++ function names readable. Different compilers have different
2987 mangling styles. The optional demangling style argument can be used to
2988 choose an appropriate demangling style for your compiler. @xref{c++filt},
2989 for more information on demangling.
2990
2991 @item -e @var{filename}
2992 @itemx --exe=@var{filename}
2993 Specify the name of the executable for which addresses should be
2994 translated. The default file is @file{a.out}.
2995
2996 @item -f
2997 @itemx --functions
2998 Display function names as well as file and line number information.
2999
3000 @item -s
3001 @itemx --basenames
3002 Display only the base of each file name.
3003
3004 @item -i
3005 @itemx --inlines
3006 If the address belongs to a function that was inlined, the source
3007 information for all enclosing scopes back to the first non-inlined
3008 function will also be printed. For example, if @code{main} inlines
3009 @code{callee1} which inlines @code{callee2}, and address is from
3010 @code{callee2}, the source information for @code{callee1} and @code{main}
3011 will also be printed.
3012
3013 @item -j
3014 @itemx --section
3015 Read offsets relative to the specified section instead of absolute addresses.
3016
3017 @item -p
3018 @itemx --pretty-print
3019 Make the output more human friendly: each location are printed on one line.
3020 If option @option{-i} is specified, lines for all enclosing scopes are
3021 prefixed with @samp{(inlined by)}.
3022 @end table
3023
3024 @c man end
3025
3026 @ignore
3027 @c man begin SEEALSO addr2line
3028 Info entries for @file{binutils}.
3029 @c man end
3030 @end ignore
3031
3032 @node nlmconv
3033 @chapter nlmconv
3034
3035 @command{nlmconv} converts a relocatable object file into a NetWare
3036 Loadable Module.
3037
3038 @ignore
3039 @command{nlmconv} currently works with @samp{i386} object
3040 files in @code{coff}, @sc{elf}, or @code{a.out} format, and @sc{SPARC}
3041 object files in @sc{elf}, or @code{a.out} format@footnote{
3042 @command{nlmconv} should work with any @samp{i386} or @sc{sparc} object
3043 format in the Binary File Descriptor library. It has only been tested
3044 with the above formats.}.
3045 @end ignore
3046
3047 @quotation
3048 @emph{Warning:} @command{nlmconv} is not always built as part of the binary
3049 utilities, since it is only useful for NLM targets.
3050 @end quotation
3051
3052 @c man title nlmconv converts object code into an NLM.
3053
3054 @smallexample
3055 @c man begin SYNOPSIS nlmconv
3056 nlmconv [@option{-I} @var{bfdname}|@option{--input-target=}@var{bfdname}]
3057 [@option{-O} @var{bfdname}|@option{--output-target=}@var{bfdname}]
3058 [@option{-T} @var{headerfile}|@option{--header-file=}@var{headerfile}]
3059 [@option{-d}|@option{--debug}] [@option{-l} @var{linker}|@option{--linker=}@var{linker}]
3060 [@option{-h}|@option{--help}] [@option{-V}|@option{--version}]
3061 @var{infile} @var{outfile}
3062 @c man end
3063 @end smallexample
3064
3065 @c man begin DESCRIPTION nlmconv
3066
3067 @command{nlmconv} converts the relocatable @samp{i386} object file
3068 @var{infile} into the NetWare Loadable Module @var{outfile}, optionally
3069 reading @var{headerfile} for NLM header information. For instructions
3070 on writing the NLM command file language used in header files, see the
3071 @samp{linkers} section, @samp{NLMLINK} in particular, of the @cite{NLM
3072 Development and Tools Overview}, which is part of the NLM Software
3073 Developer's Kit (``NLM SDK''), available from Novell, Inc.
3074 @command{nlmconv} uses the @sc{gnu} Binary File Descriptor library to read
3075 @var{infile};
3076 @ifclear man
3077 see @ref{BFD,,BFD,ld.info,Using LD}, for more information.
3078 @end ifclear
3079
3080 @command{nlmconv} can perform a link step. In other words, you can list
3081 more than one object file for input if you list them in the definitions
3082 file (rather than simply specifying one input file on the command line).
3083 In this case, @command{nlmconv} calls the linker for you.
3084
3085 @c man end
3086
3087 @c man begin OPTIONS nlmconv
3088
3089 @table @env
3090 @item -I @var{bfdname}
3091 @itemx --input-target=@var{bfdname}
3092 Object format of the input file. @command{nlmconv} can usually determine
3093 the format of a given file (so no default is necessary).
3094 @xref{Target Selection}, for more information.
3095
3096 @item -O @var{bfdname}
3097 @itemx --output-target=@var{bfdname}
3098 Object format of the output file. @command{nlmconv} infers the output
3099 format based on the input format, e.g. for a @samp{i386} input file the
3100 output format is @samp{nlm32-i386}.
3101 @xref{Target Selection}, for more information.
3102
3103 @item -T @var{headerfile}
3104 @itemx --header-file=@var{headerfile}
3105 Reads @var{headerfile} for NLM header information. For instructions on
3106 writing the NLM command file language used in header files, see@ see the
3107 @samp{linkers} section, of the @cite{NLM Development and Tools
3108 Overview}, which is part of the NLM Software Developer's Kit, available
3109 from Novell, Inc.
3110
3111 @item -d
3112 @itemx --debug
3113 Displays (on standard error) the linker command line used by @command{nlmconv}.
3114
3115 @item -l @var{linker}
3116 @itemx --linker=@var{linker}
3117 Use @var{linker} for any linking. @var{linker} can be an absolute or a
3118 relative pathname.
3119
3120 @item -h
3121 @itemx --help
3122 Prints a usage summary.
3123
3124 @item -V
3125 @itemx --version
3126 Prints the version number for @command{nlmconv}.
3127 @end table
3128
3129 @c man end
3130
3131 @ignore
3132 @c man begin SEEALSO nlmconv
3133 the Info entries for @file{binutils}.
3134 @c man end
3135 @end ignore
3136
3137 @node windmc
3138 @chapter windmc
3139
3140 @command{windmc} may be used to generator Windows message resources.
3141
3142 @quotation
3143 @emph{Warning:} @command{windmc} is not always built as part of the binary
3144 utilities, since it is only useful for Windows targets.
3145 @end quotation
3146
3147 @c man title windmc generates Windows message resources.
3148
3149 @smallexample
3150 @c man begin SYNOPSIS windres
3151 windmc [options] input-file
3152 @c man end
3153 @end smallexample
3154
3155 @c man begin DESCRIPTION windmc
3156
3157 @command{windmc} reads message definitions from an input file (.mc) and
3158 translate them into a set of output files. The output files may be of
3159 four kinds:
3160
3161 @table @code
3162 @item h
3163 A C header file containing the message definitions.
3164
3165 @item rc
3166 A resource file compilable by the @command{windres} tool.
3167
3168 @item bin
3169 One or more binary files containing the resource data for a specific
3170 message language.
3171
3172 @item dbg
3173 A C include file that maps message id's to their symbolic name.
3174 @end table
3175
3176 The exact description of these different formats is available in
3177 documentation from Microsoft.
3178
3179 When @command{windmc} converts from the @code{mc} format to the @code{bin}
3180 format, @code{rc}, @code{h}, and optional @code{dbg} it is acting like the
3181 Windows Message Compiler.
3182
3183 @c man end
3184
3185 @c man begin OPTIONS windmc
3186
3187 @table @env
3188 @item -a
3189 @itemx --ascii_in
3190 Specifies that the input file specified is ANSI. This is the default
3191 behaviour.
3192
3193 @item -A
3194 @itemx --ascii_out
3195 Specifies that messages in the output @code{bin} files should be in ANSI
3196 format.
3197
3198 @item -b
3199 @itemx --binprefix
3200 Specifies that @code{bin} filenames should have to be prefixed by the
3201 basename of the source file.
3202
3203 @item -c
3204 @itemx --customflag
3205 Sets the customer bit in all message id's.
3206
3207 @item -C @var{codepage}
3208 @itemx --codepage_in @var{codepage}
3209 Sets the default codepage to be used to convert input file to UTF16. The
3210 default is ocdepage 1252.
3211
3212 @item -d
3213 @itemx --decimal_values
3214 Outputs the constants in the header file in decimal. Default is using
3215 hexadecimal output.
3216
3217 @item -e @var{ext}
3218 @itemx --extension @var{ext}
3219 The extension for the header file. The default is .h extension.
3220
3221 @item -F @var{target}
3222 @itemx --target @var{target}
3223 Specify the BFD format to use for a bin file as output. This
3224 is a BFD target name; you can use the @option{--help} option to see a list
3225 of supported targets. Normally @command{windmc} will use the default
3226 format, which is the first one listed by the @option{--help} option.
3227 @ifclear man
3228 @ref{Target Selection}.
3229 @end ifclear
3230
3231 @item -h @var{path}
3232 @itemx --headerdir @var{path}
3233 The target directory of the generated header file. The default is the
3234 current directory.
3235
3236 @item -H
3237 @itemx --help
3238 Displays a list of command line options and then exits.
3239
3240 @item -m @var{characters}
3241 @itemx --maxlength @var{characters}
3242 Instructs @command{windmc} to generate a warning if the length
3243 of any message exceeds the number specified.
3244
3245 @item -n
3246 @itemx --nullterminate
3247 Terminate message text in @code{bin} files by zero. By default they are
3248 terminated by CR/LF.
3249
3250 @item -o
3251 @itemx --hresult_use
3252 Not yet implemented. Instructs @code{windmc} to generate an OLE2 header
3253 file, using HRESULT definitions. Status codes are used if the flag is not
3254 specified.
3255
3256 @item -O @var{codepage}
3257 @itemx --codepage_out @var{codepage}
3258 Sets the default codepage to be used to output text files. The default
3259 is ocdepage 1252.
3260
3261 @item -r @var{path}
3262 @itemx --rcdir @var{path}
3263 The target directory for the generated @code{rc} script and the generated
3264 @code{bin} files that the resource compiler script includes. The default
3265 is the current directory.
3266
3267 @item -u
3268 @itemx --unicode_in
3269 Specifies that the input file is UTF16.
3270
3271 @item -U
3272 @itemx --unicode_out
3273 Specifies that messages in the output @code{bin} file should be in UTF16
3274 format. This is the default behaviour.
3275
3276 @item -v
3277 @item --verbose
3278 Enable verbose mode.
3279
3280 @item -V
3281 @item --version
3282 Prints the version number for @command{windmc}.
3283
3284 @item -x @var{path}
3285 @itemx --xdgb @var{path}
3286 The path of the @code{dbg} C include file that maps message id's to the
3287 symbolic name. No such file is generated without specifying the switch.
3288 @end table
3289
3290 @c man end
3291
3292 @ignore
3293 @c man begin SEEALSO windmc
3294 the Info entries for @file{binutils}.
3295 @c man end
3296 @end ignore
3297
3298 @node windres
3299 @chapter windres
3300
3301 @command{windres} may be used to manipulate Windows resources.
3302
3303 @quotation
3304 @emph{Warning:} @command{windres} is not always built as part of the binary
3305 utilities, since it is only useful for Windows targets.
3306 @end quotation
3307
3308 @c man title windres manipulate Windows resources.
3309
3310 @smallexample
3311 @c man begin SYNOPSIS windres
3312 windres [options] [input-file] [output-file]
3313 @c man end
3314 @end smallexample
3315
3316 @c man begin DESCRIPTION windres
3317
3318 @command{windres} reads resources from an input file and copies them into
3319 an output file. Either file may be in one of three formats:
3320
3321 @table @code
3322 @item rc
3323 A text format read by the Resource Compiler.
3324
3325 @item res
3326 A binary format generated by the Resource Compiler.
3327
3328 @item coff
3329 A COFF object or executable.
3330 @end table
3331
3332 The exact description of these different formats is available in
3333 documentation from Microsoft.
3334
3335 When @command{windres} converts from the @code{rc} format to the @code{res}
3336 format, it is acting like the Windows Resource Compiler. When
3337 @command{windres} converts from the @code{res} format to the @code{coff}
3338 format, it is acting like the Windows @code{CVTRES} program.
3339
3340 When @command{windres} generates an @code{rc} file, the output is similar
3341 but not identical to the format expected for the input. When an input
3342 @code{rc} file refers to an external filename, an output @code{rc} file
3343 will instead include the file contents.
3344
3345 If the input or output format is not specified, @command{windres} will
3346 guess based on the file name, or, for the input file, the file contents.
3347 A file with an extension of @file{.rc} will be treated as an @code{rc}
3348 file, a file with an extension of @file{.res} will be treated as a
3349 @code{res} file, and a file with an extension of @file{.o} or
3350 @file{.exe} will be treated as a @code{coff} file.
3351
3352 If no output file is specified, @command{windres} will print the resources
3353 in @code{rc} format to standard output.
3354
3355 The normal use is for you to write an @code{rc} file, use @command{windres}
3356 to convert it to a COFF object file, and then link the COFF file into
3357 your application. This will make the resources described in the
3358 @code{rc} file available to Windows.
3359
3360 @c man end
3361
3362 @c man begin OPTIONS windres
3363
3364 @table @env
3365 @item -i @var{filename}
3366 @itemx --input @var{filename}
3367 The name of the input file. If this option is not used, then
3368 @command{windres} will use the first non-option argument as the input file
3369 name. If there are no non-option arguments, then @command{windres} will
3370 read from standard input. @command{windres} can not read a COFF file from
3371 standard input.
3372
3373 @item -o @var{filename}
3374 @itemx --output @var{filename}
3375 The name of the output file. If this option is not used, then
3376 @command{windres} will use the first non-option argument, after any used
3377 for the input file name, as the output file name. If there is no
3378 non-option argument, then @command{windres} will write to standard output.
3379 @command{windres} can not write a COFF file to standard output. Note,
3380 for compatibility with @command{rc} the option @option{-fo} is also
3381 accepted, but its use is not recommended.
3382
3383 @item -J @var{format}
3384 @itemx --input-format @var{format}
3385 The input format to read. @var{format} may be @samp{res}, @samp{rc}, or
3386 @samp{coff}. If no input format is specified, @command{windres} will
3387 guess, as described above.
3388
3389 @item -O @var{format}
3390 @itemx --output-format @var{format}
3391 The output format to generate. @var{format} may be @samp{res},
3392 @samp{rc}, or @samp{coff}. If no output format is specified,
3393 @command{windres} will guess, as described above.
3394
3395 @item -F @var{target}
3396 @itemx --target @var{target}
3397 Specify the BFD format to use for a COFF file as input or output. This
3398 is a BFD target name; you can use the @option{--help} option to see a list
3399 of supported targets. Normally @command{windres} will use the default
3400 format, which is the first one listed by the @option{--help} option.
3401 @ifclear man
3402 @ref{Target Selection}.
3403 @end ifclear
3404
3405 @item --preprocessor @var{program}
3406 When @command{windres} reads an @code{rc} file, it runs it through the C
3407 preprocessor first. This option may be used to specify the preprocessor
3408 to use, including any leading arguments. The default preprocessor
3409 argument is @code{gcc -E -xc-header -DRC_INVOKED}.
3410
3411 @item -I @var{directory}
3412 @itemx --include-dir @var{directory}
3413 Specify an include directory to use when reading an @code{rc} file.
3414 @command{windres} will pass this to the preprocessor as an @option{-I}
3415 option. @command{windres} will also search this directory when looking for
3416 files named in the @code{rc} file. If the argument passed to this command
3417 matches any of the supported @var{formats} (as described in the @option{-J}
3418 option), it will issue a deprecation warning, and behave just like the
3419 @option{-J} option. New programs should not use this behaviour. If a
3420 directory happens to match a @var{format}, simple prefix it with @samp{./}
3421 to disable the backward compatibility.
3422
3423 @item -D @var{target}
3424 @itemx --define @var{sym}[=@var{val}]
3425 Specify a @option{-D} option to pass to the preprocessor when reading an
3426 @code{rc} file.
3427
3428 @item -U @var{target}
3429 @itemx --undefine @var{sym}
3430 Specify a @option{-U} option to pass to the preprocessor when reading an
3431 @code{rc} file.
3432
3433 @item -r
3434 Ignored for compatibility with rc.
3435
3436 @item -v
3437 Enable verbose mode. This tells you what the preprocessor is if you
3438 didn't specify one.
3439
3440 @item -c @var{val}
3441 @item --codepage @var{val}
3442 Specify the default codepage to use when reading an @code{rc} file.
3443 @var{val} should be a hexadecimal prefixed by @samp{0x} or decimal
3444 codepage code. The valid range is from zero up to 0xffff, but the
3445 validity of the codepage is host and configuration dependent.
3446
3447 @item -l @var{val}
3448 @item --language @var{val}
3449 Specify the default language to use when reading an @code{rc} file.
3450 @var{val} should be a hexadecimal language code. The low eight bits are
3451 the language, and the high eight bits are the sublanguage.
3452
3453 @item --use-temp-file
3454 Use a temporary file to instead of using popen to read the output of
3455 the preprocessor. Use this option if the popen implementation is buggy
3456 on the host (eg., certain non-English language versions of Windows 95 and
3457 Windows 98 are known to have buggy popen where the output will instead
3458 go the console).
3459
3460 @item --no-use-temp-file
3461 Use popen, not a temporary file, to read the output of the preprocessor.
3462 This is the default behaviour.
3463
3464 @item -h
3465 @item --help
3466 Prints a usage summary.
3467
3468 @item -V
3469 @item --version
3470 Prints the version number for @command{windres}.
3471
3472 @item --yydebug
3473 If @command{windres} is compiled with @code{YYDEBUG} defined as @code{1},
3474 this will turn on parser debugging.
3475 @end table
3476
3477 @c man end
3478
3479 @ignore
3480 @c man begin SEEALSO windres
3481 the Info entries for @file{binutils}.
3482 @c man end
3483 @end ignore
3484
3485 @node dlltool
3486 @chapter dlltool
3487 @cindex DLL
3488 @kindex dlltool
3489
3490 @command{dlltool} is used to create the files needed to create dynamic
3491 link libraries (DLLs) on systems which understand PE format image
3492 files such as Windows. A DLL contains an export table which contains
3493 information that the runtime loader needs to resolve references from a
3494 referencing program.
3495
3496 The export table is generated by this program by reading in a
3497 @file{.def} file or scanning the @file{.a} and @file{.o} files which
3498 will be in the DLL. A @file{.o} file can contain information in
3499 special @samp{.drectve} sections with export information.
3500
3501 @quotation
3502 @emph{Note:} @command{dlltool} is not always built as part of the
3503 binary utilities, since it is only useful for those targets which
3504 support DLLs.
3505 @end quotation
3506
3507 @c man title dlltool Create files needed to build and use DLLs.
3508
3509 @smallexample
3510 @c man begin SYNOPSIS dlltool
3511 dlltool [@option{-d}|@option{--input-def} @var{def-file-name}]
3512 [@option{-b}|@option{--base-file} @var{base-file-name}]
3513 [@option{-e}|@option{--output-exp} @var{exports-file-name}]
3514 [@option{-z}|@option{--output-def} @var{def-file-name}]
3515 [@option{-l}|@option{--output-lib} @var{library-file-name}]
3516 [@option{-y}|@option{--output-delaylib} @var{library-file-name}]
3517 [@option{--export-all-symbols}] [@option{--no-export-all-symbols}]
3518 [@option{--exclude-symbols} @var{list}]
3519 [@option{--no-default-excludes}]
3520 [@option{-S}|@option{--as} @var{path-to-assembler}] [@option{-f}|@option{--as-flags} @var{options}]
3521 [@option{-D}|@option{--dllname} @var{name}] [@option{-m}|@option{--machine} @var{machine}]
3522 [@option{-a}|@option{--add-indirect}]
3523 [@option{-U}|@option{--add-underscore}] [@option{--add-stdcall-underscore}]
3524 [@option{-k}|@option{--kill-at}] [@option{-A}|@option{--add-stdcall-alias}]
3525 [@option{-p}|@option{--ext-prefix-alias} @var{prefix}]
3526 [@option{-x}|@option{--no-idata4}] [@option{-c}|@option{--no-idata5}]
3527 [@option{--use-nul-prefixed-import-tables}]
3528 [@option{-I}|@option{--identify} @var{library-file-name}] [@option{--identify-strict}]
3529 [@option{-i}|@option{--interwork}]
3530 [@option{-n}|@option{--nodelete}] [@option{-t}|@option{--temp-prefix} @var{prefix}]
3531 [@option{-v}|@option{--verbose}]
3532 [@option{-h}|@option{--help}] [@option{-V}|@option{--version}]
3533 [@option{--no-leading-underscore}] [@option{--leading-underscore}]
3534 [object-file @dots{}]
3535 @c man end
3536 @end smallexample
3537
3538 @c man begin DESCRIPTION dlltool
3539
3540 @command{dlltool} reads its inputs, which can come from the @option{-d} and
3541 @option{-b} options as well as object files specified on the command
3542 line. It then processes these inputs and if the @option{-e} option has
3543 been specified it creates a exports file. If the @option{-l} option
3544 has been specified it creates a library file and if the @option{-z} option
3545 has been specified it creates a def file. Any or all of the @option{-e},
3546 @option{-l} and @option{-z} options can be present in one invocation of
3547 dlltool.
3548
3549 When creating a DLL, along with the source for the DLL, it is necessary
3550 to have three other files. @command{dlltool} can help with the creation of
3551 these files.
3552
3553 The first file is a @file{.def} file which specifies which functions are
3554 exported from the DLL, which functions the DLL imports, and so on. This
3555 is a text file and can be created by hand, or @command{dlltool} can be used
3556 to create it using the @option{-z} option. In this case @command{dlltool}
3557 will scan the object files specified on its command line looking for
3558 those functions which have been specially marked as being exported and
3559 put entries for them in the @file{.def} file it creates.
3560
3561 In order to mark a function as being exported from a DLL, it needs to
3562 have an @option{-export:<name_of_function>} entry in the @samp{.drectve}
3563 section of the object file. This can be done in C by using the
3564 asm() operator:
3565
3566 @smallexample
3567 asm (".section .drectve");
3568 asm (".ascii \"-export:my_func\"");
3569
3570 int my_func (void) @{ @dots{} @}
3571 @end smallexample
3572
3573 The second file needed for DLL creation is an exports file. This file
3574 is linked with the object files that make up the body of the DLL and it
3575 handles the interface between the DLL and the outside world. This is a
3576 binary file and it can be created by giving the @option{-e} option to
3577 @command{dlltool} when it is creating or reading in a @file{.def} file.
3578
3579 The third file needed for DLL creation is the library file that programs
3580 will link with in order to access the functions in the DLL (an `import
3581 library'). This file can be created by giving the @option{-l} option to
3582 dlltool when it is creating or reading in a @file{.def} file.
3583
3584 If the @option{-y} option is specified, dlltool generates a delay-import
3585 library that can be used instead of the normal import library to allow
3586 a program to link to the dll only as soon as an imported function is
3587 called for the first time. The resulting executable will need to be
3588 linked to the static delayimp library containing __delayLoadHelper2(),
3589 which in turn will import LoadLibraryA and GetProcAddress from kernel32.
3590
3591 @command{dlltool} builds the library file by hand, but it builds the
3592 exports file by creating temporary files containing assembler statements
3593 and then assembling these. The @option{-S} command line option can be
3594 used to specify the path to the assembler that dlltool will use,
3595 and the @option{-f} option can be used to pass specific flags to that
3596 assembler. The @option{-n} can be used to prevent dlltool from deleting
3597 these temporary assembler files when it is done, and if @option{-n} is
3598 specified twice then this will prevent dlltool from deleting the
3599 temporary object files it used to build the library.
3600
3601 Here is an example of creating a DLL from a source file @samp{dll.c} and
3602 also creating a program (from an object file called @samp{program.o})
3603 that uses that DLL:
3604
3605 @smallexample
3606 gcc -c dll.c
3607 dlltool -e exports.o -l dll.lib dll.o
3608 gcc dll.o exports.o -o dll.dll
3609 gcc program.o dll.lib -o program
3610 @end smallexample
3611
3612
3613 @command{dlltool} may also be used to query an existing import library
3614 to determine the name of the DLL to which it is associated. See the
3615 description of the @option{-I} or @option{--identify} option.
3616
3617 @c man end
3618
3619 @c man begin OPTIONS dlltool
3620
3621 The command line options have the following meanings:
3622
3623 @table @env
3624
3625 @item -d @var{filename}
3626 @itemx --input-def @var{filename}
3627 @cindex input .def file
3628 Specifies the name of a @file{.def} file to be read in and processed.
3629
3630 @item -b @var{filename}
3631 @itemx --base-file @var{filename}
3632 @cindex base files
3633 Specifies the name of a base file to be read in and processed. The
3634 contents of this file will be added to the relocation section in the
3635 exports file generated by dlltool.
3636
3637 @item -e @var{filename}
3638 @itemx --output-exp @var{filename}
3639 Specifies the name of the export file to be created by dlltool.
3640
3641 @item -z @var{filename}
3642 @itemx --output-def @var{filename}
3643 Specifies the name of the @file{.def} file to be created by dlltool.
3644
3645 @item -l @var{filename}
3646 @itemx --output-lib @var{filename}
3647 Specifies the name of the library file to be created by dlltool.
3648
3649 @item -y @var{filename}
3650 @itemx --output-delaylib @var{filename}
3651 Specifies the name of the delay-import library file to be created by dlltool.
3652
3653 @item --export-all-symbols
3654 Treat all global and weak defined symbols found in the input object
3655 files as symbols to be exported. There is a small list of symbols which
3656 are not exported by default; see the @option{--no-default-excludes}
3657 option. You may add to the list of symbols to not export by using the
3658 @option{--exclude-symbols} option.
3659
3660 @item --no-export-all-symbols
3661 Only export symbols explicitly listed in an input @file{.def} file or in
3662 @samp{.drectve} sections in the input object files. This is the default
3663 behaviour. The @samp{.drectve} sections are created by @samp{dllexport}
3664 attributes in the source code.
3665
3666 @item --exclude-symbols @var{list}
3667 Do not export the symbols in @var{list}. This is a list of symbol names
3668 separated by comma or colon characters. The symbol names should not
3669 contain a leading underscore. This is only meaningful when
3670 @option{--export-all-symbols} is used.
3671
3672 @item --no-default-excludes
3673 When @option{--export-all-symbols} is used, it will by default avoid
3674 exporting certain special symbols. The current list of symbols to avoid
3675 exporting is @samp{DllMain@@12}, @samp{DllEntryPoint@@0},
3676 @samp{impure_ptr}. You may use the @option{--no-default-excludes} option
3677 to go ahead and export these special symbols. This is only meaningful
3678 when @option{--export-all-symbols} is used.
3679
3680 @item -S @var{path}
3681 @itemx --as @var{path}
3682 Specifies the path, including the filename, of the assembler to be used
3683 to create the exports file.
3684
3685 @item -f @var{options}
3686 @itemx --as-flags @var{options}
3687 Specifies any specific command line options to be passed to the
3688 assembler when building the exports file. This option will work even if
3689 the @option{-S} option is not used. This option only takes one argument,
3690 and if it occurs more than once on the command line, then later
3691 occurrences will override earlier occurrences. So if it is necessary to
3692 pass multiple options to the assembler they should be enclosed in
3693 double quotes.
3694
3695 @item -D @var{name}
3696 @itemx --dll-name @var{name}
3697 Specifies the name to be stored in the @file{.def} file as the name of
3698 the DLL when the @option{-e} option is used. If this option is not
3699 present, then the filename given to the @option{-e} option will be
3700 used as the name of the DLL.
3701
3702 @item -m @var{machine}
3703 @itemx -machine @var{machine}
3704 Specifies the type of machine for which the library file should be
3705 built. @command{dlltool} has a built in default type, depending upon how
3706 it was created, but this option can be used to override that. This is
3707 normally only useful when creating DLLs for an ARM processor, when the
3708 contents of the DLL are actually encode using Thumb instructions.
3709
3710 @item -a
3711 @itemx --add-indirect
3712 Specifies that when @command{dlltool} is creating the exports file it
3713 should add a section which allows the exported functions to be
3714 referenced without using the import library. Whatever the hell that
3715 means!
3716
3717 @item -U
3718 @itemx --add-underscore
3719 Specifies that when @command{dlltool} is creating the exports file it
3720 should prepend an underscore to the names of @emph{all} exported symbols.
3721
3722 @item --no-leading-underscore
3723 @item --leading-underscore
3724 Specifies whether standard symbol should be forced to be prefixed, or
3725 not.
3726
3727 @item --add-stdcall-underscore
3728 Specifies that when @command{dlltool} is creating the exports file it
3729 should prepend an underscore to the names of exported @emph{stdcall}
3730 functions. Variable names and non-stdcall function names are not modified.
3731 This option is useful when creating GNU-compatible import libs for third
3732 party DLLs that were built with MS-Windows tools.
3733
3734 @item -k
3735 @itemx --kill-at
3736 Specifies that when @command{dlltool} is creating the exports file it
3737 should not append the string @samp{@@ <number>}. These numbers are
3738 called ordinal numbers and they represent another way of accessing the
3739 function in a DLL, other than by name.
3740
3741 @item -A
3742 @itemx --add-stdcall-alias
3743 Specifies that when @command{dlltool} is creating the exports file it
3744 should add aliases for stdcall symbols without @samp{@@ <number>}
3745 in addition to the symbols with @samp{@@ <number>}.
3746
3747 @item -p
3748 @itemx --ext-prefix-alias @var{prefix}
3749 Causes @command{dlltool} to create external aliases for all DLL
3750 imports with the specified prefix. The aliases are created for both
3751 external and import symbols with no leading underscore.
3752
3753 @item -x
3754 @itemx --no-idata4
3755 Specifies that when @command{dlltool} is creating the exports and library
3756 files it should omit the @code{.idata4} section. This is for compatibility
3757 with certain operating systems.
3758
3759 @item --use-nul-prefixed-import-tables
3760 Specifies that when @command{dlltool} is creating the exports and library
3761 files it should prefix the @code{.idata4} and @code{.idata5} by zero an
3762 element. This emulates old gnu import library generation of
3763 @code{dlltool}. By default this option is turned off.
3764
3765 @item -c
3766 @itemx --no-idata5
3767 Specifies that when @command{dlltool} is creating the exports and library
3768 files it should omit the @code{.idata5} section. This is for compatibility
3769 with certain operating systems.
3770
3771 @item -I @var{filename}
3772 @itemx --identify @var{filename}
3773 Specifies that @command{dlltool} should inspect the import library
3774 indicated by @var{filename} and report, on @code{stdout}, the name(s)
3775 of the associated DLL(s). This can be performed in addition to any
3776 other operations indicated by the other options and arguments.
3777 @command{dlltool} fails if the import library does not exist or is not
3778 actually an import library. See also @option{--identify-strict}.
3779
3780 @item --identify-strict
3781 Modifies the behavior of the @option{--identify} option, such
3782 that an error is reported if @var{filename} is associated with
3783 more than one DLL.
3784
3785 @item -i
3786 @itemx --interwork
3787 Specifies that @command{dlltool} should mark the objects in the library
3788 file and exports file that it produces as supporting interworking
3789 between ARM and Thumb code.
3790
3791 @item -n
3792 @itemx --nodelete
3793 Makes @command{dlltool} preserve the temporary assembler files it used to
3794 create the exports file. If this option is repeated then dlltool will
3795 also preserve the temporary object files it uses to create the library
3796 file.
3797
3798 @item -t @var{prefix}
3799 @itemx --temp-prefix @var{prefix}
3800 Makes @command{dlltool} use @var{prefix} when constructing the names of
3801 temporary assembler and object files. By default, the temp file prefix
3802 is generated from the pid.
3803
3804 @item -v
3805 @itemx --verbose
3806 Make dlltool describe what it is doing.
3807
3808 @item -h
3809 @itemx --help
3810 Displays a list of command line options and then exits.
3811
3812 @item -V
3813 @itemx --version
3814 Displays dlltool's version number and then exits.
3815
3816 @end table
3817
3818 @c man end
3819
3820 @menu
3821 * def file format:: The format of the dlltool @file{.def} file
3822 @end menu
3823
3824 @node def file format
3825 @section The format of the @command{dlltool} @file{.def} file
3826
3827 A @file{.def} file contains any number of the following commands:
3828
3829 @table @asis
3830
3831 @item @code{NAME} @var{name} @code{[ ,} @var{base} @code{]}
3832 The result is going to be named @var{name}@code{.exe}.
3833
3834 @item @code{LIBRARY} @var{name} @code{[ ,} @var{base} @code{]}
3835 The result is going to be named @var{name}@code{.dll}.
3836
3837 @item @code{EXPORTS ( ( (} @var{name1} @code{[ = } @var{name2} @code{] ) | ( } @var{name1} @code{=} @var{module-name} @code{.} @var{external-name} @code{) ) [ == } @var{its_name} @code{]}
3838 @item @code{[} @var{integer} @code{] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) *}
3839 Declares @var{name1} as an exported symbol from the DLL, with optional
3840 ordinal number @var{integer}, or declares @var{name1} as an alias
3841 (forward) of the function @var{external-name} in the DLL.
3842 If @var{its_name} is specified, this name is used as string in export table.
3843 @var{module-name}.
3844
3845 @item @code{IMPORTS ( (} @var{internal-name} @code{=} @var{module-name} @code{.} @var{integer} @code{) | [} @var{internal-name} @code{= ]} @var{module-name} @code{.} @var{external-name} @code{) [ == ) @var{its_name} @code{]} *}
3846 Declares that @var{external-name} or the exported function whose
3847 ordinal number is @var{integer} is to be imported from the file
3848 @var{module-name}. If @var{internal-name} is specified then this is
3849 the name that the imported function will be referred to in the body of
3850 the DLL.
3851 If @var{its_name} is specified, this name is used as string in import table.
3852
3853 @item @code{DESCRIPTION} @var{string}
3854 Puts @var{string} into the output @file{.exp} file in the
3855 @code{.rdata} section.
3856
3857 @item @code{STACKSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]}
3858 @item @code{HEAPSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]}
3859 Generates @code{--stack} or @code{--heap}
3860 @var{number-reserve},@var{number-commit} in the output @code{.drectve}
3861 section. The linker will see this and act upon it.
3862
3863 @item @code{CODE} @var{attr} @code{+}
3864 @item @code{DATA} @var{attr} @code{+}
3865 @item @code{SECTIONS (} @var{section-name} @var{attr}@code{ + ) *}
3866 Generates @code{--attr} @var{section-name} @var{attr} in the output
3867 @code{.drectve} section, where @var{attr} is one of @code{READ},
3868 @code{WRITE}, @code{EXECUTE} or @code{SHARED}. The linker will see
3869 this and act upon it.
3870
3871 @end table
3872
3873 @ignore
3874 @c man begin SEEALSO dlltool
3875 The Info pages for @file{binutils}.
3876 @c man end
3877 @end ignore
3878
3879 @node readelf
3880 @chapter readelf
3881
3882 @cindex ELF file information
3883 @kindex readelf
3884
3885 @c man title readelf Displays information about ELF files.
3886
3887 @smallexample
3888 @c man begin SYNOPSIS readelf
3889 readelf [@option{-a}|@option{--all}]
3890 [@option{-h}|@option{--file-header}]
3891 [@option{-l}|@option{--program-headers}|@option{--segments}]
3892 [@option{-S}|@option{--section-headers}|@option{--sections}]
3893 [@option{-g}|@option{--section-groups}]
3894 [@option{-t}|@option{--section-details}]
3895 [@option{-e}|@option{--headers}]
3896 [@option{-s}|@option{--syms}|@option{--symbols}]
3897 [@option{-n}|@option{--notes}]
3898 [@option{-r}|@option{--relocs}]
3899 [@option{-u}|@option{--unwind}]
3900 [@option{-d}|@option{--dynamic}]
3901 [@option{-V}|@option{--version-info}]
3902 [@option{-A}|@option{--arch-specific}]
3903 [@option{-D}|@option{--use-dynamic}]
3904 [@option{-x} <number or name>|@option{--hex-dump=}<number or name>]
3905 [@option{-p} <number or name>|@option{--string-dump=}<number or name>]
3906 [@option{-R} <number or name>|@option{--relocated-dump=}<number or name>]
3907 [@option{-c}|@option{--archive-index}]
3908 [@option{-w[lLiaprmfFsoRt]}|
3909 @option{--debug-dump}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes]]
3910 [@option{-I}|@option{--histogram}]
3911 [@option{-v}|@option{--version}]
3912 [@option{-W}|@option{--wide}]
3913 [@option{-H}|@option{--help}]
3914 @var{elffile}@dots{}
3915 @c man end
3916 @end smallexample
3917
3918 @c man begin DESCRIPTION readelf
3919
3920 @command{readelf} displays information about one or more ELF format object
3921 files. The options control what particular information to display.
3922
3923 @var{elffile}@dots{} are the object files to be examined. 32-bit and
3924 64-bit ELF files are supported, as are archives containing ELF files.
3925
3926 This program performs a similar function to @command{objdump} but it
3927 goes into more detail and it exists independently of the @sc{bfd}
3928 library, so if there is a bug in @sc{bfd} then readelf will not be
3929 affected.
3930
3931 @c man end
3932
3933 @c man begin OPTIONS readelf
3934
3935 The long and short forms of options, shown here as alternatives, are
3936 equivalent. At least one option besides @samp{-v} or @samp{-H} must be
3937 given.
3938
3939 @table @env
3940 @item -a
3941 @itemx --all
3942 Equivalent to specifying @option{--file-header},
3943 @option{--program-headers}, @option{--sections}, @option{--symbols},
3944 @option{--relocs}, @option{--dynamic}, @option{--notes} and
3945 @option{--version-info}.
3946
3947 @item -h
3948 @itemx --file-header
3949 @cindex ELF file header information
3950 Displays the information contained in the ELF header at the start of the
3951 file.
3952
3953 @item -l
3954 @itemx --program-headers
3955 @itemx --segments
3956 @cindex ELF program header information
3957 @cindex ELF segment information
3958 Displays the information contained in the file's segment headers, if it
3959 has any.
3960
3961 @item -S
3962 @itemx --sections
3963 @itemx --section-headers
3964 @cindex ELF section information
3965 Displays the information contained in the file's section headers, if it
3966 has any.
3967
3968 @item -g
3969 @itemx --section-groups
3970 @cindex ELF section group information
3971 Displays the information contained in the file's section groups, if it
3972 has any.
3973
3974 @item -t
3975 @itemx --section-details
3976 @cindex ELF section information
3977 Displays the detailed section information. Implies @option{-S}.
3978
3979 @item -s
3980 @itemx --symbols
3981 @itemx --syms
3982 @cindex ELF symbol table information
3983 Displays the entries in symbol table section of the file, if it has one.
3984
3985 @item -e
3986 @itemx --headers
3987 Display all the headers in the file. Equivalent to @option{-h -l -S}.
3988
3989 @item -n
3990 @itemx --notes
3991 @cindex ELF notes
3992 Displays the contents of the NOTE segments and/or sections, if any.
3993
3994 @item -r
3995 @itemx --relocs
3996 @cindex ELF reloc information
3997 Displays the contents of the file's relocation section, if it has one.
3998
3999 @item -u
4000 @itemx --unwind
4001 @cindex unwind information
4002 Displays the contents of the file's unwind section, if it has one. Only
4003 the unwind sections for IA64 ELF files are currently supported.
4004
4005 @item -d
4006 @itemx --dynamic
4007 @cindex ELF dynamic section information
4008 Displays the contents of the file's dynamic section, if it has one.
4009
4010 @item -V
4011 @itemx --version-info
4012 @cindex ELF version sections informations
4013 Displays the contents of the version sections in the file, it they
4014 exist.
4015
4016 @item -A
4017 @itemx --arch-specific
4018 Displays architecture-specific information in the file, if there
4019 is any.
4020
4021 @item -D
4022 @itemx --use-dynamic
4023 When displaying symbols, this option makes @command{readelf} use the
4024 symbol table in the file's dynamic section, rather than the one in the
4025 symbols section.
4026
4027 @item -x <number or name>
4028 @itemx --hex-dump=<number or name>
4029 Displays the contents of the indicated section as a hexadecimal bytes.
4030 A number identifies a particular section by index in the section table;
4031 any other string identifies all sections with that name in the object file.
4032
4033 @item -R <number or name>
4034 @itemx --relocated-dump=<number or name>
4035 Displays the contents of the indicated section as a hexadecimal
4036 bytes. A number identifies a particular section by index in the
4037 section table; any other string identifies all sections with that name
4038 in the object file. The contents of the section will be relocated
4039 before they are displayed.
4040
4041 @item -p <number or name>
4042 @itemx --string-dump=<number or name>
4043 Displays the contents of the indicated section as printable strings.
4044 A number identifies a particular section by index in the section table;
4045 any other string identifies all sections with that name in the object file.
4046
4047 @item -c
4048 @itemx --archive-index
4049 @cindex Archive file symbol index information
4050 Displays the file symbol index infomation contained in the header part
4051 of binary archives. Performs the same function as the @option{t}
4052 command to @command{ar}, but without using the BFD library. @xref{ar}.
4053
4054 @item -w[lLiaprmfFsoRt]
4055 @itemx --debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes]
4056 Displays the contents of the debug sections in the file, if any are
4057 present. If one of the optional letters or words follows the switch
4058 then only data found in those specific sections will be dumped.
4059
4060 Note: the @option{=decodedline} option will display the interpreted
4061 contents of a .debug_line section whereas the @option{=rawline} option
4062 dumps the contents in a raw format.
4063
4064 Note: the @option{=frames-interp} option will display the interpreted
4065 contents of a .debug_frame section whereas the @option{=frames} option
4066 dumps the contents in a raw format.
4067
4068 @item -I
4069 @itemx --histogram
4070 Display a histogram of bucket list lengths when displaying the contents
4071 of the symbol tables.
4072
4073 @item -v
4074 @itemx --version
4075 Display the version number of readelf.
4076
4077 @item -W
4078 @itemx --wide
4079 Don't break output lines to fit into 80 columns. By default
4080 @command{readelf} breaks section header and segment listing lines for
4081 64-bit ELF files, so that they fit into 80 columns. This option causes
4082 @command{readelf} to print each section header resp. each segment one a
4083 single line, which is far more readable on terminals wider than 80 columns.
4084
4085 @item -H
4086 @itemx --help
4087 Display the command line options understood by @command{readelf}.
4088
4089 @end table
4090
4091 @c man end
4092
4093 @ignore
4094 @c man begin SEEALSO readelf
4095 objdump(1), and the Info entries for @file{binutils}.
4096 @c man end
4097 @end ignore
4098
4099 @node elfedit
4100 @chapter elfedit
4101
4102 @cindex Update ELF header
4103 @kindex elfedit
4104
4105 @c man title elfedit Update the ELF header of ELF files.
4106
4107 @smallexample
4108 @c man begin SYNOPSIS elfedit
4109 elfedit [@option{--input-mach=}@var{machine}]
4110 [@option{--input-type=}@var{type}]
4111 @option{--output-mach=}@var{machine}
4112 @option{--output-type=}@var{type}
4113 [@option{-v}|@option{--version}]
4114 [@option{-h}|@option{--help}]
4115 @var{elffile}@dots{}
4116 @c man end
4117 @end smallexample
4118
4119 @c man begin DESCRIPTION elfedit
4120
4121 @command{elfedit} updates the ELF header of ELF files which have
4122 the matching ELF machine and file types. The options control how and
4123 which fields in the ELF header should be updated.
4124
4125 @var{elffile}@dots{} are the ELF files to be updated. 32-bit and
4126 64-bit ELF files are supported, as are archives containing ELF files.
4127 @c man end
4128
4129 @c man begin OPTIONS elfedit
4130
4131 The long and short forms of options, shown here as alternatives, are
4132 equivalent. At least one of the @option{--output-mach} and
4133 @option{--output-type} options must be given.
4134
4135 @table @env
4136
4137 @itemx --input-mach=@var{machine}
4138 Set the matching input ELF machine type to @var{machine}. If
4139 @option{--input-mach} isn't specified, it will match any ELF
4140 machine types.
4141
4142 The supported ELF machine types are, @var{L1OM} and @var{x86-64}.
4143
4144 @itemx --output-mach=@var{machine}
4145 Change the ELF machine type in the ELF header to @var{machine}. The
4146 supported ELF machine types are the same as @option{--input-mach}.
4147
4148 @itemx --input-type=@var{type}
4149 Set the matching input ELF file type to @var{type}. If
4150 @option{--input-type} isn't specified, it will match any ELF file types.
4151
4152 The supported ELF file types are, @var{rel}, @var{exec} and @var{dyn}.
4153
4154 @itemx --output-type=@var{type}
4155 Change the ELF file type in the ELF header to @var{type}. The
4156 supported ELF types are the same as @option{--input-type}.
4157
4158 @item -v
4159 @itemx --version
4160 Display the version number of @command{elfedit}.
4161
4162 @item -h
4163 @itemx --help
4164 Display the command line options understood by @command{elfedit}.
4165
4166 @end table
4167
4168 @c man end
4169
4170 @ignore
4171 @c man begin SEEALSO elfedit
4172 readelf(1), and the Info entries for @file{binutils}.
4173 @c man end
4174 @end ignore
4175
4176 @node Common Options
4177 @chapter Common Options
4178
4179 The following command-line options are supported by all of the
4180 programs described in this manual.
4181
4182 @c man begin OPTIONS
4183 @table @env
4184 @include at-file.texi
4185 @c man end
4186
4187 @item --help
4188 Display the command-line options supported by the program.
4189
4190 @item --version
4191 Display the version number of the program.
4192
4193 @c man begin OPTIONS
4194 @end table
4195 @c man end
4196
4197 @node Selecting the Target System
4198 @chapter Selecting the Target System
4199
4200 You can specify two aspects of the target system to the @sc{gnu}
4201 binary file utilities, each in several ways:
4202
4203 @itemize @bullet
4204 @item
4205 the target
4206
4207 @item
4208 the architecture
4209 @end itemize
4210
4211 In the following summaries, the lists of ways to specify values are in
4212 order of decreasing precedence. The ways listed first override those
4213 listed later.
4214
4215 The commands to list valid values only list the values for which the
4216 programs you are running were configured. If they were configured with
4217 @option{--enable-targets=all}, the commands list most of the available
4218 values, but a few are left out; not all targets can be configured in at
4219 once because some of them can only be configured @dfn{native} (on hosts
4220 with the same type as the target system).
4221
4222 @menu
4223 * Target Selection::
4224 * Architecture Selection::
4225 @end menu
4226
4227 @node Target Selection
4228 @section Target Selection
4229
4230 A @dfn{target} is an object file format. A given target may be
4231 supported for multiple architectures (@pxref{Architecture Selection}).
4232 A target selection may also have variations for different operating
4233 systems or architectures.
4234
4235 The command to list valid target values is @samp{objdump -i}
4236 (the first column of output contains the relevant information).
4237
4238 Some sample values are: @samp{a.out-hp300bsd}, @samp{ecoff-littlemips},
4239 @samp{a.out-sunos-big}.
4240
4241 You can also specify a target using a configuration triplet. This is
4242 the same sort of name that is passed to @file{configure} to specify a
4243 target. When you use a configuration triplet as an argument, it must be
4244 fully canonicalized. You can see the canonical version of a triplet by
4245 running the shell script @file{config.sub} which is included with the
4246 sources.
4247
4248 Some sample configuration triplets are: @samp{m68k-hp-bsd},
4249 @samp{mips-dec-ultrix}, @samp{sparc-sun-sunos}.
4250
4251 @subheading @command{objdump} Target
4252
4253 Ways to specify:
4254
4255 @enumerate
4256 @item
4257 command line option: @option{-b} or @option{--target}
4258
4259 @item
4260 environment variable @code{GNUTARGET}
4261
4262 @item
4263 deduced from the input file
4264 @end enumerate
4265
4266 @subheading @command{objcopy} and @command{strip} Input Target
4267
4268 Ways to specify:
4269
4270 @enumerate
4271 @item
4272 command line options: @option{-I} or @option{--input-target}, or @option{-F} or @option{--target}
4273
4274 @item
4275 environment variable @code{GNUTARGET}
4276
4277 @item
4278 deduced from the input file
4279 @end enumerate
4280
4281 @subheading @command{objcopy} and @command{strip} Output Target
4282
4283 Ways to specify:
4284
4285 @enumerate
4286 @item
4287 command line options: @option{-O} or @option{--output-target}, or @option{-F} or @option{--target}
4288
4289 @item
4290 the input target (see ``@command{objcopy} and @command{strip} Input Target'' above)
4291
4292 @item
4293 environment variable @code{GNUTARGET}
4294
4295 @item
4296 deduced from the input file
4297 @end enumerate
4298
4299 @subheading @command{nm}, @command{size}, and @command{strings} Target
4300
4301 Ways to specify:
4302
4303 @enumerate
4304 @item
4305 command line option: @option{--target}
4306
4307 @item
4308 environment variable @code{GNUTARGET}
4309
4310 @item
4311 deduced from the input file
4312 @end enumerate
4313
4314 @node Architecture Selection
4315 @section Architecture Selection
4316
4317 An @dfn{architecture} is a type of @sc{cpu} on which an object file is
4318 to run. Its name may contain a colon, separating the name of the
4319 processor family from the name of the particular @sc{cpu}.
4320
4321 The command to list valid architecture values is @samp{objdump -i} (the
4322 second column contains the relevant information).
4323
4324 Sample values: @samp{m68k:68020}, @samp{mips:3000}, @samp{sparc}.
4325
4326 @subheading @command{objdump} Architecture
4327
4328 Ways to specify:
4329
4330 @enumerate
4331 @item
4332 command line option: @option{-m} or @option{--architecture}
4333
4334 @item
4335 deduced from the input file
4336 @end enumerate
4337
4338 @subheading @command{objcopy}, @command{nm}, @command{size}, @command{strings} Architecture
4339
4340 Ways to specify:
4341
4342 @enumerate
4343 @item
4344 deduced from the input file
4345 @end enumerate
4346
4347 @node Reporting Bugs
4348 @chapter Reporting Bugs
4349 @cindex bugs
4350 @cindex reporting bugs
4351
4352 Your bug reports play an essential role in making the binary utilities
4353 reliable.
4354
4355 Reporting a bug may help you by bringing a solution to your problem, or
4356 it may not. But in any case the principal function of a bug report is
4357 to help the entire community by making the next version of the binary
4358 utilities work better. Bug reports are your contribution to their
4359 maintenance.
4360
4361 In order for a bug report to serve its purpose, you must include the
4362 information that enables us to fix the bug.
4363
4364 @menu
4365 * Bug Criteria:: Have you found a bug?
4366 * Bug Reporting:: How to report bugs
4367 @end menu
4368
4369 @node Bug Criteria
4370 @section Have You Found a Bug?
4371 @cindex bug criteria
4372
4373 If you are not sure whether you have found a bug, here are some guidelines:
4374
4375 @itemize @bullet
4376 @cindex fatal signal
4377 @cindex crash
4378 @item
4379 If a binary utility gets a fatal signal, for any input whatever, that is
4380 a bug. Reliable utilities never crash.
4381
4382 @cindex error on valid input
4383 @item
4384 If a binary utility produces an error message for valid input, that is a
4385 bug.
4386
4387 @item
4388 If you are an experienced user of binary utilities, your suggestions for
4389 improvement are welcome in any case.
4390 @end itemize
4391
4392 @node Bug Reporting
4393 @section How to Report Bugs
4394 @cindex bug reports
4395 @cindex bugs, reporting
4396
4397 A number of companies and individuals offer support for @sc{gnu}
4398 products. If you obtained the binary utilities from a support
4399 organization, we recommend you contact that organization first.
4400
4401 You can find contact information for many support companies and
4402 individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
4403 distribution.
4404
4405 @ifset BUGURL
4406 In any event, we also recommend that you send bug reports for the binary
4407 utilities to @value{BUGURL}.
4408 @end ifset
4409
4410 The fundamental principle of reporting bugs usefully is this:
4411 @strong{report all the facts}. If you are not sure whether to state a
4412 fact or leave it out, state it!
4413
4414 Often people omit facts because they think they know what causes the
4415 problem and assume that some details do not matter. Thus, you might
4416 assume that the name of a file you use in an example does not matter.
4417 Well, probably it does not, but one cannot be sure. Perhaps the bug is
4418 a stray memory reference which happens to fetch from the location where
4419 that pathname is stored in memory; perhaps, if the pathname were
4420 different, the contents of that location would fool the utility into
4421 doing the right thing despite the bug. Play it safe and give a
4422 specific, complete example. That is the easiest thing for you to do,
4423 and the most helpful.
4424
4425 Keep in mind that the purpose of a bug report is to enable us to fix the bug if
4426 it is new to us. Therefore, always write your bug reports on the assumption
4427 that the bug has not been reported previously.
4428
4429 Sometimes people give a few sketchy facts and ask, ``Does this ring a
4430 bell?'' This cannot help us fix a bug, so it is basically useless. We
4431 respond by asking for enough details to enable us to investigate.
4432 You might as well expedite matters by sending them to begin with.
4433
4434 To enable us to fix the bug, you should include all these things:
4435
4436 @itemize @bullet
4437 @item
4438 The version of the utility. Each utility announces it if you start it
4439 with the @option{--version} argument.
4440
4441 Without this, we will not know whether there is any point in looking for
4442 the bug in the current version of the binary utilities.
4443
4444 @item
4445 Any patches you may have applied to the source, including any patches
4446 made to the @code{BFD} library.
4447
4448 @item
4449 The type of machine you are using, and the operating system name and
4450 version number.
4451
4452 @item
4453 What compiler (and its version) was used to compile the utilities---e.g.
4454 ``@code{gcc-2.7}''.
4455
4456 @item
4457 The command arguments you gave the utility to observe the bug. To
4458 guarantee you will not omit something important, list them all. A copy
4459 of the Makefile (or the output from make) is sufficient.
4460
4461 If we were to try to guess the arguments, we would probably guess wrong
4462 and then we might not encounter the bug.
4463
4464 @item
4465 A complete input file, or set of input files, that will reproduce the
4466 bug. If the utility is reading an object file or files, then it is
4467 generally most helpful to send the actual object files.
4468
4469 If the source files were produced exclusively using @sc{gnu} programs
4470 (e.g., @command{gcc}, @command{gas}, and/or the @sc{gnu} @command{ld}), then it
4471 may be OK to send the source files rather than the object files. In
4472 this case, be sure to say exactly what version of @command{gcc}, or
4473 whatever, was used to produce the object files. Also say how
4474 @command{gcc}, or whatever, was configured.
4475
4476 @item
4477 A description of what behavior you observe that you believe is
4478 incorrect. For example, ``It gets a fatal signal.''
4479
4480 Of course, if the bug is that the utility gets a fatal signal, then we
4481 will certainly notice it. But if the bug is incorrect output, we might
4482 not notice unless it is glaringly wrong. You might as well not give us
4483 a chance to make a mistake.
4484
4485 Even if the problem you experience is a fatal signal, you should still
4486 say so explicitly. Suppose something strange is going on, such as your
4487 copy of the utility is out of sync, or you have encountered a bug in
4488 the C library on your system. (This has happened!) Your copy might
4489 crash and ours would not. If you told us to expect a crash, then when
4490 ours fails to crash, we would know that the bug was not happening for
4491 us. If you had not told us to expect a crash, then we would not be able
4492 to draw any conclusion from our observations.
4493
4494 @item
4495 If you wish to suggest changes to the source, send us context diffs, as
4496 generated by @command{diff} with the @option{-u}, @option{-c}, or @option{-p}
4497 option. Always send diffs from the old file to the new file. If you
4498 wish to discuss something in the @command{ld} source, refer to it by
4499 context, not by line number.
4500
4501 The line numbers in our development sources will not match those in your
4502 sources. Your line numbers would convey no useful information to us.
4503 @end itemize
4504
4505 Here are some things that are not necessary:
4506
4507 @itemize @bullet
4508 @item
4509 A description of the envelope of the bug.
4510
4511 Often people who encounter a bug spend a lot of time investigating
4512 which changes to the input file will make the bug go away and which
4513 changes will not affect it.
4514
4515 This is often time consuming and not very useful, because the way we
4516 will find the bug is by running a single example under the debugger
4517 with breakpoints, not by pure deduction from a series of examples.
4518 We recommend that you save your time for something else.
4519
4520 Of course, if you can find a simpler example to report @emph{instead}
4521 of the original one, that is a convenience for us. Errors in the
4522 output will be easier to spot, running under the debugger will take
4523 less time, and so on.
4524
4525 However, simplification is not vital; if you do not want to do this,
4526 report the bug anyway and send us the entire test case you used.
4527
4528 @item
4529 A patch for the bug.
4530
4531 A patch for the bug does help us if it is a good one. But do not omit
4532 the necessary information, such as the test case, on the assumption that
4533 a patch is all we need. We might see problems with your patch and decide
4534 to fix the problem another way, or we might not understand it at all.
4535
4536 Sometimes with programs as complicated as the binary utilities it is
4537 very hard to construct an example that will make the program follow a
4538 certain path through the code. If you do not send us the example, we
4539 will not be able to construct one, so we will not be able to verify that
4540 the bug is fixed.
4541
4542 And if we cannot understand what bug you are trying to fix, or why your
4543 patch should be an improvement, we will not install it. A test case will
4544 help us to understand.
4545
4546 @item
4547 A guess about what the bug is or what it depends on.
4548
4549 Such guesses are usually wrong. Even we cannot guess right about such
4550 things without first using the debugger to find the facts.
4551 @end itemize
4552
4553 @node GNU Free Documentation License
4554 @appendix GNU Free Documentation License
4555
4556 @include fdl.texi
4557
4558 @node Binutils Index
4559 @unnumbered Binutils Index
4560
4561 @printindex cp
4562
4563 @bye
This page took 0.125561 seconds and 4 git commands to generate.