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