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