* Makefile.in: Revert 2001-06-17.
[deliverable/binutils-gdb.git] / binutils / binutils.texi
CommitLineData
252b5132
RH
1\input texinfo @c -*- Texinfo -*-
2@setfilename binutils.info
8c2bc687
NC
3@c Copyright 2001 Free Software Foundation, Inc.
4
252b5132
RH
5@include config.texi
6
7@ifinfo
8@format
9START-INFO-DIR-ENTRY
ad0481cd
AS
10* Binutils: (binutils). The GNU binary utilities.
11* ar: (binutils)ar. Create, modify, and extract from archives
12* nm: (binutils)nm. List symbols from object files
13* objcopy: (binutils)objcopy. Copy and translate object files
14* objdump: (binutils)objdump. Display information from object files
15* ranlib: (binutils)ranlib. Generate index to archive contents
16* readelf: (binutils)readelf. Display the contents of ELF format files.
17* size: (binutils)size. List section sizes and total size
18* strings: (binutils)strings. List printable strings from files
19* strip: (binutils)strip. Discard symbols
20* c++filt: (binutils)c++filt. Filter to demangle encoded C++ symbols
21* cxxfilt: (binutils)c++filt. MS-DOS name for c++filt
22* addr2line: (binutils)addr2line. Convert addresses to file and line
23* nlmconv: (binutils)nlmconv. Converts object code into an NLM
24* windres: (binutils)windres. Manipulate Windows resources
25* dlltool: (binutils)dlltool. Create files needed to build and use DLLs
252b5132
RH
26END-INFO-DIR-ENTRY
27@end format
28@end ifinfo
29
30@ifinfo
0285c67d 31@c man begin COPYRIGHT
18356cf2 32Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
252b5132 33
0285c67d
NC
34Permission is granted to copy, distribute and/or modify this document
35under the terms of the GNU Free Documentation License, Version 1.1
36or any later version published by the Free Software Foundation;
37with no Invariant Sections, with no Front-Cover Texts, and with no
38Back-Cover Texts. A copy of the license is included in the
39section entitled "GNU Free Documentation License".
252b5132 40
0285c67d 41@c man end
252b5132
RH
42@ignore
43Permission is granted to process this file through TeX and print the
44results, provided the printed document carries a copying permission
45notice identical to this one except for the removal of this paragraph
46(this paragraph not being relevant to the printed manual).
47
48@end ignore
252b5132
RH
49@end ifinfo
50
51@synindex ky cp
52@c
53@c This file documents the GNU binary utilities "ar", "ld", "objcopy",
54@c "objdump", "nm", "size", "strings", "strip", "readelf" and "ranlib".
55@c
18356cf2 56@c Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
252b5132
RH
57@c
58@c This text may be freely distributed under the terms of the GNU
cf055d54 59@c Free Documentation License.
252b5132
RH
60@c
61
62@setchapternewpage odd
63@settitle @sc{gnu} Binary Utilities
64@titlepage
65@finalout
66@title The @sc{gnu} Binary Utilities
67@subtitle Version @value{VERSION}
68@sp 1
69@subtitle May 1993
70@author Roland H. Pesch
71@author Jeffrey M. Osier
72@author Cygnus Support
73@page
74
75@tex
76{\parskip=0pt \hfill Cygnus Support\par \hfill
77\TeX{}info \texinfoversion\par }
78@end tex
79
80@vskip 0pt plus 1filll
18356cf2 81Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998, 2000, 2001 Free Software Foundation, Inc.
252b5132 82
cf055d54
NC
83 Permission is granted to copy, distribute and/or modify this document
84 under the terms of the GNU Free Documentation License, Version 1.1
85 or any later version published by the Free Software Foundation;
86 with no Invariant Sections, with no Front-Cover Texts, and with no
87 Back-Cover Texts. A copy of the license is included in the
88 section entitled "GNU Free Documentation License".
252b5132 89
252b5132
RH
90@end titlepage
91
92@node Top
93@top Introduction
94
95@cindex version
96This brief manual contains preliminary documentation for the @sc{gnu} binary
97utilities (collectively version @value{VERSION}):
98
99@iftex
100@table @code
101@item ar
102Create, modify, and extract from archives
103
104@item nm
105List symbols from object files
106
107@item objcopy
108Copy and translate object files
109
110@item objdump
111Display information from object files
112
113@item ranlib
114Generate index to archive contents
115
116@item readelf
117Display the contents of ELF format files.
118
119@item size
120List file section sizes and total size
121
122@item strings
123List printable strings from files
124
125@item strip
126Discard symbols
127
128@item c++filt
9d51cc66
ILT
129Demangle encoded C++ symbols (on MS-DOS, this program is named
130@code{cxxfilt})
252b5132
RH
131
132@item addr2line
133Convert addresses into file names and line numbers
134
135@item nlmconv
136Convert object code into a Netware Loadable Module
137
138@item windres
139Manipulate Windows resources
140
141@item dlltool
142Create the files needed to build and use Dynamic Link Libraries
143@end table
144@end iftex
145
cf055d54
NC
146This document is distributed under the terms of the GNU Free
147Documentation License. A copy of the license is included in the
148section entitled "GNU Free Documentation License".
149
252b5132
RH
150@menu
151* ar:: Create, modify, and extract from archives
152* nm:: List symbols from object files
153* objcopy:: Copy and translate object files
154* objdump:: Display information from object files
155* ranlib:: Generate index to archive contents
156* readelf:: Display the contents of ELF format files.
157* size:: List section sizes and total size
158* strings:: List printable strings from files
159* strip:: Discard symbols
160* c++filt:: Filter to demangle encoded C++ symbols
9d51cc66 161* cxxfilt: c++filt. MS-DOS name for c++filt
252b5132
RH
162* addr2line:: Convert addresses to file and line
163* nlmconv:: Converts object code into an NLM
164* windres:: Manipulate Windows resources
165* dlltool:: Create files needed to build and use DLLs
166* Selecting The Target System:: How these utilities determine the target.
167* Reporting Bugs:: Reporting Bugs
cf055d54 168* GNU Free Documentation License:: GNU Free Documentation License
252b5132
RH
169* Index:: Index
170@end menu
171
172@node ar
173@chapter ar
174
175@kindex ar
176@cindex archives
177@cindex collections of files
0285c67d
NC
178
179@c man title ar create, modify, and extract from archives
180
252b5132 181@smallexample
3de39064 182ar [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
252b5132
RH
183ar -M [ <mri-script ]
184@end smallexample
185
0285c67d
NC
186@c man begin DESCRIPTION ar
187
252b5132
RH
188The @sc{gnu} @code{ar} program creates, modifies, and extracts from
189archives. An @dfn{archive} is a single file holding a collection of
190other files in a structure that makes it possible to retrieve
191the original individual files (called @dfn{members} of the archive).
192
193The original files' contents, mode (permissions), timestamp, owner, and
194group are preserved in the archive, and can be restored on
195extraction.
196
197@cindex name length
198@sc{gnu} @code{ar} can maintain archives whose members have names of any
199length; however, depending on how @code{ar} is configured on your
200system, a limit on member-name length may be imposed for compatibility
201with archive formats maintained with other tools. If it exists, the
202limit is often 15 characters (typical of formats related to a.out) or 16
203characters (typical of formats related to coff).
204
205@cindex libraries
206@code{ar} is considered a binary utility because archives of this sort
207are most often used as @dfn{libraries} holding commonly needed
208subroutines.
209
210@cindex symbol index
211@code{ar} creates an index to the symbols defined in relocatable
212object modules in the archive when you specify the modifier @samp{s}.
213Once created, this index is updated in the archive whenever @code{ar}
214makes a change to its contents (save for the @samp{q} update operation).
215An archive with such an index speeds up linking to the library, and
216allows routines in the library to call each other without regard to
217their placement in the archive.
218
219You may use @samp{nm -s} or @samp{nm --print-armap} to list this index
220table. If an archive lacks the table, another form of @code{ar} called
221@code{ranlib} can be used to add just the table.
222
223@cindex compatibility, @code{ar}
224@cindex @code{ar} compatibility
225@sc{gnu} @code{ar} is designed to be compatible with two different
226facilities. You can control its activity using command-line options,
227like the different varieties of @code{ar} on Unix systems; or, if you
228specify the single command-line option @samp{-M}, you can control it
229with a script supplied via standard input, like the MRI ``librarian''
230program.
231
0285c67d
NC
232@c man end
233
252b5132
RH
234@menu
235* ar cmdline:: Controlling @code{ar} on the command line
236* ar scripts:: Controlling @code{ar} with a script
237@end menu
238
239@page
240@node ar cmdline
241@section Controlling @code{ar} on the command line
242
243@smallexample
0285c67d 244@c man begin SYNOPSIS ar
6e800839 245ar [-X32_64] [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
0285c67d 246@c man end
252b5132
RH
247@end smallexample
248
249@cindex Unix compatibility, @code{ar}
250When you use @code{ar} in the Unix style, @code{ar} insists on at least two
251arguments to execute: one keyletter specifying the @emph{operation}
252(optionally accompanied by other keyletters specifying
253@emph{modifiers}), and the archive name to act on.
254
255Most operations can also accept further @var{member} arguments,
256specifying particular files to operate on.
257
0285c67d
NC
258@c man begin OPTIONS ar
259
252b5132
RH
260@sc{gnu} @code{ar} allows you to mix the operation code @var{p} and modifier
261flags @var{mod} in any order, within the first command-line argument.
262
263If you wish, you may begin the first command-line argument with a
264dash.
265
266@cindex operations on archive
267The @var{p} keyletter specifies what operation to execute; it may be
268any of the following, but you must specify only one of them:
269
270@table @code
271@item d
272@cindex deleting from archive
273@emph{Delete} modules from the archive. Specify the names of modules to
274be deleted as @var{member}@dots{}; the archive is untouched if you
275specify no files to delete.
276
277If you specify the @samp{v} modifier, @code{ar} lists each module
278as it is deleted.
279
280@item m
281@cindex moving in archive
282Use this operation to @emph{move} members in an archive.
283
284The ordering of members in an archive can make a difference in how
285programs are linked using the library, if a symbol is defined in more
286than one member.
287
288If no modifiers are used with @code{m}, any members you name in the
289@var{member} arguments are moved to the @emph{end} of the archive;
290you can use the @samp{a}, @samp{b}, or @samp{i} modifiers to move them to a
291specified place instead.
292
293@item p
294@cindex printing from archive
295@emph{Print} the specified members of the archive, to the standard
296output file. If the @samp{v} modifier is specified, show the member
297name before copying its contents to standard output.
298
299If you specify no @var{member} arguments, all the files in the archive are
300printed.
301
302@item q
303@cindex quick append to archive
304@emph{Quick append}; Historically, add the files @var{member}@dots{} to the end of
305@var{archive}, without checking for replacement.
306
307The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this
308operation; new members are always placed at the end of the archive.
309
310The modifier @samp{v} makes @code{ar} list each file as it is appended.
311
312Since the point of this operation is speed, the archive's symbol table
313index is not updated, even if it already existed; you can use @samp{ar s} or
314@code{ranlib} explicitly to update the symbol table index.
315
316However, too many different systems assume quick append rebuilds the
317index, so GNU ar implements @code{q} as a synonym for @code{r}.
318
319@item r
320@cindex replacement in archive
321Insert the files @var{member}@dots{} into @var{archive} (with
322@emph{replacement}). This operation differs from @samp{q} in that any
323previously existing members are deleted if their names match those being
324added.
325
326If one of the files named in @var{member}@dots{} does not exist, @code{ar}
327displays an error message, and leaves undisturbed any existing members
328of the archive matching that name.
329
330By default, new members are added at the end of the file; but you may
331use one of the modifiers @samp{a}, @samp{b}, or @samp{i} to request
332placement relative to some existing member.
333
334The modifier @samp{v} used with this operation elicits a line of
335output for each file inserted, along with one of the letters @samp{a} or
336@samp{r} to indicate whether the file was appended (no old member
337deleted) or replaced.
338
339@item t
340@cindex contents of archive
341Display a @emph{table} listing the contents of @var{archive}, or those
342of the files listed in @var{member}@dots{} that are present in the
343archive. Normally only the member name is shown; if you also want to
344see the modes (permissions), timestamp, owner, group, and size, you can
345request that by also specifying the @samp{v} modifier.
346
347If you do not specify a @var{member}, all files in the archive
348are listed.
349
350@cindex repeated names in archive
351@cindex name duplication in archive
352If there is more than one file with the same name (say, @samp{fie}) in
353an archive (say @samp{b.a}), @samp{ar t b.a fie} lists only the
354first instance; to see them all, you must ask for a complete
355listing---in our example, @samp{ar t b.a}.
356@c WRS only; per Gumby, this is implementation-dependent, and in a more
357@c recent case in fact works the other way.
358
359@item x
360@cindex extract from archive
361@emph{Extract} members (named @var{member}) from the archive. You can
362use the @samp{v} modifier with this operation, to request that
363@code{ar} list each name as it extracts it.
364
365If you do not specify a @var{member}, all files in the archive
366are extracted.
367
368@end table
369
370A number of modifiers (@var{mod}) may immediately follow the @var{p}
371keyletter, to specify variations on an operation's behavior:
372
373@table @code
374@item a
375@cindex relative placement in archive
376Add new files @emph{after} an existing member of the
377archive. If you use the modifier @samp{a}, the name of an existing archive
378member must be present as the @var{relpos} argument, before the
379@var{archive} specification.
380
381@item b
382Add new files @emph{before} an existing member of the
383archive. If you use the modifier @samp{b}, the name of an existing archive
384member must be present as the @var{relpos} argument, before the
385@var{archive} specification. (same as @samp{i}).
386
387@item c
388@cindex creating archives
389@emph{Create} the archive. The specified @var{archive} is always
390created if it did not exist, when you request an update. But a warning is
391issued unless you specify in advance that you expect to create it, by
392using this modifier.
393
394@item f
395Truncate names in the archive. @sc{gnu} @code{ar} will normally permit file
396names of any length. This will cause it to create archives which are
397not compatible with the native @code{ar} program on some systems. If
398this is a concern, the @samp{f} modifier may be used to truncate file
399names when putting them in the archive.
400
401@item i
402Insert new files @emph{before} an existing member of the
403archive. If you use the modifier @samp{i}, the name of an existing archive
404member must be present as the @var{relpos} argument, before the
405@var{archive} specification. (same as @samp{b}).
406
407@item l
408This modifier is accepted but not used.
409@c whaffor ar l modifier??? presumably compat; with
410@c what???---doc@@cygnus.com, 25jan91
411
3de39064
ILT
412@item N
413Uses the @var{count} parameter. This is used if there are multiple
414entries in the archive with the same name. Extract or delete instance
415@var{count} of the given name from the archive.
416
252b5132
RH
417@item o
418@cindex dates in archive
419Preserve the @emph{original} dates of members when extracting them. If
420you do not specify this modifier, files extracted from the archive
421are stamped with the time of extraction.
422
3de39064
ILT
423@item P
424Use the full path name when matching names in the archive. @sc{gnu}
425@code{ar} can not create an archive with a full path name (such archives
426are not POSIX complaint), but other archive creators can. This option
427will cause @sc{gnu} @code{ar} to match file names using a complete path
428name, which can be convenient when extracting a single file from an
429archive created by another tool.
430
252b5132
RH
431@item s
432@cindex writing archive index
433Write an object-file index into the archive, or update an existing one,
434even if no other change is made to the archive. You may use this modifier
435flag either with any operation, or alone. Running @samp{ar s} on an
436archive is equivalent to running @samp{ranlib} on it.
437
438@item S
439@cindex not writing archive index
440Do not generate an archive symbol table. This can speed up building a
441large library in several steps. The resulting archive can not be used
442with the linker. In order to build a symbol table, you must omit the
443@samp{S} modifier on the last execution of @samp{ar}, or you must run
444@samp{ranlib} on the archive.
445
446@item u
447@cindex updating an archive
448Normally, @samp{ar r}@dots{} inserts all files
449listed into the archive. If you would like to insert @emph{only} those
450of the files you list that are newer than existing members of the same
451names, use this modifier. The @samp{u} modifier is allowed only for the
452operation @samp{r} (replace). In particular, the combination @samp{qu} is
453not allowed, since checking the timestamps would lose any speed
454advantage from the operation @samp{q}.
455
456@item v
457This modifier requests the @emph{verbose} version of an operation. Many
458operations display additional information, such as filenames processed,
459when the modifier @samp{v} is appended.
460
461@item V
462This modifier shows the version number of @code{ar}.
463@end table
464
6e800839
GK
465@code{ar} ignores an initial option spelt @code{-X32_64}, for
466compatibility with AIX. The behaviour produced by this option is the
467default for GNU @code{ar}. @code{ar} does not support any of the other
468@code{-X} options; in particular, it does not support @code{-X32}
469which is the default for AIX @code{ar}.
470
0285c67d
NC
471@c man end
472
473@ignore
474@c man begin SEEALSO ar
475nm(1), ranlib(1), and the Info entries for @file{binutils}.
476@c man end
477@end ignore
478
252b5132
RH
479@node ar scripts
480@section Controlling @code{ar} with a script
481
482@smallexample
483ar -M [ <@var{script} ]
484@end smallexample
485
486@cindex MRI compatibility, @code{ar}
487@cindex scripts, @code{ar}
488If you use the single command-line option @samp{-M} with @code{ar}, you
489can control its operation with a rudimentary command language. This
490form of @code{ar} operates interactively if standard input is coming
491directly from a terminal. During interactive use, @code{ar} prompts for
492input (the prompt is @samp{AR >}), and continues executing even after
493errors. If you redirect standard input to a script file, no prompts are
494issued, and @code{ar} abandons execution (with a nonzero exit code)
495on any error.
496
497The @code{ar} command language is @emph{not} designed to be equivalent
498to the command-line options; in fact, it provides somewhat less control
499over archives. The only purpose of the command language is to ease the
500transition to @sc{gnu} @code{ar} for developers who already have scripts
501written for the MRI ``librarian'' program.
502
503The syntax for the @code{ar} command language is straightforward:
504@itemize @bullet
505@item
506commands are recognized in upper or lower case; for example, @code{LIST}
507is the same as @code{list}. In the following descriptions, commands are
508shown in upper case for clarity.
509
510@item
511a single command may appear on each line; it is the first word on the
512line.
513
514@item
515empty lines are allowed, and have no effect.
516
517@item
518comments are allowed; text after either of the characters @samp{*}
519or @samp{;} is ignored.
520
521@item
522Whenever you use a list of names as part of the argument to an @code{ar}
523command, you can separate the individual names with either commas or
524blanks. Commas are shown in the explanations below, for clarity.
525
526@item
527@samp{+} is used as a line continuation character; if @samp{+} appears
528at the end of a line, the text on the following line is considered part
529of the current command.
530@end itemize
531
532Here are the commands you can use in @code{ar} scripts, or when using
533@code{ar} interactively. Three of them have special significance:
534
535@code{OPEN} or @code{CREATE} specify a @dfn{current archive}, which is
536a temporary file required for most of the other commands.
537
538@code{SAVE} commits the changes so far specified by the script. Prior
539to @code{SAVE}, commands affect only the temporary copy of the current
540archive.
541
542@table @code
543@item ADDLIB @var{archive}
544@itemx ADDLIB @var{archive} (@var{module}, @var{module}, @dots{} @var{module})
545Add all the contents of @var{archive} (or, if specified, each named
546@var{module} from @var{archive}) to the current archive.
547
548Requires prior use of @code{OPEN} or @code{CREATE}.
549
550@item ADDMOD @var{member}, @var{member}, @dots{} @var{member}
551@c FIXME! w/Replacement?? If so, like "ar r @var{archive} @var{names}"
552@c else like "ar q..."
553Add each named @var{member} as a module in the current archive.
554
555Requires prior use of @code{OPEN} or @code{CREATE}.
556
557@item CLEAR
558Discard the contents of the current archive, canceling the effect of
559any operations since the last @code{SAVE}. May be executed (with no
560effect) even if no current archive is specified.
561
562@item CREATE @var{archive}
563Creates an archive, and makes it the current archive (required for many
564other commands). The new archive is created with a temporary name; it
565is not actually saved as @var{archive} until you use @code{SAVE}.
566You can overwrite existing archives; similarly, the contents of any
567existing file named @var{archive} will not be destroyed until @code{SAVE}.
568
569@item DELETE @var{module}, @var{module}, @dots{} @var{module}
570Delete each listed @var{module} from the current archive; equivalent to
571@samp{ar -d @var{archive} @var{module} @dots{} @var{module}}.
572
573Requires prior use of @code{OPEN} or @code{CREATE}.
574
575@item DIRECTORY @var{archive} (@var{module}, @dots{} @var{module})
576@itemx DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) @var{outputfile}
577List each named @var{module} present in @var{archive}. The separate
578command @code{VERBOSE} specifies the form of the output: when verbose
579output is off, output is like that of @samp{ar -t @var{archive}
580@var{module}@dots{}}. When verbose output is on, the listing is like
581@samp{ar -tv @var{archive} @var{module}@dots{}}.
582
583Output normally goes to the standard output stream; however, if you
584specify @var{outputfile} as a final argument, @code{ar} directs the
585output to that file.
586
587@item END
588Exit from @code{ar}, with a @code{0} exit code to indicate successful
589completion. This command does not save the output file; if you have
590changed the current archive since the last @code{SAVE} command, those
591changes are lost.
592
593@item EXTRACT @var{module}, @var{module}, @dots{} @var{module}
594Extract each named @var{module} from the current archive, writing them
595into the current directory as separate files. Equivalent to @samp{ar -x
596@var{archive} @var{module}@dots{}}.
597
598Requires prior use of @code{OPEN} or @code{CREATE}.
599
600@ignore
601@c FIXME Tokens but no commands???
602@item FULLDIR
603
604@item HELP
605@end ignore
606
607@item LIST
608Display full contents of the current archive, in ``verbose'' style
609regardless of the state of @code{VERBOSE}. The effect is like @samp{ar
c89746f6 610tv @var{archive}}. (This single command is a @sc{gnu} @code{ar}
252b5132
RH
611enhancement, rather than present for MRI compatibility.)
612
613Requires prior use of @code{OPEN} or @code{CREATE}.
614
615@item OPEN @var{archive}
616Opens an existing archive for use as the current archive (required for
617many other commands). Any changes as the result of subsequent commands
618will not actually affect @var{archive} until you next use @code{SAVE}.
619
620@item REPLACE @var{module}, @var{module}, @dots{} @var{module}
621In the current archive, replace each existing @var{module} (named in
622the @code{REPLACE} arguments) from files in the current working directory.
623To execute this command without errors, both the file, and the module in
624the current archive, must exist.
625
626Requires prior use of @code{OPEN} or @code{CREATE}.
627
628@item VERBOSE
629Toggle an internal flag governing the output from @code{DIRECTORY}.
630When the flag is on, @code{DIRECTORY} output matches output from
631@samp{ar -tv }@dots{}.
632
633@item SAVE
634Commit your changes to the current archive, and actually save it as a
635file with the name specified in the last @code{CREATE} or @code{OPEN}
636command.
637
638Requires prior use of @code{OPEN} or @code{CREATE}.
639
640@end table
641
642@iftex
643@node ld
644@chapter ld
645@cindex linker
646@kindex ld
647The @sc{gnu} linker @code{ld} is now described in a separate manual.
648@xref{Top,, Overview,, Using LD: the @sc{gnu} linker}.
649@end iftex
650
651@node nm
652@chapter nm
653@cindex symbols
654@kindex nm
655
0285c67d
NC
656@c man title nm list symbols from object files
657
252b5132 658@smallexample
0285c67d 659@c man begin SYNOPSIS nm
252b5132 660nm [ -a | --debug-syms ] [ -g | --extern-only ]
28c309a2 661 [ -B ] [ -C | --demangle[=@var{style}] ] [ -D | --dynamic ]
252b5132
RH
662 [ -s | --print-armap ] [ -A | -o | --print-file-name ]
663 [ -n | -v | --numeric-sort ] [ -p | --no-sort ]
664 [ -r | --reverse-sort ] [ --size-sort ] [ -u | --undefined-only ]
665 [ -t @var{radix} | --radix=@var{radix} ] [ -P | --portability ]
666 [ --target=@var{bfdname} ] [ -f @var{format} | --format=@var{format} ]
6e800839
GK
667 [ --defined-only ] [-l | --line-numbers ] [ --no-demangle ]
668 [ -V | --version ] [ -X 32_64 ] [ --help ] [ @var{objfile}@dots{} ]
0285c67d 669@c man end
252b5132
RH
670@end smallexample
671
0285c67d 672@c man begin DESCRIPTION nm
252b5132 673@sc{gnu} @code{nm} lists the symbols from object files @var{objfile}@dots{}.
f20a759a 674If no object files are listed as arguments, @code{nm} assumes the file
252b5132
RH
675@file{a.out}.
676
677For each symbol, @code{nm} shows:
678
679@itemize @bullet
680@item
681The symbol value, in the radix selected by options (see below), or
682hexadecimal by default.
683
684@item
685The symbol type. At least the following types are used; others are, as
686well, depending on the object file format. If lowercase, the symbol is
687local; if uppercase, the symbol is global (external).
688
689@c Some more detail on exactly what these symbol types are used for
690@c would be nice.
691@table @code
692@item A
693The symbol's value is absolute, and will not be changed by further
694linking.
695
696@item B
697The symbol is in the uninitialized data section (known as BSS).
698
699@item C
700The symbol is common. Common symbols are uninitialized data. When
701linking, multiple common symbols may appear with the same name. If the
702symbol is defined anywhere, the common symbols are treated as undefined
0285c67d
NC
703references.
704@ifclear man
705For more details on common symbols, see the discussion of
252b5132 706--warn-common in @ref{Options,,Linker options,ld.info,The GNU linker}.
0879a67a 707@end ifclear
252b5132
RH
708
709@item D
710The symbol is in the initialized data section.
711
712@item G
713The symbol is in an initialized data section for small objects. Some
714object file formats permit more efficient access to small data objects,
715such as a global int variable as opposed to a large global array.
716
717@item I
718The symbol is an indirect reference to another symbol. This is a GNU
719extension to the a.out object file format which is rarely used.
720
721@item N
722The symbol is a debugging symbol.
723
724@item R
725The symbol is in a read only data section.
726
727@item S
728The symbol is in an uninitialized data section for small objects.
729
730@item T
731The symbol is in the text (code) section.
732
733@item U
734The symbol is undefined.
735
fad6fcbb
NC
736@item V
737The symbol is a weak object. When a weak defined symbol is linked with
738a normal defined symbol, the normal defined symbol is used with no error.
739When a weak undefined symbol is linked and the symbol is not defined,
740the value of the weak symbol becomes zero with no error.
741
252b5132 742@item W
fad6fcbb
NC
743The symbol is a weak symbol that has not been specifically tagged as a
744weak object symbol. When a weak defined symbol is linked with a normal
745defined symbol, the normal defined symbol is used with no error.
746When a weak undefined symbol is linked and the symbol is not defined,
747the value of the weak symbol becomes zero with no error.
252b5132
RH
748
749@item -
750The symbol is a stabs symbol in an a.out object file. In this case, the
751next values printed are the stabs other field, the stabs desc field, and
752the stab type. Stabs symbols are used to hold debugging information;
753for more information, see @ref{Top,Stabs,Stabs Overview,stabs.info, The
754``stabs'' debug format}.
755
756@item ?
757The symbol type is unknown, or object file format specific.
758@end table
759
760@item
761The symbol name.
762@end itemize
763
0285c67d
NC
764@c man end
765
766@c man begin OPTIONS nm
252b5132
RH
767The long and short forms of options, shown here as alternatives, are
768equivalent.
769
770@table @code
771@item -A
772@itemx -o
773@itemx --print-file-name
774@cindex input file name
775@cindex file name
776@cindex source file name
f20a759a 777Precede each symbol by the name of the input file (or archive member)
252b5132
RH
778in which it was found, rather than identifying the input file once only,
779before all of its symbols.
780
781@item -a
782@itemx --debug-syms
783@cindex debugging symbols
784Display all symbols, even debugger-only symbols; normally these are not
785listed.
786
787@item -B
788@cindex @code{nm} format
789@cindex @code{nm} compatibility
790The same as @samp{--format=bsd} (for compatibility with the MIPS @code{nm}).
791
792@item -C
28c309a2 793@itemx --demangle[=@var{style}]
252b5132
RH
794@cindex demangling in nm
795Decode (@dfn{demangle}) low-level symbol names into user-level names.
796Besides removing any initial underscore prepended by the system, this
28c309a2
NC
797makes C++ function names readable. Different compilers have different
798mangling styles. The optional demangling style argument can be used to
799choose an appropriate demangling style for your compiler. @xref{c++filt},
800for more information on demangling.
252b5132
RH
801
802@item --no-demangle
803Do not demangle low-level symbol names. This is the default.
804
805@item -D
806@itemx --dynamic
807@cindex dynamic symbols
808Display the dynamic symbols rather than the normal symbols. This is
809only meaningful for dynamic objects, such as certain types of shared
810libraries.
811
812@item -f @var{format}
813@itemx --format=@var{format}
814@cindex @code{nm} format
815@cindex @code{nm} compatibility
816Use the output format @var{format}, which can be @code{bsd},
817@code{sysv}, or @code{posix}. The default is @code{bsd}.
818Only the first character of @var{format} is significant; it can be
819either upper or lower case.
820
821@item -g
822@itemx --extern-only
823@cindex external symbols
824Display only external symbols.
825
826@item -l
827@itemx --line-numbers
828@cindex symbol line numbers
829For each symbol, use debugging information to try to find a filename and
830line number. For a defined symbol, look for the line number of the
831address of the symbol. For an undefined symbol, look for the line
832number of a relocation entry which refers to the symbol. If line number
833information can be found, print it after the other symbol information.
834
835@item -n
836@itemx -v
837@itemx --numeric-sort
838Sort symbols numerically by their addresses, rather than alphabetically
839by their names.
840
841@item -p
842@itemx --no-sort
843@cindex sorting symbols
844Do not bother to sort the symbols in any order; print them in the order
845encountered.
846
847@item -P
848@itemx --portability
849Use the POSIX.2 standard output format instead of the default format.
850Equivalent to @samp{-f posix}.
851
852@item -s
853@itemx --print-armap
854@cindex symbol index, listing
855When listing symbols from archive members, include the index: a mapping
856(stored in the archive by @code{ar} or @code{ranlib}) of which modules
857contain definitions for which names.
858
859@item -r
860@itemx --reverse-sort
861Reverse the order of the sort (whether numeric or alphabetic); let the
862last come first.
863
864@item --size-sort
865Sort symbols by size. The size is computed as the difference between
866the value of the symbol and the value of the symbol with the next higher
867value. The size of the symbol is printed, rather than the value.
868
869@item -t @var{radix}
870@itemx --radix=@var{radix}
871Use @var{radix} as the radix for printing the symbol values. It must be
872@samp{d} for decimal, @samp{o} for octal, or @samp{x} for hexadecimal.
873
874@item --target=@var{bfdname}
875@cindex object code format
876Specify an object code format other than your system's default format.
877@xref{Target Selection}, for more information.
878
879@item -u
880@itemx --undefined-only
881@cindex external symbols
882@cindex undefined symbols
883Display only undefined symbols (those external to each object file).
884
885@item --defined-only
886@cindex external symbols
887@cindex undefined symbols
888Display only defined symbols for each object file.
889
890@item -V
891@itemx --version
892Show the version number of @code{nm} and exit.
893
6e800839
GK
894@item -X
895This option is ignored for compatibility with the AIX version of
896@code{nm}. It takes one parameter which must be the string
897@code{32_64}. The default mode of AIX @code{nm} corresponds
898to @code{-X 32}, which is not supported by @sc{gnu} @code{nm}.
899
252b5132
RH
900@item --help
901Show a summary of the options to @code{nm} and exit.
902@end table
903
0285c67d
NC
904@c man end
905
906@ignore
907@c man begin SEEALSO nm
908ar(1), objdump(1), ranlib(1), and the Info entries for @file{binutils}.
909@c man end
910@end ignore
911
252b5132
RH
912@node objcopy
913@chapter objcopy
914
0285c67d
NC
915@c man title objcopy copy and translate object files
916
252b5132 917@smallexample
0285c67d 918@c man begin SYNOPSIS objcopy
252b5132
RH
919objcopy [ -F @var{bfdname} | --target=@var{bfdname} ]
920 [ -I @var{bfdname} | --input-target=@var{bfdname} ]
921 [ -O @var{bfdname} | --output-target=@var{bfdname} ]
43a0748c 922 [ -B @var{bfdarch} | --binary-architecture=@var{bfdarch} ]
252b5132
RH
923 [ -S | --strip-all ] [ -g | --strip-debug ]
924 [ -K @var{symbolname} | --keep-symbol=@var{symbolname} ]
925 [ -N @var{symbolname} | --strip-symbol=@var{symbolname} ]
16b2b71c 926 [ -G @var{symbolname} | --keep-global-symbol=@var{symbolname}]
252b5132
RH
927 [ -L @var{symbolname} | --localize-symbol=@var{symbolname} ]
928 [ -W @var{symbolname} | --weaken-symbol=@var{symbolname} ]
929 [ -x | --discard-all ] [ -X | --discard-locals ]
930 [ -b @var{byte} | --byte=@var{byte} ]
931 [ -i @var{interleave} | --interleave=@var{interleave} ]
f91ea849 932 [ -j @var{sectionname} | --only-section=@var{sectionname} ]
252b5132
RH
933 [ -R @var{sectionname} | --remove-section=@var{sectionname} ]
934 [ -p | --preserve-dates ] [ --debugging ]
935 [ --gap-fill=@var{val} ] [ --pad-to=@var{address} ]
936 [ --set-start=@var{val} ] [ --adjust-start=@var{incr} ]
937 [ --change-addresses=@var{incr} ]
57938635
AM
938 [ --change-section-address @var{section}@{=,+,-@}@var{val} ]
939 [ --change-section-lma @var{section}@{=,+,-@}@var{val} ]
940 [ --change-section-vma @var{section}@{=,+,-@}@var{val} ]
252b5132 941 [ --change-warnings ] [ --no-change-warnings ]
57938635
AM
942 [ --set-section-flags @var{section}=@var{flags} ]
943 [ --add-section @var{sectionname}=@var{filename} ]
252b5132 944 [ --change-leading-char ] [ --remove-leading-char ]
420496c1 945 [ --srec-len=@var{ival} ] [ --srec-forceS3 ]
57938635 946 [ --redefine-sym @var{old}=@var{new} ] [ --weaken ]
16b2b71c
NC
947 [ --keep-symbols=@var{filename} ]
948 [ --strip-symbols=@var{filename} ]
949 [ --keep-global-symbols=@var{filename} ]
950 [ --localize-symbols=@var{filename} ]
951 [ --weaken-symbols=@var{filename} ]
252b5132
RH
952 [ -v | --verbose ] [ -V | --version ] [ --help ]
953 @var{infile} [@var{outfile}]
0285c67d 954@c man end
252b5132
RH
955@end smallexample
956
0285c67d 957@c man begin DESCRIPTION objcopy
252b5132
RH
958The @sc{gnu} @code{objcopy} utility copies the contents of an object
959file to another. @code{objcopy} uses the @sc{gnu} @sc{bfd} Library to
960read and write the object files. It can write the destination object
961file in a format different from that of the source object file. The
962exact behavior of @code{objcopy} is controlled by command-line options.
ccd13d18
L
963Note that @code{objcopy} should be able to copy a fully linked file
964between any two formats. However, copying a relocatable object file
965between any two formats may not work as expected.
252b5132
RH
966
967@code{objcopy} creates temporary files to do its translations and
968deletes them afterward. @code{objcopy} uses @sc{bfd} to do all its
969translation work; it has access to all the formats described in @sc{bfd}
970and thus is able to recognize most formats without being told
971explicitly. @xref{BFD,,BFD,ld.info,Using LD}.
972
973@code{objcopy} can be used to generate S-records by using an output
974target of @samp{srec} (e.g., use @samp{-O srec}).
975
976@code{objcopy} can be used to generate a raw binary file by using an
977output target of @samp{binary} (e.g., use @samp{-O binary}). When
978@code{objcopy} generates a raw binary file, it will essentially produce
979a memory dump of the contents of the input object file. All symbols and
980relocation information will be discarded. The memory dump will start at
981the load address of the lowest section copied into the output file.
982
983When generating an S-record or a raw binary file, it may be helpful to
984use @samp{-S} to remove sections containing debugging information. In
985some cases @samp{-R} will be useful to remove sections which contain
f20a759a 986information that is not needed by the binary file.
252b5132 987
18356cf2
NC
988Note - @code{objcopy} is not able to change the endianness of its input
989files. If the input format has an endianness, (some formats do not),
990@code{objcopy} can only copy the inputs into file formats that have the
991same endianness or which have no endianness (eg @samp{srec}).
992
0285c67d
NC
993@c man end
994
995@c man begin OPTIONS objcopy
996
252b5132
RH
997@table @code
998@item @var{infile}
999@itemx @var{outfile}
f20a759a 1000The input and output files, respectively.
252b5132
RH
1001If you do not specify @var{outfile}, @code{objcopy} creates a
1002temporary file and destructively renames the result with
1003the name of @var{infile}.
1004
1005@item -I @var{bfdname}
1006@itemx --input-target=@var{bfdname}
1007Consider the source file's object format to be @var{bfdname}, rather than
1008attempting to deduce it. @xref{Target Selection}, for more information.
1009
1010@item -O @var{bfdname}
1011@itemx --output-target=@var{bfdname}
1012Write the output file using the object format @var{bfdname}.
1013@xref{Target Selection}, for more information.
1014
1015@item -F @var{bfdname}
1016@itemx --target=@var{bfdname}
1017Use @var{bfdname} as the object format for both the input and the output
1018file; i.e., simply transfer data from source to destination with no
1019translation. @xref{Target Selection}, for more information.
1020
43a0748c
NC
1021@item -B @var{bfdarch}
1022@itemx --binary-architecture=@var{bfdarch}
1023Useful when transforming a raw binary input file into an object file.
1024In this case the output architecture can be set to @var{bfdarch}. This
1025option will be ignored if the input file has a known @var{bfdarch}. You
1026can access this binary data inside a program by referencing the special
1027symbols that are created by the conversion process. These symbols are
1028called _binary_@var{objfile}_start, _binary_@var{objfile}_end and
1029_binary_@var{objfile}_size. e.g. you can transform a picture file into
1030an object file and then access it in your code using these symbols.
1031
f91ea849
ILT
1032@item -j @var{sectionname}
1033@itemx --only-section=@var{sectionname}
1034Copy only the named section from the input file to the output file.
1035This option may be given more than once. Note that using this option
1036inappropriately may make the output file unusable.
1037
252b5132
RH
1038@item -R @var{sectionname}
1039@itemx --remove-section=@var{sectionname}
1040Remove any section named @var{sectionname} from the output file. This
1041option may be given more than once. Note that using this option
1042inappropriately may make the output file unusable.
1043
1044@item -S
1045@itemx --strip-all
1046Do not copy relocation and symbol information from the source file.
1047
1048@item -g
1049@itemx --strip-debug
1050Do not copy debugging symbols from the source file.
1051
1052@item --strip-unneeded
1053Strip all symbols that are not needed for relocation processing.
1054
1055@item -K @var{symbolname}
1056@itemx --keep-symbol=@var{symbolname}
1057Copy only symbol @var{symbolname} from the source file. This option may
1058be given more than once.
1059
1060@item -N @var{symbolname}
1061@itemx --strip-symbol=@var{symbolname}
1062Do not copy symbol @var{symbolname} from the source file. This option
1063may be given more than once.
1064
16b2b71c
NC
1065@item -G @var{symbolname}
1066@itemx --keep-global-symbol=@var{symbolname}
1067Keep only symbol @var{symbolname} global. Make all other symbols local
1068to the file, so that they are not visible externally. This option may
1069be given more than once.
1070
252b5132
RH
1071@item -L @var{symbolname}
1072@itemx --localize-symbol=@var{symbolname}
1073Make symbol @var{symbolname} local to the file, so that it is not
1074visible externally. This option may be given more than once.
1075
1076@item -W @var{symbolname}
1077@itemx --weaken-symbol=@var{symbolname}
1078Make symbol @var{symbolname} weak. This option may be given more than once.
1079
1080@item -x
1081@itemx --discard-all
1082Do not copy non-global symbols from the source file.
1083@c FIXME any reason to prefer "non-global" to "local" here?
1084
1085@item -X
1086@itemx --discard-locals
1087Do not copy compiler-generated local symbols.
1088(These usually start with @samp{L} or @samp{.}.)
1089
1090@item -b @var{byte}
1091@itemx --byte=@var{byte}
1092Keep only every @var{byte}th byte of the input file (header data is not
1093affected). @var{byte} can be in the range from 0 to @var{interleave}-1,
1094where @var{interleave} is given by the @samp{-i} or @samp{--interleave}
1095option, or the default of 4. This option is useful for creating files
1096to program @sc{rom}. It is typically used with an @code{srec} output
1097target.
1098
1099@item -i @var{interleave}
1100@itemx --interleave=@var{interleave}
1101Only copy one out of every @var{interleave} bytes. Select which byte to
1102copy with the @var{-b} or @samp{--byte} option. The default is 4.
1103@code{objcopy} ignores this option if you do not specify either @samp{-b} or
1104@samp{--byte}.
1105
1106@item -p
1107@itemx --preserve-dates
1108Set the access and modification dates of the output file to be the same
1109as those of the input file.
1110
1111@item --debugging
1112Convert debugging information, if possible. This is not the default
1113because only certain debugging formats are supported, and the
1114conversion process can be time consuming.
1115
1116@item --gap-fill @var{val}
1117Fill gaps between sections with @var{val}. This operation applies to
1118the @emph{load address} (LMA) of the sections. It is done by increasing
1119the size of the section with the lower address, and filling in the extra
1120space created with @var{val}.
1121
1122@item --pad-to @var{address}
1123Pad the output file up to the load address @var{address}. This is
1124done by increasing the size of the last section. The extra space is
1125filled in with the value specified by @samp{--gap-fill} (default zero).
1126
1127@item --set-start @var{val}
f20a759a 1128Set the start address of the new file to @var{val}. Not all object file
252b5132
RH
1129formats support setting the start address.
1130
1131@item --change-start @var{incr}
1132@itemx --adjust-start @var{incr}
1133@cindex changing start address
1134Change the start address by adding @var{incr}. Not all object file
1135formats support setting the start address.
1136
1137@item --change-addresses @var{incr}
1138@itemx --adjust-vma @var{incr}
1139@cindex changing object addresses
1140Change the VMA and LMA addresses of all sections, as well as the start
1141address, by adding @var{incr}. Some object file formats do not permit
1142section addresses to be changed arbitrarily. Note that this does not
1143relocate the sections; if the program expects sections to be loaded at a
1144certain address, and this option is used to change the sections such
1145that they are loaded at a different address, the program may fail.
1146
1147@item --change-section-address @var{section}@{=,+,-@}@var{val}
1148@itemx --adjust-section-vma @var{section}@{=,+,-@}@var{val}
1149@cindex changing section address
1150Set or change both the VMA address and the LMA address of the named
1151@var{section}. If @samp{=} is used, the section address is set to
1152@var{val}. Otherwise, @var{val} is added to or subtracted from the
1153section address. See the comments under @samp{--change-addresses},
1154above. If @var{section} does not exist in the input file, a warning will
1155be issued, unless @samp{--no-change-warnings} is used.
1156
1157@item --change-section-lma @var{section}@{=,+,-@}@var{val}
1158@cindex changing section LMA
1159Set or change the LMA address of the named @var{section}. The LMA
1160address is the address where the section will be loaded into memory at
1161program load time. Normally this is the same as the VMA address, which
1162is the address of the section at program run time, but on some systems,
1163especially those where a program is held in ROM, the two can be
1164different. If @samp{=} is used, the section address is set to
1165@var{val}. Otherwise, @var{val} is added to or subtracted from the
1166section address. See the comments under @samp{--change-addresses},
1167above. If @var{section} does not exist in the input file, a warning
1168will be issued, unless @samp{--no-change-warnings} is used.
1169
1170@item --change-section-vma @var{section}@{=,+,-@}@var{val}
1171@cindex changing section VMA
1172Set or change the VMA address of the named @var{section}. The VMA
1173address is the address where the section will be located once the
1174program has started executing. Normally this is the same as the LMA
1175address, which is the address where the section will be loaded into
1176memory, but on some systems, especially those where a program is held in
1177ROM, the two can be different. If @samp{=} is used, the section address
1178is set to @var{val}. Otherwise, @var{val} is added to or subtracted
1179from the section address. See the comments under
1180@samp{--change-addresses}, above. If @var{section} does not exist in
1181the input file, a warning will be issued, unless
1182@samp{--no-change-warnings} is used.
1183
1184@item --change-warnings
1185@itemx --adjust-warnings
1186If @samp{--change-section-address} or @samp{--change-section-lma} or
1187@samp{--change-section-vma} is used, and the named section does not
1188exist, issue a warning. This is the default.
1189
1190@item --no-change-warnings
1191@itemx --no-adjust-warnings
1192Do not issue a warning if @samp{--change-section-address} or
1193@samp{--adjust-section-lma} or @samp{--adjust-section-vma} is used, even
1194if the named section does not exist.
1195
1196@item --set-section-flags @var{section}=@var{flags}
1197Set the flags for the named section. The @var{flags} argument is a
1198comma separated string of flag names. The recognized names are
3994e2c6
ILT
1199@samp{alloc}, @samp{contents}, @samp{load}, @samp{noload},
1200@samp{readonly}, @samp{code}, @samp{data}, @samp{rom}, @samp{share}, and
1201@samp{debug}. You can set the @samp{contents} flag for a section which
1202does not have contents, but it is not meaningful to clear the
1203@samp{contents} flag of a section which does have contents--just remove
1204the section instead. Not all flags are meaningful for all object file
1205formats.
252b5132
RH
1206
1207@item --add-section @var{sectionname}=@var{filename}
1208Add a new section named @var{sectionname} while copying the file. The
1209contents of the new section are taken from the file @var{filename}. The
1210size of the section will be the size of the file. This option only
1211works on file formats which can support sections with arbitrary names.
1212
1213@item --change-leading-char
1214Some object file formats use special characters at the start of
1215symbols. The most common such character is underscore, which compilers
1216often add before every symbol. This option tells @code{objcopy} to
1217change the leading character of every symbol when it converts between
1218object file formats. If the object file formats use the same leading
1219character, this option has no effect. Otherwise, it will add a
1220character, or remove a character, or change a character, as
1221appropriate.
1222
1223@item --remove-leading-char
1224If the first character of a global symbol is a special symbol leading
1225character used by the object file format, remove the character. The
1226most common symbol leading character is underscore. This option will
1227remove a leading underscore from all global symbols. This can be useful
1228if you want to link together objects of different file formats with
1229different conventions for symbol names. This is different from
1230@code{--change-leading-char} because it always changes the symbol name
1231when appropriate, regardless of the object file format of the output
1232file.
1233
420496c1
NC
1234@item --srec-len=@var{ival}
1235Meaningful only for srec output. Set the maximum length of the Srecords
1236being produced to @var{ival}. This length covers both address, data and
1237crc fields.
1238
1239@item --srec-forceS3
1240Meaningful only for srec output. Avoid generation of S1/S2 records,
1241creating S3-only record format.
1242
57938635
AM
1243@item --redefine-sym @var{old}=@var{new}
1244Change the name of a symbol @var{old}, to @var{new}. This can be useful
1245when one is trying link two things together for which you have no
1246source, and there are name collisions.
1247
252b5132
RH
1248@item --weaken
1249Change all global symbols in the file to be weak. This can be useful
1250when building an object which will be linked against other objects using
1251the @code{-R} option to the linker. This option is only effective when
1252using an object file format which supports weak symbols.
1253
16b2b71c
NC
1254@item --keep-symbols=@var{filename}
1255Apply @samp{--keep-symbol} option to each symbol listed in the file
1256@var{filename}. @var{filename} is simply a flat file, with one symbol
1257name per line. Line comments may be introduced by the hash character.
1258This option may be given more than once.
1259
1260@item --strip-symbols=@var{filename}
1261Apply @samp{--strip-symbol} option to each symbol listed in the file
1262@var{filename}. @var{filename} is simply a flat file, with one symbol
1263name per line. Line comments may be introduced by the hash character.
1264This option may be given more than once.
1265
1266@item --keep-global-symbols=@var{filename}
1267Apply @samp{--keep-global-symbol} option to each symbol listed in the
1268file @var{filename}. @var{filename} is simply a flat file, with one
1269symbol name per line. Line comments may be introduced by the hash
1270character. This option may be given more than once.
1271
1272@item --localize-symbols=@var{filename}
1273Apply @samp{--localize-symbol} option to each symbol listed in the file
1274@var{filename}. @var{filename} is simply a flat file, with one symbol
1275name per line. Line comments may be introduced by the hash character.
1276This option may be given more than once.
1277
1278@item --weaken-symbols=@var{filename}
1279Apply @samp{--weaken-symbol} option to each symbol listed in the file
1280@var{filename}. @var{filename} is simply a flat file, with one symbol
1281name per line. Line comments may be introduced by the hash character.
1282This option may be given more than once.
1283
252b5132
RH
1284@item -V
1285@itemx --version
1286Show the version number of @code{objcopy}.
1287
1288@item -v
1289@itemx --verbose
1290Verbose output: list all object files modified. In the case of
1291archives, @samp{objcopy -V} lists all members of the archive.
1292
1293@item --help
1294Show a summary of the options to @code{objcopy}.
1295@end table
1296
0285c67d
NC
1297@c man end
1298
1299@ignore
1300@c man begin SEEALSO objcopy
1301ld(1), objdump(1), and the Info entries for @file{binutils}.
1302@c man end
1303@end ignore
1304
252b5132
RH
1305@node objdump
1306@chapter objdump
1307
1308@cindex object file information
1309@kindex objdump
1310
0285c67d
NC
1311@c man title objdump display information from object files.
1312
252b5132 1313@smallexample
0285c67d 1314@c man begin SYNOPSIS objdump
252b5132 1315objdump [ -a | --archive-headers ]
1dada9c5 1316 [ -b @var{bfdname} | --target=@var{bfdname} ]
28c309a2 1317 [ -C | --demangle[=@var{style}] ]
1dada9c5
NC
1318 [ -d | --disassemble ]
1319 [ -D | --disassemble-all ]
1320 [ -z | --disassemble-zeroes ]
252b5132
RH
1321 [ -EB | -EL | --endian=@{big | little @} ]
1322 [ -f | --file-headers ]
f1563258 1323 [ --file-start-context ]
1dada9c5
NC
1324 [ -g | --debugging ]
1325 [ -h | --section-headers | --headers ]
1326 [ -i | --info ]
252b5132 1327 [ -j @var{section} | --section=@var{section} ]
1dada9c5
NC
1328 [ -l | --line-numbers ]
1329 [ -S | --source ]
252b5132 1330 [ -m @var{machine} | --architecture=@var{machine} ]
dd92f639 1331 [ -M @var{options} | --disassembler-options=@var{options}]
252b5132 1332 [ -p | --private-headers ]
1dada9c5
NC
1333 [ -r | --reloc ]
1334 [ -R | --dynamic-reloc ]
1335 [ -s | --full-contents ]
1336 [ -G | --stabs ]
1337 [ -t | --syms ]
1338 [ -T | --dynamic-syms ]
1339 [ -x | --all-headers ]
1340 [ -w | --wide ]
1341 [ --start-address=@var{address} ]
252b5132 1342 [ --stop-address=@var{address} ]
1dada9c5
NC
1343 [ --prefix-addresses]
1344 [ --[no-]show-raw-insn ]
252b5132 1345 [ --adjust-vma=@var{offset} ]
1dada9c5
NC
1346 [ -V | --version ]
1347 [ -H | --help ]
252b5132 1348 @var{objfile}@dots{}
0285c67d 1349@c man end
252b5132
RH
1350@end smallexample
1351
0285c67d
NC
1352@c man begin DESCRIPTION objdump
1353
252b5132
RH
1354@code{objdump} displays information about one or more object files.
1355The options control what particular information to display. This
1356information is mostly useful to programmers who are working on the
1357compilation tools, as opposed to programmers who just want their
1358program to compile and work.
1359
1360@var{objfile}@dots{} are the object files to be examined. When you
1361specify archives, @code{objdump} shows information on each of the member
1362object files.
1363
0285c67d
NC
1364@c man end
1365
1366@c man begin OPTIONS objdump
1367
252b5132 1368The long and short forms of options, shown here as alternatives, are
1dada9c5
NC
1369equivalent. At least one option from the list
1370@samp{-a,-d,-D,-f,-g,-G,-h,-H,-p,-r,-R,-S,-t,-T,-V,-x} must be given.
252b5132
RH
1371
1372@table @code
1373@item -a
1374@itemx --archive-header
1375@cindex archive headers
1376If any of the @var{objfile} files are archives, display the archive
1377header information (in a format similar to @samp{ls -l}). Besides the
1378information you could list with @samp{ar tv}, @samp{objdump -a} shows
1379the object file format of each archive member.
1380
1381@item --adjust-vma=@var{offset}
1382@cindex section addresses in objdump
1383@cindex VMA in objdump
1384When dumping information, first add @var{offset} to all the section
1385addresses. This is useful if the section addresses do not correspond to
1386the symbol table, which can happen when putting sections at particular
1387addresses when using a format which can not represent section addresses,
1388such as a.out.
1389
1390@item -b @var{bfdname}
1391@itemx --target=@var{bfdname}
1392@cindex object code format
1393Specify that the object-code format for the object files is
1394@var{bfdname}. This option may not be necessary; @var{objdump} can
1395automatically recognize many formats.
1396
1397For example,
1398@example
1399objdump -b oasys -m vax -h fu.o
1400@end example
1401@noindent
1402displays summary information from the section headers (@samp{-h}) of
1403@file{fu.o}, which is explicitly identified (@samp{-m}) as a VAX object
1404file in the format produced by Oasys compilers. You can list the
1405formats available with the @samp{-i} option.
1406@xref{Target Selection}, for more information.
1407
1408@item -C
28c309a2 1409@itemx --demangle[=@var{style}]
252b5132
RH
1410@cindex demangling in objdump
1411Decode (@dfn{demangle}) low-level symbol names into user-level names.
1412Besides removing any initial underscore prepended by the system, this
28c309a2
NC
1413makes C++ function names readable. Different compilers have different
1414mangling styles. The optional demangling style argument can be used to
1415choose an appropriate demangling style for your compiler. @xref{c++filt},
1416for more information on demangling.
252b5132 1417
1dada9c5 1418@item -G
252b5132
RH
1419@item --debugging
1420Display debugging information. This attempts to parse debugging
1421information stored in the file and print it out using a C like syntax.
1422Only certain types of debugging information have been implemented.
1423
1424@item -d
1425@itemx --disassemble
1426@cindex disassembling object code
1427@cindex machine instructions
1428Display the assembler mnemonics for the machine instructions from
1429@var{objfile}. This option only disassembles those sections which are
1430expected to contain instructions.
1431
1432@item -D
1433@itemx --disassemble-all
1434Like @samp{-d}, but disassemble the contents of all sections, not just
1435those expected to contain instructions.
1436
1437@item --prefix-addresses
1438When disassembling, print the complete address on each line. This is
1439the older disassembly format.
1440
1441@item --disassemble-zeroes
1442Normally the disassembly output will skip blocks of zeroes. This
1443option directs the disassembler to disassemble those blocks, just like
1444any other data.
1445
1446@item -EB
1447@itemx -EL
1448@itemx --endian=@{big|little@}
1449@cindex endianness
1450@cindex disassembly endianness
1451Specify the endianness of the object files. This only affects
1452disassembly. This can be useful when disassembling a file format which
1453does not describe endianness information, such as S-records.
1454
1455@item -f
1456@itemx --file-header
1457@cindex object file header
1458Display summary information from the overall header of
1459each of the @var{objfile} files.
1460
f1563258
TW
1461@item --file-start-context
1462@cindex source code context
1463Specify that when displaying interlisted source code/disassembly
1464(assumes '-S') from a file that has not yet been displayed, extend the
1465context to the start of the file.
1466
252b5132
RH
1467@item -h
1468@itemx --section-header
1469@itemx --header
1470@cindex section headers
1471Display summary information from the section headers of the
1472object file.
1473
1474File segments may be relocated to nonstandard addresses, for example by
1475using the @samp{-Ttext}, @samp{-Tdata}, or @samp{-Tbss} options to
1476@code{ld}. However, some object file formats, such as a.out, do not
1477store the starting address of the file segments. In those situations,
1478although @code{ld} relocates the sections correctly, using @samp{objdump
1479-h} to list the file section headers cannot show the correct addresses.
1480Instead, it shows the usual addresses, which are implicit for the
1481target.
1482
1483@item --help
1484Print a summary of the options to @code{objdump} and exit.
1485
1486@item -i
1487@itemx --info
1488@cindex architectures available
1489@cindex object formats available
1490Display a list showing all architectures and object formats available
1491for specification with @samp{-b} or @samp{-m}.
1492
1493@item -j @var{name}
1494@itemx --section=@var{name}
1495@cindex section information
1496Display information only for section @var{name}.
1497
1498@item -l
1499@itemx --line-numbers
1500@cindex source filenames for object files
1501Label the display (using debugging information) with the filename and
1502source line numbers corresponding to the object code or relocs shown.
1503Only useful with @samp{-d}, @samp{-D}, or @samp{-r}.
1504
1505@item -m @var{machine}
1506@itemx --architecture=@var{machine}
1507@cindex architecture
1508@cindex disassembly architecture
1509Specify the architecture to use when disassembling object files. This
1510can be useful when disassembling object files which do not describe
1511architecture information, such as S-records. You can list the available
1512architectures with the @samp{-i} option.
1513
dd92f639
NC
1514@item -M @var{options}
1515@itemx --disassembler-options=@var{options}
1516Pass target specific information to the disassembler. Only supported on
1517some targets.
1518
1519If the target is an ARM architecture then this switch can be used to
1520select which register name set is used during disassembler. Specifying
58efb6c0
NC
1521@samp{-M reg-name-std} (the default) will select the register names as
1522used in ARM's instruction set documentation, but with register 13 called
1523'sp', register 14 called 'lr' and register 15 called 'pc'. Specifying
1524@samp{-M reg-names-apcs} will select the name set used by the ARM
1525Procedure Call Standard, whilst specifying @samp{-M reg-names-raw} will
1526just use @samp{r} followed by the register number.
1527
1528There are also two variants on the APCS register naming scheme enabled
0fff8110 1529by @samp{-M reg-names-atpcs} and @samp{-M reg-names-special-atpcs} which
58efb6c0
NC
1530use the ARM/Thumb Procedure Call Standard naming conventions. (Eiuther
1531with the normal register name sor the special register names).
dd92f639 1532
8f915f68
NC
1533This option can also be used for ARM architectures to force the
1534disassembler to interpret all instructions as THUMB instructions by
1535using the switch @samp{--disassembler-options=force-thumb}. This can be
1536useful when attempting to disassemble thumb code produced by other
1537compilers.
1538
252b5132
RH
1539@item -p
1540@itemx --private-headers
1541Print information that is specific to the object file format. The exact
1542information printed depends upon the object file format. For some
1543object file formats, no additional information is printed.
1544
1545@item -r
1546@itemx --reloc
1547@cindex relocation entries, in object file
1548Print the relocation entries of the file. If used with @samp{-d} or
1549@samp{-D}, the relocations are printed interspersed with the
1550disassembly.
1551
1552@item -R
1553@itemx --dynamic-reloc
1554@cindex dynamic relocation entries, in object file
1555Print the dynamic relocation entries of the file. This is only
1556meaningful for dynamic objects, such as certain types of shared
1557libraries.
1558
1559@item -s
1560@itemx --full-contents
1561@cindex sections, full contents
1562@cindex object file sections
1563Display the full contents of any sections requested.
1564
1565@item -S
1566@itemx --source
1567@cindex source disassembly
1568@cindex disassembly, with source
1569Display source code intermixed with disassembly, if possible. Implies
1570@samp{-d}.
1571
1572@item --show-raw-insn
1573When disassembling instructions, print the instruction in hex as well as
1574in symbolic form. This is the default except when
1575@code{--prefix-addresses} is used.
1576
1577@item --no-show-raw-insn
1578When disassembling instructions, do not print the instruction bytes.
1579This is the default when @code{--prefix-addresses} is used.
1580
1dada9c5 1581@item -G
252b5132
RH
1582@item --stabs
1583@cindex stab
1584@cindex .stab
1585@cindex debug symbols
1586@cindex ELF object file format
1587Display the full contents of any sections requested. Display the
1588contents of the .stab and .stab.index and .stab.excl sections from an
1589ELF file. This is only useful on systems (such as Solaris 2.0) in which
1590@code{.stab} debugging symbol-table entries are carried in an ELF
1591section. In most other file formats, debugging symbol-table entries are
1592interleaved with linkage symbols, and are visible in the @samp{--syms}
0285c67d
NC
1593output.
1594@ifclear man
1595For more information on stabs symbols, see @ref{Top,Stabs,Stabs
252b5132 1596Overview,stabs.info, The ``stabs'' debug format}.
0285c67d 1597@end ifclear
252b5132
RH
1598
1599@item --start-address=@var{address}
1600@cindex start-address
1601Start displaying data at the specified address. This affects the output
1602of the @code{-d}, @code{-r} and @code{-s} options.
1603
1604@item --stop-address=@var{address}
1605@cindex stop-address
1606Stop displaying data at the specified address. This affects the output
1607of the @code{-d}, @code{-r} and @code{-s} options.
1608
1609@item -t
1610@itemx --syms
1611@cindex symbol table entries, printing
1612Print the symbol table entries of the file.
1613This is similar to the information provided by the @samp{nm} program.
1614
1615@item -T
1616@itemx --dynamic-syms
1617@cindex dynamic symbol table entries, printing
1618Print the dynamic symbol table entries of the file. This is only
1619meaningful for dynamic objects, such as certain types of shared
1620libraries. This is similar to the information provided by the @samp{nm}
1621program when given the @samp{-D} (@samp{--dynamic}) option.
1622
1623@item --version
1624Print the version number of @code{objdump} and exit.
1625
1626@item -x
1627@itemx --all-header
1628@cindex all header information, object file
1629@cindex header information, all
1630Display all available header information, including the symbol table and
1631relocation entries. Using @samp{-x} is equivalent to specifying all of
1632@samp{-a -f -h -r -t}.
1633
1634@item -w
1635@itemx --wide
1636@cindex wide output, printing
1637Format some lines for output devices that have more than 80 columns.
1638@end table
1639
0285c67d
NC
1640@c man end
1641
1642@ignore
1643@c man begin SEEALSO objdump
1644nm(1), readelf(1), and the Info entries for @file{binutils}.
1645@c man end
1646@end ignore
1647
252b5132
RH
1648@node ranlib
1649@chapter ranlib
1650
1651@kindex ranlib
1652@cindex archive contents
1653@cindex symbol index
1654
0285c67d
NC
1655@c man title ranlib generate index to archive.
1656
252b5132 1657@smallexample
0285c67d 1658@c man begin SYNOPSIS ranlib
252b5132 1659ranlib [-vV] @var{archive}
0285c67d 1660@c man end
252b5132
RH
1661@end smallexample
1662
0285c67d
NC
1663@c man begin DESCRIPTION ranlib
1664
252b5132
RH
1665@code{ranlib} generates an index to the contents of an archive and
1666stores it in the archive. The index lists each symbol defined by a
1667member of an archive that is a relocatable object file.
1668
1669You may use @samp{nm -s} or @samp{nm --print-armap} to list this index.
1670
1671An archive with such an index speeds up linking to the library and
1672allows routines in the library to call each other without regard to
1673their placement in the archive.
1674
1675The @sc{gnu} @code{ranlib} program is another form of @sc{gnu} @code{ar}; running
1676@code{ranlib} is completely equivalent to executing @samp{ar -s}.
1677@xref{ar}.
1678
0285c67d
NC
1679@c man end
1680
1681@c man begin OPTIONS ranlib
1682
252b5132
RH
1683@table @code
1684@item -v
1685@itemx -V
f20a759a 1686@itemx --version
252b5132
RH
1687Show the version number of @code{ranlib}.
1688@end table
1689
0285c67d
NC
1690@c man end
1691
1692@ignore
1693@c man begin SEEALSO ranlib
1694ar(1), nm(1), and the Info entries for @file{binutils}.
1695@c man end
1696@end ignore
1697
252b5132
RH
1698@node size
1699@chapter size
1700
1701@kindex size
1702@cindex section sizes
1703
0285c67d
NC
1704@c man title size list section sizes and total size.
1705
252b5132 1706@smallexample
0285c67d 1707@c man begin SYNOPSIS size
252b5132
RH
1708size [ -A | -B | --format=@var{compatibility} ]
1709 [ --help ] [ -d | -o | -x | --radix=@var{number} ]
1710 [ --target=@var{bfdname} ] [ -V | --version ]
1711 [ @var{objfile}@dots{} ]
0285c67d 1712@c man end
252b5132
RH
1713@end smallexample
1714
0285c67d
NC
1715@c man begin DESCRIPTION size
1716
252b5132
RH
1717The @sc{gnu} @code{size} utility lists the section sizes---and the total
1718size---for each of the object or archive files @var{objfile} in its
1719argument list. By default, one line of output is generated for each
1720object file or each module in an archive.
1721
1722@var{objfile}@dots{} are the object files to be examined.
1723If none are specified, the file @code{a.out} will be used.
1724
0285c67d
NC
1725@c man end
1726
1727@c man begin OPTIONS size
1728
252b5132
RH
1729The command line options have the following meanings:
1730
1731@table @code
1732@item -A
1733@itemx -B
1734@itemx --format=@var{compatibility}
1735@cindex @code{size} display format
1736Using one of these options, you can choose whether the output from @sc{gnu}
1737@code{size} resembles output from System V @code{size} (using @samp{-A},
1738or @samp{--format=sysv}), or Berkeley @code{size} (using @samp{-B}, or
1739@samp{--format=berkeley}). The default is the one-line format similar to
1740Berkeley's.
1741@c Bonus for doc-source readers: you can also say --format=strange (or
1742@c anything else that starts with 's') for sysv, and --format=boring (or
1743@c anything else that starts with 'b') for Berkeley.
1744
1745Here is an example of the Berkeley (default) format of output from
1746@code{size}:
1747@smallexample
f20a759a 1748$ size --format=Berkeley ranlib size
252b5132
RH
1749text data bss dec hex filename
1750294880 81920 11592 388392 5ed28 ranlib
1751294880 81920 11888 388688 5ee50 size
1752@end smallexample
1753
1754@noindent
1755This is the same data, but displayed closer to System V conventions:
1756
1757@smallexample
f20a759a 1758$ size --format=SysV ranlib size
252b5132
RH
1759ranlib :
1760section size addr
1761.text 294880 8192
1762.data 81920 303104
1763.bss 11592 385024
1764Total 388392
1765
1766
1767size :
1768section size addr
1769.text 294880 8192
1770.data 81920 303104
1771.bss 11888 385024
1772Total 388688
1773@end smallexample
1774
1775@item --help
1776Show a summary of acceptable arguments and options.
1777
1778@item -d
1779@itemx -o
1780@itemx -x
1781@itemx --radix=@var{number}
1782@cindex @code{size} number format
1783@cindex radix for section sizes
1784Using one of these options, you can control whether the size of each
1785section is given in decimal (@samp{-d}, or @samp{--radix=10}); octal
1786(@samp{-o}, or @samp{--radix=8}); or hexadecimal (@samp{-x}, or
1787@samp{--radix=16}). In @samp{--radix=@var{number}}, only the three
1788values (8, 10, 16) are supported. The total size is always given in two
1789radices; decimal and hexadecimal for @samp{-d} or @samp{-x} output, or
1790octal and hexadecimal if you're using @samp{-o}.
1791
1792@item --target=@var{bfdname}
1793@cindex object code format
1794Specify that the object-code format for @var{objfile} is
1795@var{bfdname}. This option may not be necessary; @code{size} can
1796automatically recognize many formats.
1797@xref{Target Selection}, for more information.
1798
1799@item -V
1800@itemx --version
1801Display the version number of @code{size}.
1802@end table
1803
0285c67d
NC
1804@c man end
1805
1806@ignore
1807@c man begin SEEALSO size
1808ar(1), objdump(1), readelf(1), and the Info entries for @file{binutils}.
1809@c man end
1810@end ignore
1811
252b5132
RH
1812@node strings
1813@chapter strings
1814@kindex strings
1815@cindex listings strings
1816@cindex printing strings
1817@cindex strings, printing
1818
0285c67d
NC
1819@c man title strings print the strings of printable characters in files.
1820
252b5132 1821@smallexample
0285c67d 1822@c man begin SYNOPSIS strings
252b5132
RH
1823strings [-afov] [-@var{min-len}] [-n @var{min-len}] [-t @var{radix}] [-]
1824 [--all] [--print-file-name] [--bytes=@var{min-len}]
1825 [--radix=@var{radix}] [--target=@var{bfdname}]
1826 [--help] [--version] @var{file}@dots{}
0285c67d 1827@c man end
252b5132
RH
1828@end smallexample
1829
0285c67d
NC
1830@c man begin DESCRIPTION strings
1831
252b5132
RH
1832For each @var{file} given, @sc{gnu} @code{strings} prints the printable
1833character sequences that are at least 4 characters long (or the number
1834given with the options below) and are followed by an unprintable
1835character. By default, it only prints the strings from the initialized
1836and loaded sections of object files; for other types of files, it prints
1837the strings from the whole file.
1838
1839@code{strings} is mainly useful for determining the contents of non-text
1840files.
1841
0285c67d
NC
1842@c man end
1843
1844@c man begin OPTIONS strings
1845
252b5132
RH
1846@table @code
1847@item -a
1848@itemx --all
1849@itemx -
1850Do not scan only the initialized and loaded sections of object files;
1851scan the whole files.
1852
1853@item -f
1854@itemx --print-file-name
1855Print the name of the file before each string.
1856
1857@item --help
1858Print a summary of the program usage on the standard output and exit.
1859
1860@item -@var{min-len}
1861@itemx -n @var{min-len}
1862@itemx --bytes=@var{min-len}
1863Print sequences of characters that are at least @var{min-len} characters
1864long, instead of the default 4.
1865
1866@item -o
1867Like @samp{-t o}. Some other versions of @code{strings} have @samp{-o}
1868act like @samp{-t d} instead. Since we can not be compatible with both
1869ways, we simply chose one.
1870
1871@item -t @var{radix}
1872@itemx --radix=@var{radix}
1873Print the offset within the file before each string. The single
1874character argument specifies the radix of the offset---@samp{o} for
1875octal, @samp{x} for hexadecimal, or @samp{d} for decimal.
1876
1877@item --target=@var{bfdname}
1878@cindex object code format
1879Specify an object code format other than your system's default format.
1880@xref{Target Selection}, for more information.
1881
1882@item -v
1883@itemx --version
1884Print the program version number on the standard output and exit.
1885@end table
1886
0285c67d
NC
1887@c man end
1888
1889@ignore
1890@c man begin SEEALSO strings
1891ar(1), nm(1), objdump(1), ranlib(1), readelf(1)
1892and the Info entries for @file{binutils}.
1893@c man end
1894@end ignore
1895
252b5132
RH
1896@node strip
1897@chapter strip
1898
1899@kindex strip
1900@cindex removing symbols
1901@cindex discarding symbols
1902@cindex symbols, discarding
1903
0285c67d
NC
1904@c man title strip Discard symbols from object files.
1905
252b5132 1906@smallexample
0285c67d 1907@c man begin SYNOPSIS strip
252b5132
RH
1908strip [ -F @var{bfdname} | --target=@var{bfdname} ]
1909 [ -I @var{bfdname} | --input-target=@var{bfdname} ]
1910 [ -O @var{bfdname} | --output-target=@var{bfdname} ]
1911 [ -s | --strip-all ] [ -S | -g | --strip-debug ]
1912 [ -K @var{symbolname} | --keep-symbol=@var{symbolname} ]
1913 [ -N @var{symbolname} | --strip-symbol=@var{symbolname} ]
1914 [ -x | --discard-all ] [ -X | --discard-locals ]
1915 [ -R @var{sectionname} | --remove-section=@var{sectionname} ]
1916 [ -o @var{file} ] [ -p | --preserve-dates ]
1917 [ -v | --verbose ] [ -V | --version ] [ --help ]
1918 @var{objfile}@dots{}
0285c67d 1919@c man end
252b5132
RH
1920@end smallexample
1921
0285c67d
NC
1922@c man begin DESCRIPTION strip
1923
252b5132
RH
1924@sc{gnu} @code{strip} discards all symbols from object files
1925@var{objfile}. The list of object files may include archives.
1926At least one object file must be given.
1927
1928@code{strip} modifies the files named in its argument,
1929rather than writing modified copies under different names.
1930
0285c67d
NC
1931@c man end
1932
1933@c man begin OPTIONS strip
1934
252b5132
RH
1935@table @code
1936@item -F @var{bfdname}
1937@itemx --target=@var{bfdname}
1938Treat the original @var{objfile} as a file with the object
1939code format @var{bfdname}, and rewrite it in the same format.
1940@xref{Target Selection}, for more information.
1941
1942@item --help
1943Show a summary of the options to @code{strip} and exit.
1944
1945@item -I @var{bfdname}
1946@itemx --input-target=@var{bfdname}
1947Treat the original @var{objfile} as a file with the object
1948code format @var{bfdname}.
1949@xref{Target Selection}, for more information.
1950
1951@item -O @var{bfdname}
1952@itemx --output-target=@var{bfdname}
1953Replace @var{objfile} with a file in the output format @var{bfdname}.
1954@xref{Target Selection}, for more information.
1955
1956@item -R @var{sectionname}
1957@itemx --remove-section=@var{sectionname}
1958Remove any section named @var{sectionname} from the output file. This
1959option may be given more than once. Note that using this option
1960inappropriately may make the output file unusable.
1961
1962@item -s
1963@itemx --strip-all
1964Remove all symbols.
1965
1966@item -g
1967@itemx -S
1968@itemx --strip-debug
1969Remove debugging symbols only.
1970
1971@item --strip-unneeded
1972Remove all symbols that are not needed for relocation processing.
1973
1974@item -K @var{symbolname}
1975@itemx --keep-symbol=@var{symbolname}
1976Keep only symbol @var{symbolname} from the source file. This option may
1977be given more than once.
1978
1979@item -N @var{symbolname}
1980@itemx --strip-symbol=@var{symbolname}
1981Remove symbol @var{symbolname} from the source file. This option may be
1982given more than once, and may be combined with strip options other than
1983@code{-K}.
1984
1985@item -o @var{file}
1986Put the stripped output in @var{file}, rather than replacing the
1987existing file. When this argument is used, only one @var{objfile}
1988argument may be specified.
1989
1990@item -p
1991@itemx --preserve-dates
1992Preserve the access and modification dates of the file.
1993
1994@item -x
1995@itemx --discard-all
1996Remove non-global symbols.
1997
1998@item -X
1999@itemx --discard-locals
2000Remove compiler-generated local symbols.
2001(These usually start with @samp{L} or @samp{.}.)
2002
2003@item -V
2004@itemx --version
2005Show the version number for @code{strip}.
2006
2007@item -v
2008@itemx --verbose
2009Verbose output: list all object files modified. In the case of
2010archives, @samp{strip -v} lists all members of the archive.
2011@end table
2012
0285c67d
NC
2013@c man end
2014
2015@ignore
2016@c man begin SEEALSO strip
2017the Info entries for @file{binutils}.
2018@c man end
2019@end ignore
2020
9d51cc66 2021@node c++filt, addr2line, strip, Top
252b5132
RH
2022@chapter c++filt
2023
2024@kindex c++filt
2025@cindex demangling C++ symbols
2026
0285c67d
NC
2027@c man title cxxfilt Demangle C++ and Java symbols.
2028
252b5132 2029@smallexample
0285c67d 2030@c man begin SYNOPSIS cxxfilt
252b5132
RH
2031c++filt [ -_ | --strip-underscores ]
2032 [ -j | --java ]
2033 [ -n | --no-strip-underscores ]
2034 [ -s @var{format} | --format=@var{format} ]
2035 [ --help ] [ --version ] [ @var{symbol}@dots{} ]
0285c67d 2036@c man end
252b5132
RH
2037@end smallexample
2038
0285c67d
NC
2039@c man begin DESCRIPTION cxxfilt
2040
9d51cc66 2041@kindex cxxfilt
252b5132
RH
2042The C++ and Java languages provides function overloading, which means
2043that you can write many functions with the same name (providing each
2044takes parameters of different types). All C++ and Java function names
2045are encoded into a low-level assembly label (this process is known as
9d51cc66
ILT
2046@dfn{mangling}). The @code{c++filt}
2047@footnote{MS-DOS does not allow @kbd{+} characters in file names, so on
2048MS-DOS this program is named @code{cxxfilt}.}
2049program does the inverse mapping: it decodes (@dfn{demangles}) low-level
2050names into user-level names so that the linker can keep these overloaded
2051functions from clashing.
252b5132
RH
2052
2053Every alphanumeric word (consisting of letters, digits, underscores,
2054dollars, or periods) seen in the input is a potential label. If the
2055label decodes into a C++ name, the C++ name replaces the low-level
2056name in the output.
2057
2058You can use @code{c++filt} to decipher individual symbols:
2059
2060@example
2061c++filt @var{symbol}
2062@end example
2063
2064If no @var{symbol} arguments are given, @code{c++filt} reads symbol
2065names from the standard input and writes the demangled names to the
2066standard output. All results are printed on the standard output.
2067
0285c67d
NC
2068@c man end
2069
2070@c man begin OPTIONS cxxfilt
2071
252b5132
RH
2072@table @code
2073@item -_
2074@itemx --strip-underscores
2075On some systems, both the C and C++ compilers put an underscore in front
2076of every name. For example, the C name @code{foo} gets the low-level
2077name @code{_foo}. This option removes the initial underscore. Whether
2078@code{c++filt} removes the underscore by default is target dependent.
2079
2080@item -j
2081@itemx --java
2082Prints demangled names using Java syntax. The default is to use C++
2083syntax.
2084
2085@item -n
2086@itemx --no-strip-underscores
2087Do not remove the initial underscore.
2088
2089@item -s @var{format}
2090@itemx --format=@var{format}
2091@sc{gnu} @code{nm} can decode three different methods of mangling, used by
2092different C++ compilers. The argument to this option selects which
2093method it uses:
2094
2095@table @code
2096@item gnu
2097the one used by the @sc{gnu} compiler (the default method)
2098@item lucid
2099the one used by the Lucid compiler
2100@item arm
2101the one specified by the C++ Annotated Reference Manual
2102@item hp
2103the one used by the HP compiler
2104@item edg
2105the one used by the EDG compiler
28c309a2
NC
2106@item gnu-new-abi
2107the one used by the @sc{gnu} compiler with the new ABI.
252b5132
RH
2108@end table
2109
2110@item --help
2111Print a summary of the options to @code{c++filt} and exit.
2112
2113@item --version
2114Print the version number of @code{c++filt} and exit.
2115@end table
2116
0285c67d
NC
2117@c man end
2118
2119@ignore
2120@c man begin SEEALSO cxxfilt
2121the Info entries for @file{binutils}.
2122@c man end
2123@end ignore
2124
252b5132
RH
2125@quotation
2126@emph{Warning:} @code{c++filt} is a new utility, and the details of its
2127user interface are subject to change in future releases. In particular,
2128a command-line option may be required in the the future to decode a name
2129passed as an argument on the command line; in other words,
2130
2131@example
2132c++filt @var{symbol}
2133@end example
2134
2135@noindent
2136may in a future release become
2137
2138@example
2139c++filt @var{option} @var{symbol}
2140@end example
2141@end quotation
2142
2143@node addr2line
2144@chapter addr2line
2145
2146@kindex addr2line
2147@cindex address to file name and line number
2148
0285c67d
NC
2149@c man title addr2line convert addresses into file names and line numbers.
2150
252b5132 2151@smallexample
0285c67d 2152@c man begin SYNOPSIS addr2line
252b5132 2153addr2line [ -b @var{bfdname} | --target=@var{bfdname} ]
28c309a2 2154 [ -C | --demangle[=@var{style} ]
252b5132
RH
2155 [ -e @var{filename} | --exe=@var{filename} ]
2156 [ -f | --functions ] [ -s | --basename ]
2157 [ -H | --help ] [ -V | --version ]
2158 [ addr addr ... ]
0285c67d 2159@c man end
252b5132
RH
2160@end smallexample
2161
0285c67d
NC
2162@c man begin DESCRIPTION addr2line
2163
252b5132
RH
2164@code{addr2line} translates program addresses into file names and line
2165numbers. Given an address and an executable, it uses the debugging
2166information in the executable to figure out which file name and line
2167number are associated with a given address.
2168
2169The executable to use is specified with the @code{-e} option. The
f20a759a 2170default is the file @file{a.out}.
252b5132
RH
2171
2172@code{addr2line} has two modes of operation.
2173
2174In the first, hexadecimal addresses are specified on the command line,
2175and @code{addr2line} displays the file name and line number for each
2176address.
2177
2178In the second, @code{addr2line} reads hexadecimal addresses from
2179standard input, and prints the file name and line number for each
2180address on standard output. In this mode, @code{addr2line} may be used
2181in a pipe to convert dynamically chosen addresses.
2182
2183The format of the output is @samp{FILENAME:LINENO}. The file name and
2184line number for each address is printed on a separate line. If the
2185@code{-f} option is used, then each @samp{FILENAME:LINENO} line is
2186preceded by a @samp{FUNCTIONNAME} line which is the name of the function
2187containing the address.
2188
2189If the file name or function name can not be determined,
2190@code{addr2line} will print two question marks in their place. If the
2191line number can not be determined, @code{addr2line} will print 0.
2192
0285c67d
NC
2193@c man end
2194
2195@c man begin OPTIONS addr2line
2196
252b5132
RH
2197The long and short forms of options, shown here as alternatives, are
2198equivalent.
2199
2200@table @code
2201@item -b @var{bfdname}
2202@itemx --target=@var{bfdname}
2203@cindex object code format
2204Specify that the object-code format for the object files is
2205@var{bfdname}.
2206
2207@item -C
28c309a2 2208@itemx --demangle[=@var{style}]
252b5132
RH
2209@cindex demangling in objdump
2210Decode (@dfn{demangle}) low-level symbol names into user-level names.
2211Besides removing any initial underscore prepended by the system, this
28c309a2
NC
2212makes C++ function names readable. Different compilers have different
2213mangling styles. The optional demangling style argument can be used to
2214choose an appropriate demangling style for your compiler. @xref{c++filt},
2215for more information on demangling.
252b5132
RH
2216
2217@item -e @var{filename}
2218@itemx --exe=@var{filename}
2219Specify the name of the executable for which addresses should be
2220translated. The default file is @file{a.out}.
2221
2222@item -f
2223@itemx --functions
2224Display function names as well as file and line number information.
2225
2226@item -s
2227@itemx --basenames
2228Display only the base of each file name.
e107c42f 2229@end table
252b5132 2230
0285c67d
NC
2231@c man end
2232
2233@ignore
2234@c man begin SEEALSO addr2line
2235Info entries for @file{binutils}.
2236@c man end
2237@end ignore
2238
252b5132
RH
2239@node nlmconv
2240@chapter nlmconv
2241
2242@code{nlmconv} converts a relocatable object file into a NetWare
2243Loadable Module.
2244
2245@ignore
2246@code{nlmconv} currently works with @samp{i386} object
2247files in @code{coff}, @sc{elf}, or @code{a.out} format, and @sc{SPARC}
2248object files in @sc{elf}, or @code{a.out} format@footnote{
2249@code{nlmconv} should work with any @samp{i386} or @sc{sparc} object
2250format in the Binary File Descriptor library. It has only been tested
2251with the above formats.}.
2252@end ignore
2253
2254@quotation
2255@emph{Warning:} @code{nlmconv} is not always built as part of the binary
2256utilities, since it is only useful for NLM targets.
2257@end quotation
2258
0285c67d
NC
2259@c man title nlmconv converts object code into an NLM.
2260
252b5132 2261@smallexample
0285c67d 2262@c man begin SYNOPSIS nlmconv
252b5132
RH
2263nlmconv [ -I @var{bfdname} | --input-target=@var{bfdname} ]
2264 [ -O @var{bfdname} | --output-target=@var{bfdname} ]
2265 [ -T @var{headerfile} | --header-file=@var{headerfile} ]
2266 [ -d | --debug] [ -l @var{linker} | --linker=@var{linker} ]
2267 [ -h | --help ] [ -V | --version ]
2268 @var{infile} @var{outfile}
0285c67d 2269@c man end
252b5132
RH
2270@end smallexample
2271
0285c67d
NC
2272@c man begin DESCRIPTION nlmconv
2273
252b5132
RH
2274@code{nlmconv} converts the relocatable @samp{i386} object file
2275@var{infile} into the NetWare Loadable Module @var{outfile}, optionally
2276reading @var{headerfile} for NLM header information. For instructions
2277on writing the NLM command file language used in header files, see the
2278@samp{linkers} section, @samp{NLMLINK} in particular, of the @cite{NLM
2279Development and Tools Overview}, which is part of the NLM Software
2280Developer's Kit (``NLM SDK''), available from Novell, Inc.
2281@code{nlmconv} uses the @sc{gnu} Binary File Descriptor library to read
0285c67d
NC
2282@var{infile};
2283@ifclear man
2284see @ref{BFD,,BFD,ld.info,Using LD}, for more information.
2285@end ifclear
252b5132
RH
2286
2287@code{nlmconv} can perform a link step. In other words, you can list
2288more than one object file for input if you list them in the definitions
2289file (rather than simply specifying one input file on the command line).
2290In this case, @code{nlmconv} calls the linker for you.
2291
0285c67d
NC
2292@c man end
2293
2294@c man begin OPTIONS nlmconv
2295
252b5132
RH
2296@table @code
2297@item -I @var{bfdname}
2298@itemx --input-target=@var{bfdname}
2299Object format of the input file. @code{nlmconv} can usually determine
2300the format of a given file (so no default is necessary).
2301@xref{Target Selection}, for more information.
2302
2303@item -O @var{bfdname}
2304@itemx --output-target=@var{bfdname}
2305Object format of the output file. @code{nlmconv} infers the output
2306format based on the input format, e.g. for a @samp{i386} input file the
2307output format is @samp{nlm32-i386}.
2308@xref{Target Selection}, for more information.
2309
2310@item -T @var{headerfile}
2311@itemx --header-file=@var{headerfile}
2312Reads @var{headerfile} for NLM header information. For instructions on
2313writing the NLM command file language used in header files, see@ see the
2314@samp{linkers} section, of the @cite{NLM Development and Tools
2315Overview}, which is part of the NLM Software Developer's Kit, available
2316from Novell, Inc.
2317
2318@item -d
2319@itemx --debug
2320Displays (on standard error) the linker command line used by @code{nlmconv}.
2321
2322@item -l @var{linker}
2323@itemx --linker=@var{linker}
2324Use @var{linker} for any linking. @var{linker} can be an absolute or a
2325relative pathname.
2326
2327@item -h
2328@itemx --help
2329Prints a usage summary.
2330
2331@item -V
2332@itemx --version
2333Prints the version number for @code{nlmconv}.
2334@end table
2335
0285c67d
NC
2336@c man end
2337
2338@ignore
2339@c man begin SEEALSO nlmconv
2340the Info entries for @file{binutils}.
2341@c man end
2342@end ignore
2343
252b5132
RH
2344@node windres
2345@chapter windres
2346
2347@code{windres} may be used to manipulate Windows resources.
2348
2349@quotation
2350@emph{Warning:} @code{windres} is not always built as part of the binary
2351utilities, since it is only useful for Windows targets.
2352@end quotation
2353
0285c67d
NC
2354@c man title windres manipulate Windows resources.
2355
252b5132 2356@smallexample
0285c67d 2357@c man begin SYNOPSIS windres
252b5132 2358windres [options] [input-file] [output-file]
0285c67d 2359@c man end
252b5132
RH
2360@end smallexample
2361
0285c67d
NC
2362@c man begin DESCRIPTION windres
2363
252b5132
RH
2364@code{windres} reads resources from an input file and copies them into
2365an output file. Either file may be in one of three formats:
2366
2367@table @code
2368@item rc
2369A text format read by the Resource Compiler.
2370
2371@item res
2372A binary format generated by the Resource Compiler.
2373
2374@item coff
2375A COFF object or executable.
2376@end table
2377
2378The exact description of these different formats is available in
2379documentation from Microsoft.
2380
2381When @code{windres} converts from the @code{rc} format to the @code{res}
2382format, it is acting like the Windows Resource Compiler. When
2383@code{windres} converts from the @code{res} format to the @code{coff}
2384format, it is acting like the Windows @code{CVTRES} program.
2385
2386When @code{windres} generates an @code{rc} file, the output is similar
2387but not identical to the format expected for the input. When an input
2388@code{rc} file refers to an external filename, an output @code{rc} file
2389will instead include the file contents.
2390
2391If the input or output format is not specified, @code{windres} will
2392guess based on the file name, or, for the input file, the file contents.
2393A file with an extension of @file{.rc} will be treated as an @code{rc}
2394file, a file with an extension of @file{.res} will be treated as a
2395@code{res} file, and a file with an extension of @file{.o} or
2396@file{.exe} will be treated as a @code{coff} file.
2397
2398If no output file is specified, @code{windres} will print the resources
2399in @code{rc} format to standard output.
2400
2401The normal use is for you to write an @code{rc} file, use @code{windres}
2402to convert it to a COFF object file, and then link the COFF file into
2403your application. This will make the resources described in the
2404@code{rc} file available to Windows.
2405
0285c67d
NC
2406@c man end
2407
2408@c man begin OPTIONS windres
2409
252b5132
RH
2410@table @code
2411@item -i @var{filename}
2412@itemx --input @var{filename}
2413The name of the input file. If this option is not used, then
2414@code{windres} will use the first non-option argument as the input file
2415name. If there are no non-option arguments, then @code{windres} will
2416read from standard input. @code{windres} can not read a COFF file from
2417standard input.
2418
2419@item -o @var{filename}
2420@itemx --output @var{filename}
2421The name of the output file. If this option is not used, then
2422@code{windres} will use the first non-option argument, after any used
2423for the input file name, as the output file name. If there is no
2424non-option argument, then @code{windres} will write to standard output.
2425@code{windres} can not write a COFF file to standard output.
2426
2427@item -I @var{format}
2428@itemx --input-format @var{format}
2429The input format to read. @var{format} may be @samp{res}, @samp{rc}, or
2430@samp{coff}. If no input format is specified, @code{windres} will
2431guess, as described above.
2432
2433@item -O @var{format}
2434@itemx --output-format @var{format}
2435The output format to generate. @var{format} may be @samp{res},
2436@samp{rc}, or @samp{coff}. If no output format is specified,
2437@code{windres} will guess, as described above.
2438
2439@item -F @var{target}
2440@itemx --target @var{target}
2441Specify the BFD format to use for a COFF file as input or output. This
2442is a BFD target name; you can use the @code{--help} option to see a list
2443of supported targets. Normally @code{windres} will use the default
2444format, which is the first one listed by the @code{--help} option.
2445@ref{Target Selection}.
2446
2447@item --preprocessor @var{program}
2448When @code{windres} reads an @code{rc} file, it runs it through the C
2449preprocessor first. This option may be used to specify the preprocessor
2450to use, including any leading arguments. The default preprocessor
2451argument is @code{gcc -E -xc-header -DRC_INVOKED}.
2452
2453@item --include-dir @var{directory}
2454Specify an include directory to use when reading an @code{rc} file.
2455@code{windres} will pass this to the preprocessor as an @code{-I}
2456option. @code{windres} will also search this directory when looking for
2457files named in the @code{rc} file.
2458
751d21b5 2459@item -D @var{target}
ad0481cd 2460@itemx --define @var{sym}[=@var{val}]
252b5132
RH
2461Specify a @code{-D} option to pass to the preprocessor when reading an
2462@code{rc} file.
2463
751d21b5
DD
2464@item -v
2465Enable verbose mode. This tells you what the preprocessor is if you
2466didn't specify one.
2467
252b5132
RH
2468@item --language @var{val}
2469Specify the default language to use when reading an @code{rc} file.
2470@var{val} should be a hexadecimal language code. The low eight bits are
2471the language, and the high eight bits are the sublanguage.
2472
5a298d2d
NC
2473@item --use-temp-file
2474Use a temporary file to instead of using popen to read the output of
2475the preprocessor. Use this option if the popen implementation is buggy
2476on the host (eg., certain non-English language versions of Windows 95 and
2477Windows 98 are known to have buggy popen where the output will instead
2478go the console).
2479
2480@item --no-use-temp-file
2481Use popen, not a temporary file, to read the output of the preprocessor.
2482This is the default behaviour.
2483
252b5132
RH
2484@item --help
2485Prints a usage summary.
2486
2487@item --version
2488Prints the version number for @code{windres}.
2489
2490@item --yydebug
2491If @code{windres} is compiled with @code{YYDEBUG} defined as @code{1},
2492this will turn on parser debugging.
2493@end table
2494
0285c67d
NC
2495@c man end
2496
2497@ignore
2498@c man begin SEEALSO windres
2499the Info entries for @file{binutils}.
2500@c man end
2501@end ignore
252b5132
RH
2502
2503@node dlltool
2504@chapter Create files needed to build and use DLLs
2505@cindex DLL
2506@kindex dlltool
2507
2508@code{dlltool} may be used to create the files needed to build and use
2509dynamic link libraries (DLLs).
2510
2511@quotation
2512@emph{Warning:} @code{dlltool} is not always built as part of the binary
2513utilities, since it is only useful for those targets which support DLLs.
2514@end quotation
2515
0285c67d
NC
2516@c man title dlltool Create files needed to build and use DLLs.
2517
252b5132 2518@smallexample
0285c67d 2519@c man begin SYNOPSIS dlltool
252b5132
RH
2520dlltool [-d|--input-def @var{def-file-name}]
2521 [-b|--base-file @var{base-file-name}]
2522 [-e|--output-exp @var{exports-file-name}]
2523 [-z|--output-def @var{def-file-name}]
2524 [-l|--output-lib @var{library-file-name}]
2525 [--export-all-symbols] [--no-export-all-symbols]
2526 [--exclude-symbols @var{list}]
2527 [--no-default-excludes]
2528 [-S|--as @var{path-to-assembler}] [-f|--as-flags @var{options}]
2529 [-D|--dllname @var{name}] [-m|--machine @var{machine}]
2530 [-a|--add-indirect] [-U|--add-underscore] [-k|--kill-at]
2531 [-A|--add-stdcall-alias]
2532 [-x|--no-idata4] [-c|--no-idata5] [-i|--interwork]
2533 [-n|--nodelete] [-v|--verbose] [-h|--help] [-V|--version]
2534 [object-file @dots{}]
0285c67d 2535@c man end
252b5132
RH
2536@end smallexample
2537
0285c67d
NC
2538@c man begin DESCRIPTION dlltool
2539
252b5132
RH
2540@code{dlltool} reads its inputs, which can come from the @samp{-d} and
2541@samp{-b} options as well as object files specified on the command
2542line. It then processes these inputs and if the @samp{-e} option has
2543been specified it creates a exports file. If the @samp{-l} option
2544has been specified it creates a library file and if the @samp{-z} option
2545has been specified it creates a def file. Any or all of the -e, -l
2546and -z options can be present in one invocation of dlltool.
2547
2548When creating a DLL, along with the source for the DLL, it is necessary
2549to have three other files. @code{dlltool} can help with the creation of
2550these files.
2551
2552The first file is a @samp{.def} file which specifies which functions are
2553exported from the DLL, which functions the DLL imports, and so on. This
2554is a text file and can be created by hand, or @code{dlltool} can be used
2555to create it using the @samp{-z} option. In this case @code{dlltool}
2556will scan the object files specified on its command line looking for
2557those functions which have been specially marked as being exported and
2558put entries for them in the .def file it creates.
2559
2560In order to mark a function as being exported from a DLL, it needs to
2561have an @samp{-export:<name_of_function>} entry in the @samp{.drectve}
2562section of the object file. This can be done in C by using the
2563asm() operator:
2564
2565@smallexample
2566 asm (".section .drectve");
2567 asm (".ascii \"-export:my_func\"");
2568
2569 int my_func (void) @{ @dots{} @}
2570@end smallexample
2571
2572The second file needed for DLL creation is an exports file. This file
2573is linked with the object files that make up the body of the DLL and it
2574handles the interface between the DLL and the outside world. This is a
2575binary file and it can be created by giving the @samp{-e} option to
2576@code{dlltool} when it is creating or reading in a .def file.
2577
2578The third file needed for DLL creation is the library file that programs
2579will link with in order to access the functions in the DLL. This file
2580can be created by giving the @samp{-l} option to dlltool when it
2581is creating or reading in a .def file.
2582
2583@code{dlltool} builds the library file by hand, but it builds the
2584exports file by creating temporary files containing assembler statements
2585and then assembling these. The @samp{-S} command line option can be
2586used to specify the path to the assembler that dlltool will use,
2587and the @samp{-f} option can be used to pass specific flags to that
2588assembler. The @samp{-n} can be used to prevent dlltool from deleting
2589these temporary assembler files when it is done, and if @samp{-n} is
2590specified twice then this will prevent dlltool from deleting the
2591temporary object files it used to build the library.
2592
2593Here is an example of creating a DLL from a source file @samp{dll.c} and
2594also creating a program (from an object file called @samp{program.o})
2595that uses that DLL:
2596
2597@smallexample
2598 gcc -c dll.c
2599 dlltool -e exports.o -l dll.lib dll.o
2600 gcc dll.o exports.o -o dll.dll
2601 gcc program.o dll.lib -o program
2602@end smallexample
2603
0285c67d
NC
2604@c man end
2605
2606@c man begin OPTIONS dlltool
2607
252b5132
RH
2608The command line options have the following meanings:
2609
2610@table @code
2611
2612@item -d @var{filename}
2613@itemx --input-def @var{filename}
2614@cindex input .def file
2615Specifies the name of a .def file to be read in and processed.
2616
2617@item -b @var{filename}
2618@itemx --base-file @var{filename}
2619@cindex base files
2620Specifies the name of a base file to be read in and processed. The
2621contents of this file will be added to the relocation section in the
2622exports file generated by dlltool.
2623
2624@item -e @var{filename}
2625@itemx --output-exp @var{filename}
2626Specifies the name of the export file to be created by dlltool.
2627
2628@item -z @var{filename}
2629@itemx --output-def @var{filename}
2630Specifies the name of the .def file to be created by dlltool.
2631
2632@item -l @var{filename}
2633@itemx --output-lib @var{filename}
2634Specifies the name of the library file to be created by dlltool.
2635
2636@item --export-all-symbols
2637Treat all global and weak defined symbols found in the input object
2638files as symbols to be exported. There is a small list of symbols which
2639are not exported by default; see the @code{--no-default-excludes}
2640option. You may add to the list of symbols to not export by using the
2641@code{--exclude-symbols} option.
2642
2643@item --no-export-all-symbols
2644Only export symbols explicitly listed in an input .def file or in
2645@samp{.drectve} sections in the input object files. This is the default
2646behaviour. The @samp{.drectve} sections are created by @samp{dllexport}
2647attributes in the source code.
2648
2649@item --exclude-symbols @var{list}
2650Do not export the symbols in @var{list}. This is a list of symbol names
2651separated by comma or colon characters. The symbol names should not
2652contain a leading underscore. This is only meaningful when
2653@code{--export-all-symbols} is used.
2654
2655@item --no-default-excludes
2656When @code{--export-all-symbols} is used, it will by default avoid
2657exporting certain special symbols. The current list of symbols to avoid
2658exporting is @samp{DllMain@@12}, @samp{DllEntryPoint@@0},
2659@samp{impure_ptr}. You may use the @code{--no-default-excludes} option
2660to go ahead and export these special symbols. This is only meaningful
2661when @code{--export-all-symbols} is used.
2662
2663@item -S @var{path}
2664@itemx --as @var{path}
2665Specifies the path, including the filename, of the assembler to be used
2666to create the exports file.
2667
2668@item -f @var{switches}
2669@itemx --as-flags @var{switches}
2670Specifies any specific command line switches to be passed to the
2671assembler when building the exports file. This option will work even if
2672the @samp{-S} option is not used. This option only takes one argument,
2673and if it occurs more than once on the command line, then later
2674occurrences will override earlier occurrences. So if it is necessary to
2675pass multiple switches to the assembler they should be enclosed in
2676double quotes.
2677
2678@item -D @var{name}
2679@itemx --dll-name @var{name}
2680Specifies the name to be stored in the .def file as the name of the DLL
2681when the @samp{-e} option is used. If this option is not present, then
2682the filename given to the @samp{-e} option will be used as the name of
2683the DLL.
2684
2685@item -m @var{machine}
2686@itemx -machine @var{machine}
2687Specifies the type of machine for which the library file should be
2688built. @code{dlltool} has a built in default type, depending upon how
2689it was created, but this option can be used to override that. This is
2690normally only useful when creating DLLs for an ARM processor, when the
2691contents of the DLL are actually encode using THUMB instructions.
2692
2693@item -a
2694@itemx --add-indirect
2695Specifies that when @code{dlltool} is creating the exports file it
2696should add a section which allows the exported functions to be
2697referenced without using the import library. Whatever the hell that
2698means!
2699
2700@item -U
2701@itemx --add-underscore
2702Specifies that when @code{dlltool} is creating the exports file it
2703should prepend an underscore to the names of the exported functions.
2704
2705@item -k
2706@itemx --kill-at
2707Specifies that when @code{dlltool} is creating the exports file it
2708should not append the string @samp{@@ <number>}. These numbers are
2709called ordinal numbers and they represent another way of accessing the
2710function in a DLL, other than by name.
2711
2712@item -A
2713@itemx --add-stdcall-alias
2714Specifies that when @code{dlltool} is creating the exports file it
2715should add aliases for stdcall symbols without @samp{@@ <number>}
2716in addition to the symbols with @samp{@@ <number>}.
2717
2718@item -x
2719@itemx --no-idata4
2720Specifies that when @code{dlltool} is creating the exports and library
2721files it should omit the .idata4 section. This is for compatibility
2722with certain operating systems.
2723
2724@item -c
2725@itemx --no-idata5
2726Specifies that when @code{dlltool} is creating the exports and library
2727files it should omit the .idata5 section. This is for compatibility
2728with certain operating systems.
2729
2730@item -i
2731@itemx --interwork
2732Specifies that @code{dlltool} should mark the objects in the library
2733file and exports file that it produces as supporting interworking
2734between ARM and THUMB code.
2735
2736@item -n
2737@itemx --nodelete
2738Makes @code{dlltool} preserve the temporary assembler files it used to
2739create the exports file. If this option is repeated then dlltool will
2740also preserve the temporary object files it uses to create the library
2741file.
2742
2743@item -v
2744@itemx --verbose
2745Make dlltool describe what it is doing.
2746
2747@item -h
2748@itemx --help
2749Displays a list of command line options and then exits.
2750
2751@item -V
2752@itemx --version
2753Displays dlltool's version number and then exits.
2754
2755@end table
2756
0285c67d
NC
2757@c man end
2758
2759@ignore
2760@c man begin SEEALSO dlltool
2761the Info entries for @file{binutils}.
2762@c man end
2763@end ignore
2764
252b5132
RH
2765@node readelf
2766@chapter readelf
2767
2768@cindex ELF file information
2769@kindex readelf
2770
0285c67d
NC
2771@c man title readelf Displays information about ELF files.
2772
252b5132 2773@smallexample
0285c67d 2774@c man begin SYNOPSIS readelf
252b5132
RH
2775readelf [ -a | --all ]
2776 [ -h | --file-header]
2777 [ -l | --program-headers | --segments]
2778 [ -S | --section-headers | --sections]
2779 [ -e | --headers]
2780 [ -s | --syms | --symbols]
779fe533 2781 [ -n | --notes]
252b5132 2782 [ -r | --relocs]
f5e21966 2783 [ -u | --unwind]
252b5132
RH
2784 [ -d | --dynamic]
2785 [ -V | --version-info]
2786 [ -D | --use-dynamic]
2787 [ -x <number> | --hex-dump=<number>]
c47d488e 2788 [ -w[liaprf] | --debug-dump[=info,=line,=abbrev,=pubnames,=ranges,=frames]]
252b5132
RH
2789 [ --histogram]
2790 [ -v | --version]
2791 [ -H | --help]
2792 @var{elffile}@dots{}
0285c67d 2793@c man end
252b5132
RH
2794@end smallexample
2795
0285c67d
NC
2796@c man begin DESCRIPTION readelf
2797
252b5132
RH
2798@code{readelf} displays information about one or more ELF format object
2799files. The options control what particular information to display.
2800
2801@var{elffile}@dots{} are the object files to be examined. At the
2802moment, @code{readelf} does not support examining archives, nor does it
2803support examing 64 bit ELF files.
2804
0285c67d
NC
2805@c man end
2806
2807@c man begin OPTIONS readelf
2808
252b5132
RH
2809The long and short forms of options, shown here as alternatives, are
2810equivalent. At least one option besides @samp{-v} or @samp{-H} must be
2811given.
2812
2813@table @code
2814@item -a
2815@itemx --all
2816Equivalent to specifiying @samp{--file-header},
2817@samp{--program-headers}, @samp{--sections}, @samp{--symbols},
779fe533
NC
2818@samp{--relocs}, @samp{--dynamic}, @samp{--notes} and
2819@samp{--version-info}.
252b5132
RH
2820
2821@item -h
2822@itemx --file-header
2823@cindex ELF file header information
2824Displays the information contained in the ELF header at the start of the
2825file.
2826
2827@item -l
2828@itemx --program-headers
2829@itemx --segments
2830@cindex ELF program header information
2831@cindex ELF segment information
2832Displays the information contained in the file's segment headers, if it
2833has any.
2834
2835@item -S
2836@itemx --sections
2837@itemx --section-headers
2838@cindex ELF section information
2839Displays the information contained in the file's section headers, if it
2840has any.
2841
2842@item -s
2843@itemx --symbols
2844@itemx --syms
2845@cindex ELF symbol table information
2846Displays the entries in symbol table section of the file, if it has one.
2847
2848@item -e
2849@itemx --headers
2850Display all the headers in the file. Equivalent to @samp{-h -l -S}.
2851
779fe533
NC
2852@item -n
2853@itemx --notes
2854@cindex ELF core notes
2855Displays the contents of the NOTE segment, if it exists.
2856
252b5132
RH
2857@item -r
2858@itemx --relocs
2859@cindex ELF reloc information
f5e21966
NC
2860Displays the contents of the file's relocation section, if it has one.
2861
2862@item -u
2863@itemx --unwind
2864@cindex unwind information
2865Displays the contents of the file's unwind section, if it has one. Only
2866the unwind sections for IA64 ELF files are currently supported.
252b5132
RH
2867
2868@item -d
2869@itemx --dynamic
2870@cindex ELF dynamic section information
2871Displays the contents of the file's dynamic section, if it has one.
2872
2873@item -V
2874@itemx --version-info
2875@cindex ELF version sections informations
2876Displays the contents of the version sections in the file, it they
2877exist.
2878
2879@item -D
2880@itemx --use-dynamic
2881When displaying symbols, this option makes @code{readelf} use the
6dbb55b6 2882symbol table in the file's dynamic section, rather than the one in the
252b5132
RH
2883symbols section.
2884
2885@item -x <number>
2886@itemx --hex-dump=<number>
2887Displays the contents of the indicated section as a hexadecimal dump.
2888
c47d488e
DD
2889@item -w[liaprf]
2890@itemx --debug-dump[=line,=info,=abbrev,=pubnames,=ranges,=frames]
252b5132
RH
2891Displays the contents of the debug sections in the file, if any are
2892present. If one of the optional letters or words follows the switch
2893then only data found in those specific sections will be dumped.
2894
2895@item --histogram
2896Display a histogram of bucket list lengths when displaying the contents
2897of the symbol tables.
2898
2899@item -v
2900@itemx --version
2901Display the version number of readelf.
2902
2903@item -H
2904@itemx --help
2905Display the command line options understood by @code{readelf}.
2906
2907@end table
2908
0285c67d
NC
2909@c man end
2910
2911@ignore
2912@c man begin SEEALSO readelf
2913objdump(1), and the Info entries for @file{binutils}.
2914@c man end
2915@end ignore
252b5132
RH
2916
2917@node Selecting The Target System
2918@chapter Selecting the target system
2919
2920You can specify three aspects of the target system to the @sc{gnu}
2921binary file utilities, each in several ways:
2922
2923@itemize @bullet
2924@item
2925the target
2926
2927@item
2928the architecture
2929
2930@item
2931the linker emulation (which applies to the linker only)
2932@end itemize
2933
2934In the following summaries, the lists of ways to specify values are in
2935order of decreasing precedence. The ways listed first override those
2936listed later.
2937
2938The commands to list valid values only list the values for which the
2939programs you are running were configured. If they were configured with
2940@samp{--enable-targets=all}, the commands list most of the available
2941values, but a few are left out; not all targets can be configured in at
2942once because some of them can only be configured @dfn{native} (on hosts
2943with the same type as the target system).
2944
2945@menu
2946* Target Selection::
2947* Architecture Selection::
2948* Linker Emulation Selection::
2949@end menu
2950
2951@node Target Selection
2952@section Target Selection
2953
2954A @dfn{target} is an object file format. A given target may be
2955supported for multiple architectures (@pxref{Architecture Selection}).
2956A target selection may also have variations for different operating
2957systems or architectures.
2958
2959The command to list valid target values is @samp{objdump -i}
2960(the first column of output contains the relevant information).
2961
2962Some sample values are: @samp{a.out-hp300bsd}, @samp{ecoff-littlemips},
2963@samp{a.out-sunos-big}.
2964
2965You can also specify a target using a configuration triplet. This is
f20a759a
ILT
2966the same sort of name that is passed to @file{configure} to specify a
2967target. When you use a configuration triplet as an argument, it must be
2968fully canonicalized. You can see the canonical version of a triplet by
252b5132
RH
2969running the shell script @file{config.sub} which is included with the
2970sources.
2971
2972Some sample configuration triplets are: @samp{m68k-hp-bsd},
2973@samp{mips-dec-ultrix}, @samp{sparc-sun-sunos}.
2974
2975@subheading @code{objdump} Target
2976
2977Ways to specify:
2978
2979@enumerate
2980@item
2981command line option: @samp{-b} or @samp{--target}
2982
2983@item
2984environment variable @code{GNUTARGET}
2985
2986@item
2987deduced from the input file
2988@end enumerate
2989
2990@subheading @code{objcopy} and @code{strip} Input Target
2991
2992Ways to specify:
2993
2994@enumerate
2995@item
2996command line options: @samp{-I} or @samp{--input-target}, or @samp{-F} or @samp{--target}
2997
2998@item
2999environment variable @code{GNUTARGET}
3000
3001@item
3002deduced from the input file
3003@end enumerate
3004
3005@subheading @code{objcopy} and @code{strip} Output Target
3006
3007Ways to specify:
3008
3009@enumerate
3010@item
3011command line options: @samp{-O} or @samp{--output-target}, or @samp{-F} or @samp{--target}
3012
3013@item
3014the input target (see ``@code{objcopy} and @code{strip} Input Target'' above)
3015
3016@item
3017environment variable @code{GNUTARGET}
3018
3019@item
3020deduced from the input file
3021@end enumerate
3022
3023@subheading @code{nm}, @code{size}, and @code{strings} Target
3024
3025Ways to specify:
3026
3027@enumerate
3028@item
3029command line option: @samp{--target}
3030
3031@item
3032environment variable @code{GNUTARGET}
3033
3034@item
3035deduced from the input file
3036@end enumerate
3037
3038@subheading Linker Input Target
3039
3040Ways to specify:
3041
3042@enumerate
3043@item
3044command line option: @samp{-b} or @samp{--format}
3045(@pxref{Options,,Options,ld.info,Using LD})
3046
3047@item
3048script command @code{TARGET}
3049(@pxref{Option Commands,,Option Commands,ld.info,Using LD})
3050
3051@item
3052environment variable @code{GNUTARGET}
3053(@pxref{Environment,,Environment,ld.info,Using LD})
3054
3055@item
3056the default target of the selected linker emulation
3057(@pxref{Linker Emulation Selection})
3058@end enumerate
3059
3060@subheading Linker Output Target
3061
3062Ways to specify:
3063
3064@enumerate
3065@item
3066command line option: @samp{-oformat}
3067(@pxref{Options,,Options,ld.info,Using LD})
3068
3069@item
3070script command @code{OUTPUT_FORMAT}
3071(@pxref{Option Commands,,Option Commands,ld.info,Using LD})
3072
3073@item
3074the linker input target (see ``Linker Input Target'' above)
3075@end enumerate
3076
3077@node Architecture Selection
3078@section Architecture selection
3079
3080An @dfn{architecture} is a type of @sc{cpu} on which an object file is
3081to run. Its name may contain a colon, separating the name of the
3082processor family from the name of the particular @sc{cpu}.
3083
3084The command to list valid architecture values is @samp{objdump -i} (the
3085second column contains the relevant information).
3086
3087Sample values: @samp{m68k:68020}, @samp{mips:3000}, @samp{sparc}.
3088
3089@subheading @code{objdump} Architecture
3090
3091Ways to specify:
3092
3093@enumerate
3094@item
3095command line option: @samp{-m} or @samp{--architecture}
3096
3097@item
3098deduced from the input file
3099@end enumerate
3100
3101@subheading @code{objcopy}, @code{nm}, @code{size}, @code{strings} Architecture
3102
3103Ways to specify:
3104
3105@enumerate
3106@item
3107deduced from the input file
3108@end enumerate
3109
3110@subheading Linker Input Architecture
3111
3112Ways to specify:
3113
3114@enumerate
3115@item
3116deduced from the input file
3117@end enumerate
3118
3119@subheading Linker Output Architecture
3120
3121Ways to specify:
3122
3123@enumerate
3124@item
3125script command @code{OUTPUT_ARCH}
3126(@pxref{Option Commands,,Option Commands,ld.info,Using LD})
3127
3128@item
3129the default architecture from the linker output target
3130(@pxref{Target Selection})
3131@end enumerate
3132
3133@node Linker Emulation Selection
3134@section Linker emulation selection
3135
3136A linker @dfn{emulation} is a ``personality'' of the linker, which gives
3137the linker default values for the other aspects of the target system.
3138In particular, it consists of
3139
3140@itemize @bullet
3141@item
3142the linker script
3143
3144@item
3145the target
3146
3147@item
3148several ``hook'' functions that are run at certain stages of the linking
3149process to do special things that some targets require
3150@end itemize
3151
3152The command to list valid linker emulation values is @samp{ld -V}.
3153
3154Sample values: @samp{hp300bsd}, @samp{mipslit}, @samp{sun4}.
3155
3156Ways to specify:
3157
3158@enumerate
3159@item
3160command line option: @samp{-m}
3161(@pxref{Options,,Options,ld.info,Using LD})
3162
3163@item
3164environment variable @code{LDEMULATION}
3165
3166@item
3167compiled-in @code{DEFAULT_EMULATION} from @file{Makefile},
3168which comes from @code{EMUL} in @file{config/@var{target}.mt}
3169@end enumerate
3170
3171@node Reporting Bugs
3172@chapter Reporting Bugs
3173@cindex bugs
3174@cindex reporting bugs
3175
3176Your bug reports play an essential role in making the binary utilities
3177reliable.
3178
3179Reporting a bug may help you by bringing a solution to your problem, or
3180it may not. But in any case the principal function of a bug report is
3181to help the entire community by making the next version of the binary
3182utilities work better. Bug reports are your contribution to their
3183maintenance.
3184
3185In order for a bug report to serve its purpose, you must include the
3186information that enables us to fix the bug.
3187
3188@menu
3189* Bug Criteria:: Have you found a bug?
3190* Bug Reporting:: How to report bugs
3191@end menu
3192
3193@node Bug Criteria
3194@section Have you found a bug?
3195@cindex bug criteria
3196
3197If you are not sure whether you have found a bug, here are some guidelines:
3198
3199@itemize @bullet
3200@cindex fatal signal
3201@cindex crash
3202@item
3203If a binary utility gets a fatal signal, for any input whatever, that is
3204a bug. Reliable utilities never crash.
3205
3206@cindex error on valid input
3207@item
3208If a binary utility produces an error message for valid input, that is a
3209bug.
3210
3211@item
3212If you are an experienced user of binary utilities, your suggestions for
3213improvement are welcome in any case.
3214@end itemize
3215
3216@node Bug Reporting
3217@section How to report bugs
3218@cindex bug reports
3219@cindex bugs, reporting
3220
3221A number of companies and individuals offer support for @sc{gnu}
3222products. If you obtained the binary utilities from a support
3223organization, we recommend you contact that organization first.
3224
3225You can find contact information for many support companies and
3226individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
3227distribution.
3228
3229In any event, we also recommend that you send bug reports for the binary
2f952d20 3230utilities to @samp{bug-binutils@@gnu.org}.
252b5132
RH
3231
3232The fundamental principle of reporting bugs usefully is this:
3233@strong{report all the facts}. If you are not sure whether to state a
3234fact or leave it out, state it!
3235
3236Often people omit facts because they think they know what causes the
3237problem and assume that some details do not matter. Thus, you might
3238assume that the name of a file you use in an example does not matter.
3239Well, probably it does not, but one cannot be sure. Perhaps the bug is
3240a stray memory reference which happens to fetch from the location where
3241that pathname is stored in memory; perhaps, if the pathname were
3242different, the contents of that location would fool the utility into
3243doing the right thing despite the bug. Play it safe and give a
3244specific, complete example. That is the easiest thing for you to do,
3245and the most helpful.
3246
3247Keep in mind that the purpose of a bug report is to enable us to fix the bug if
3248it is new to us. Therefore, always write your bug reports on the assumption
3249that the bug has not been reported previously.
3250
3251Sometimes people give a few sketchy facts and ask, ``Does this ring a
3252bell?'' Those bug reports are useless, and we urge everyone to
3253@emph{refuse to respond to them} except to chide the sender to report
3254bugs properly.
3255
3256To enable us to fix the bug, you should include all these things:
3257
3258@itemize @bullet
3259@item
3260The version of the utility. Each utility announces it if you start it
3261with the @samp{--version} argument.
3262
3263Without this, we will not know whether there is any point in looking for
3264the bug in the current version of the binary utilities.
3265
3266@item
3267Any patches you may have applied to the source, including any patches
3268made to the @code{BFD} library.
3269
3270@item
3271The type of machine you are using, and the operating system name and
3272version number.
3273
3274@item
3275What compiler (and its version) was used to compile the utilities---e.g.
3276``@code{gcc-2.7}''.
3277
3278@item
3279The command arguments you gave the utility to observe the bug. To
3280guarantee you will not omit something important, list them all. A copy
3281of the Makefile (or the output from make) is sufficient.
3282
3283If we were to try to guess the arguments, we would probably guess wrong
3284and then we might not encounter the bug.
3285
3286@item
3287A complete input file, or set of input files, that will reproduce the
3288bug. If the utility is reading an object file or files, then it is
3289generally most helpful to send the actual object files, uuencoded if
757acbc5 3290necessary to get them through the mail system. Note that
2f952d20 3291@samp{bug-binutils@@gnu.org} is a mailing list, so you should avoid
757acbc5
ILT
3292sending very large files to it. Making the files available for
3293anonymous FTP is OK.
252b5132
RH
3294
3295If the source files were produced exclusively using @sc{gnu} programs
3296(e.g., @code{gcc}, @code{gas}, and/or the @sc{gnu} @code{ld}), then it
3297may be OK to send the source files rather than the object files. In
3298this case, be sure to say exactly what version of @code{gcc}, or
3299whatever, was used to produce the object files. Also say how
3300@code{gcc}, or whatever, was configured.
3301
3302@item
3303A description of what behavior you observe that you believe is
3304incorrect. For example, ``It gets a fatal signal.''
3305
3306Of course, if the bug is that the utility gets a fatal signal, then we
3307will certainly notice it. But if the bug is incorrect output, we might
3308not notice unless it is glaringly wrong. You might as well not give us
3309a chance to make a mistake.
3310
3311Even if the problem you experience is a fatal signal, you should still
f20a759a 3312say so explicitly. Suppose something strange is going on, such as your
252b5132
RH
3313copy of the utility is out of synch, or you have encountered a bug in
3314the C library on your system. (This has happened!) Your copy might
3315crash and ours would not. If you told us to expect a crash, then when
3316ours fails to crash, we would know that the bug was not happening for
3317us. If you had not told us to expect a crash, then we would not be able
3318to draw any conclusion from our observations.
3319
3320@item
3321If you wish to suggest changes to the source, send us context diffs, as
3322generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
3323option. Always send diffs from the old file to the new file. If you
f20a759a
ILT
3324wish to discuss something in the @code{ld} source, refer to it by
3325context, not by line number.
252b5132
RH
3326
3327The line numbers in our development sources will not match those in your
3328sources. Your line numbers would convey no useful information to us.
3329@end itemize
3330
3331Here are some things that are not necessary:
3332
3333@itemize @bullet
3334@item
3335A description of the envelope of the bug.
3336
3337Often people who encounter a bug spend a lot of time investigating
3338which changes to the input file will make the bug go away and which
3339changes will not affect it.
3340
3341This is often time consuming and not very useful, because the way we
3342will find the bug is by running a single example under the debugger
3343with breakpoints, not by pure deduction from a series of examples.
3344We recommend that you save your time for something else.
3345
3346Of course, if you can find a simpler example to report @emph{instead}
3347of the original one, that is a convenience for us. Errors in the
3348output will be easier to spot, running under the debugger will take
3349less time, and so on.
3350
3351However, simplification is not vital; if you do not want to do this,
3352report the bug anyway and send us the entire test case you used.
3353
3354@item
3355A patch for the bug.
3356
3357A patch for the bug does help us if it is a good one. But do not omit
3358the necessary information, such as the test case, on the assumption that
3359a patch is all we need. We might see problems with your patch and decide
3360to fix the problem another way, or we might not understand it at all.
3361
3362Sometimes with programs as complicated as the binary utilities it is
3363very hard to construct an example that will make the program follow a
3364certain path through the code. If you do not send us the example, we
3365will not be able to construct one, so we will not be able to verify that
3366the bug is fixed.
3367
3368And if we cannot understand what bug you are trying to fix, or why your
3369patch should be an improvement, we will not install it. A test case will
3370help us to understand.
3371
3372@item
3373A guess about what the bug is or what it depends on.
3374
3375Such guesses are usually wrong. Even we cannot guess right about such
3376things without first using the debugger to find the facts.
3377@end itemize
3378
cf055d54
NC
3379@node GNU Free Documentation License
3380@chapter GNU Free Documentation License
3381@cindex GNU Free Documentation License
3382
3383 GNU Free Documentation License
3384
3385 Version 1.1, March 2000
3386
3387 Copyright (C) 2000 Free Software Foundation, Inc.
3388 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
3389
3390 Everyone is permitted to copy and distribute verbatim copies
3391 of this license document, but changing it is not allowed.
3392
3393
33940. PREAMBLE
3395
3396The purpose of this License is to make a manual, textbook, or other
3397written document "free" in the sense of freedom: to assure everyone
3398the effective freedom to copy and redistribute it, with or without
3399modifying it, either commercially or noncommercially. Secondarily,
3400this License preserves for the author and publisher a way to get
3401credit for their work, while not being considered responsible for
3402modifications made by others.
3403
3404This License is a kind of "copyleft", which means that derivative
3405works of the document must themselves be free in the same sense. It
3406complements the GNU General Public License, which is a copyleft
3407license designed for free software.
3408
3409We have designed this License in order to use it for manuals for free
3410software, because free software needs free documentation: a free
3411program should come with manuals providing the same freedoms that the
3412software does. But this License is not limited to software manuals;
3413it can be used for any textual work, regardless of subject matter or
3414whether it is published as a printed book. We recommend this License
3415principally for works whose purpose is instruction or reference.
3416
3417
34181. APPLICABILITY AND DEFINITIONS
3419
3420This License applies to any manual or other work that contains a
3421notice placed by the copyright holder saying it can be distributed
3422under the terms of this License. The "Document", below, refers to any
3423such manual or work. Any member of the public is a licensee, and is
3424addressed as "you".
3425
3426A "Modified Version" of the Document means any work containing the
3427Document or a portion of it, either copied verbatim, or with
3428modifications and/or translated into another language.
3429
3430A "Secondary Section" is a named appendix or a front-matter section of
3431the Document that deals exclusively with the relationship of the
3432publishers or authors of the Document to the Document's overall subject
3433(or to related matters) and contains nothing that could fall directly
3434within that overall subject. (For example, if the Document is in part a
3435textbook of mathematics, a Secondary Section may not explain any
3436mathematics.) The relationship could be a matter of historical
3437connection with the subject or with related matters, or of legal,
3438commercial, philosophical, ethical or political position regarding
3439them.
3440
3441The "Invariant Sections" are certain Secondary Sections whose titles
3442are designated, as being those of Invariant Sections, in the notice
3443that says that the Document is released under this License.
3444
3445The "Cover Texts" are certain short passages of text that are listed,
3446as Front-Cover Texts or Back-Cover Texts, in the notice that says that
3447the Document is released under this License.
3448
3449A "Transparent" copy of the Document means a machine-readable copy,
3450represented in a format whose specification is available to the
3451general public, whose contents can be viewed and edited directly and
3452straightforwardly with generic text editors or (for images composed of
3453pixels) generic paint programs or (for drawings) some widely available
3454drawing editor, and that is suitable for input to text formatters or
3455for automatic translation to a variety of formats suitable for input
3456to text formatters. A copy made in an otherwise Transparent file
3457format whose markup has been designed to thwart or discourage
3458subsequent modification by readers is not Transparent. A copy that is
3459not "Transparent" is called "Opaque".
3460
3461Examples of suitable formats for Transparent copies include plain
3462ASCII without markup, Texinfo input format, LaTeX input format, SGML
3463or XML using a publicly available DTD, and standard-conforming simple
3464HTML designed for human modification. Opaque formats include
3465PostScript, PDF, proprietary formats that can be read and edited only
3466by proprietary word processors, SGML or XML for which the DTD and/or
3467processing tools are not generally available, and the
3468machine-generated HTML produced by some word processors for output
3469purposes only.
3470
3471The "Title Page" means, for a printed book, the title page itself,
3472plus such following pages as are needed to hold, legibly, the material
3473this License requires to appear in the title page. For works in
3474formats which do not have any title page as such, "Title Page" means
3475the text near the most prominent appearance of the work's title,
3476preceding the beginning of the body of the text.
3477
3478
34792. VERBATIM COPYING
3480
3481You may copy and distribute the Document in any medium, either
3482commercially or noncommercially, provided that this License, the
3483copyright notices, and the license notice saying this License applies
3484to the Document are reproduced in all copies, and that you add no other
3485conditions whatsoever to those of this License. You may not use
3486technical measures to obstruct or control the reading or further
3487copying of the copies you make or distribute. However, you may accept
3488compensation in exchange for copies. If you distribute a large enough
3489number of copies you must also follow the conditions in section 3.
3490
3491You may also lend copies, under the same conditions stated above, and
3492you may publicly display copies.
3493
3494
34953. COPYING IN QUANTITY
3496
3497If you publish printed copies of the Document numbering more than 100,
3498and the Document's license notice requires Cover Texts, you must enclose
3499the copies in covers that carry, clearly and legibly, all these Cover
3500Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
3501the back cover. Both covers must also clearly and legibly identify
3502you as the publisher of these copies. The front cover must present
3503the full title with all words of the title equally prominent and
3504visible. You may add other material on the covers in addition.
3505Copying with changes limited to the covers, as long as they preserve
3506the title of the Document and satisfy these conditions, can be treated
3507as verbatim copying in other respects.
3508
3509If the required texts for either cover are too voluminous to fit
3510legibly, you should put the first ones listed (as many as fit
3511reasonably) on the actual cover, and continue the rest onto adjacent
3512pages.
3513
3514If you publish or distribute Opaque copies of the Document numbering
3515more than 100, you must either include a machine-readable Transparent
3516copy along with each Opaque copy, or state in or with each Opaque copy
3517a publicly-accessible computer-network location containing a complete
3518Transparent copy of the Document, free of added material, which the
3519general network-using public has access to download anonymously at no
3520charge using public-standard network protocols. If you use the latter
3521option, you must take reasonably prudent steps, when you begin
3522distribution of Opaque copies in quantity, to ensure that this
3523Transparent copy will remain thus accessible at the stated location
3524until at least one year after the last time you distribute an Opaque
3525copy (directly or through your agents or retailers) of that edition to
3526the public.
3527
3528It is requested, but not required, that you contact the authors of the
3529Document well before redistributing any large number of copies, to give
3530them a chance to provide you with an updated version of the Document.
3531
3532
35334. MODIFICATIONS
3534
3535You may copy and distribute a Modified Version of the Document under
3536the conditions of sections 2 and 3 above, provided that you release
3537the Modified Version under precisely this License, with the Modified
3538Version filling the role of the Document, thus licensing distribution
3539and modification of the Modified Version to whoever possesses a copy
3540of it. In addition, you must do these things in the Modified Version:
3541
3542A. Use in the Title Page (and on the covers, if any) a title distinct
3543 from that of the Document, and from those of previous versions
3544 (which should, if there were any, be listed in the History section
3545 of the Document). You may use the same title as a previous version
3546 if the original publisher of that version gives permission.
3547B. List on the Title Page, as authors, one or more persons or entities
3548 responsible for authorship of the modifications in the Modified
3549 Version, together with at least five of the principal authors of the
3550 Document (all of its principal authors, if it has less than five).
3551C. State on the Title page the name of the publisher of the
3552 Modified Version, as the publisher.
3553D. Preserve all the copyright notices of the Document.
3554E. Add an appropriate copyright notice for your modifications
3555 adjacent to the other copyright notices.
3556F. Include, immediately after the copyright notices, a license notice
3557 giving the public permission to use the Modified Version under the
3558 terms of this License, in the form shown in the Addendum below.
3559G. Preserve in that license notice the full lists of Invariant Sections
3560 and required Cover Texts given in the Document's license notice.
3561H. Include an unaltered copy of this License.
3562I. Preserve the section entitled "History", and its title, and add to
3563 it an item stating at least the title, year, new authors, and
3564 publisher of the Modified Version as given on the Title Page. If
3565 there is no section entitled "History" in the Document, create one
3566 stating the title, year, authors, and publisher of the Document as
3567 given on its Title Page, then add an item describing the Modified
3568 Version as stated in the previous sentence.
3569J. Preserve the network location, if any, given in the Document for
3570 public access to a Transparent copy of the Document, and likewise
3571 the network locations given in the Document for previous versions
3572 it was based on. These may be placed in the "History" section.
3573 You may omit a network location for a work that was published at
3574 least four years before the Document itself, or if the original
3575 publisher of the version it refers to gives permission.
3576K. In any section entitled "Acknowledgements" or "Dedications",
3577 preserve the section's title, and preserve in the section all the
3578 substance and tone of each of the contributor acknowledgements
3579 and/or dedications given therein.
3580L. Preserve all the Invariant Sections of the Document,
3581 unaltered in their text and in their titles. Section numbers
3582 or the equivalent are not considered part of the section titles.
3583M. Delete any section entitled "Endorsements". Such a section
3584 may not be included in the Modified Version.
3585N. Do not retitle any existing section as "Endorsements"
3586 or to conflict in title with any Invariant Section.
3587
3588If the Modified Version includes new front-matter sections or
3589appendices that qualify as Secondary Sections and contain no material
3590copied from the Document, you may at your option designate some or all
3591of these sections as invariant. To do this, add their titles to the
3592list of Invariant Sections in the Modified Version's license notice.
3593These titles must be distinct from any other section titles.
3594
3595You may add a section entitled "Endorsements", provided it contains
3596nothing but endorsements of your Modified Version by various
3597parties--for example, statements of peer review or that the text has
3598been approved by an organization as the authoritative definition of a
3599standard.
3600
3601You may add a passage of up to five words as a Front-Cover Text, and a
3602passage of up to 25 words as a Back-Cover Text, to the end of the list
3603of Cover Texts in the Modified Version. Only one passage of
3604Front-Cover Text and one of Back-Cover Text may be added by (or
3605through arrangements made by) any one entity. If the Document already
3606includes a cover text for the same cover, previously added by you or
3607by arrangement made by the same entity you are acting on behalf of,
3608you may not add another; but you may replace the old one, on explicit
3609permission from the previous publisher that added the old one.
3610
3611The author(s) and publisher(s) of the Document do not by this License
3612give permission to use their names for publicity for or to assert or
3613imply endorsement of any Modified Version.
3614
3615
36165. COMBINING DOCUMENTS
3617
3618You may combine the Document with other documents released under this
3619License, under the terms defined in section 4 above for modified
3620versions, provided that you include in the combination all of the
3621Invariant Sections of all of the original documents, unmodified, and
3622list them all as Invariant Sections of your combined work in its
3623license notice.
3624
3625The combined work need only contain one copy of this License, and
3626multiple identical Invariant Sections may be replaced with a single
3627copy. If there are multiple Invariant Sections with the same name but
3628different contents, make the title of each such section unique by
3629adding at the end of it, in parentheses, the name of the original
3630author or publisher of that section if known, or else a unique number.
3631Make the same adjustment to the section titles in the list of
3632Invariant Sections in the license notice of the combined work.
3633
3634In the combination, you must combine any sections entitled "History"
3635in the various original documents, forming one section entitled
3636"History"; likewise combine any sections entitled "Acknowledgements",
3637and any sections entitled "Dedications". You must delete all sections
3638entitled "Endorsements."
3639
3640
36416. COLLECTIONS OF DOCUMENTS
3642
3643You may make a collection consisting of the Document and other documents
3644released under this License, and replace the individual copies of this
3645License in the various documents with a single copy that is included in
3646the collection, provided that you follow the rules of this License for
3647verbatim copying of each of the documents in all other respects.
3648
3649You may extract a single document from such a collection, and distribute
3650it individually under this License, provided you insert a copy of this
3651License into the extracted document, and follow this License in all
3652other respects regarding verbatim copying of that document.
3653
3654
36557. AGGREGATION WITH INDEPENDENT WORKS
3656
3657A compilation of the Document or its derivatives with other separate
3658and independent documents or works, in or on a volume of a storage or
3659distribution medium, does not as a whole count as a Modified Version
3660of the Document, provided no compilation copyright is claimed for the
3661compilation. Such a compilation is called an "aggregate", and this
3662License does not apply to the other self-contained works thus compiled
3663with the Document, on account of their being thus compiled, if they
3664are not themselves derivative works of the Document.
3665
3666If the Cover Text requirement of section 3 is applicable to these
3667copies of the Document, then if the Document is less than one quarter
3668of the entire aggregate, the Document's Cover Texts may be placed on
3669covers that surround only the Document within the aggregate.
3670Otherwise they must appear on covers around the whole aggregate.
3671
3672
36738. TRANSLATION
3674
3675Translation is considered a kind of modification, so you may
3676distribute translations of the Document under the terms of section 4.
3677Replacing Invariant Sections with translations requires special
3678permission from their copyright holders, but you may include
3679translations of some or all Invariant Sections in addition to the
3680original versions of these Invariant Sections. You may include a
3681translation of this License provided that you also include the
3682original English version of this License. In case of a disagreement
3683between the translation and the original English version of this
3684License, the original English version will prevail.
3685
3686
36879. TERMINATION
3688
3689You may not copy, modify, sublicense, or distribute the Document except
3690as expressly provided for under this License. Any other attempt to
3691copy, modify, sublicense or distribute the Document is void, and will
3692automatically terminate your rights under this License. However,
3693parties who have received copies, or rights, from you under this
3694License will not have their licenses terminated so long as such
3695parties remain in full compliance.
3696
3697
369810. FUTURE REVISIONS OF THIS LICENSE
3699
3700The Free Software Foundation may publish new, revised versions
3701of the GNU Free Documentation License from time to time. Such new
3702versions will be similar in spirit to the present version, but may
3703differ in detail to address new problems or concerns. See
3704http://www.gnu.org/copyleft/.
3705
3706Each version of the License is given a distinguishing version number.
3707If the Document specifies that a particular numbered version of this
3708License "or any later version" applies to it, you have the option of
3709following the terms and conditions either of that specified version or
3710of any later version that has been published (not as a draft) by the
3711Free Software Foundation. If the Document does not specify a version
3712number of this License, you may choose any version ever published (not
3713as a draft) by the Free Software Foundation.
3714
3715
3716ADDENDUM: How to use this License for your documents
3717
3718To use this License in a document you have written, include a copy of
3719the License in the document and put the following copyright and
3720license notices just after the title page:
3721
3722@smallexample
3723 Copyright (c) YEAR YOUR NAME.
3724 Permission is granted to copy, distribute and/or modify this document
3725 under the terms of the GNU Free Documentation License, Version 1.1
3726 or any later version published by the Free Software Foundation;
3727 with the Invariant Sections being LIST THEIR TITLES, with the
3728 Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
3729 A copy of the license is included in the section entitled "GNU
3730 Free Documentation License".
3731@end smallexample
3732
3733If you have no Invariant Sections, write "with no Invariant Sections"
3734instead of saying which ones are invariant. If you have no
3735Front-Cover Texts, write "no Front-Cover Texts" instead of
3736"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
3737
3738If your document contains nontrivial examples of program code, we
3739recommend releasing these examples in parallel under your choice of
3740free software license, such as the GNU General Public License,
3741to permit their use in free software.
3742
252b5132
RH
3743@node Index
3744@unnumbered Index
3745
3746@printindex cp
3747
3748@contents
3749@bye
This page took 0.281139 seconds and 4 git commands to generate.