1 \input texinfo @c -*- Texinfo -*-
2 @setfilename binutils.info
3 @c Copyright 2001 Free Software Foundation, Inc.
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
31 Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
33 Permission is granted to copy, distribute and/or modify this document
34 under the terms of the GNU Free Documentation License, Version 1.1
35 or any later version published by the Free Software Foundation;
36 with no Invariant Sections, with no Front-Cover Texts, and with no
37 Back-Cover Texts. A copy of the license is included in the
38 section entitled "GNU Free Documentation License".
41 Permission is granted to process this file through TeX and print the
42 results, provided the printed document carries a copying permission
43 notice identical to this one except for the removal of this paragraph
44 (this paragraph not being relevant to the printed manual).
51 @c This file documents the GNU binary utilities "ar", "ld", "objcopy",
52 @c "objdump", "nm", "size", "strings", "strip", "readelf" and "ranlib".
54 @c Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
56 @c This text may be freely distributed under the terms of the GNU
57 @c Free Documentation License.
60 @setchapternewpage odd
61 @settitle @sc{gnu} Binary Utilities
64 @title The @sc{gnu} Binary Utilities
65 @subtitle Version @value{VERSION}
68 @author Roland H. Pesch
69 @author Jeffrey M. Osier
70 @author Cygnus Support
74 {\parskip=0pt \hfill Cygnus Support\par \hfill
75 \TeX{}info \texinfoversion\par }
78 @vskip 0pt plus 1filll
79 Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998, 2000, 2001 Free Software Foundation, Inc.
81 Permission is granted to copy, distribute and/or modify this document
82 under the terms of the GNU Free Documentation License, Version 1.1
83 or any later version published by the Free Software Foundation;
84 with no Invariant Sections, with no Front-Cover Texts, and with no
85 Back-Cover Texts. A copy of the license is included in the
86 section entitled "GNU Free Documentation License".
94 This brief manual contains preliminary documentation for the @sc{gnu} binary
95 utilities (collectively version @value{VERSION}):
100 Create, modify, and extract from archives
103 List symbols from object files
106 Copy and translate object files
109 Display information from object files
112 Generate index to archive contents
115 Display the contents of ELF format files.
118 List file section sizes and total size
121 List printable strings from files
127 Demangle encoded C++ symbols (on MS-DOS, this program is named
131 Convert addresses into file names and line numbers
134 Convert object code into a Netware Loadable Module
137 Manipulate Windows resources
140 Create the files needed to build and use Dynamic Link Libraries
144 This document is distributed under the terms of the GNU Free
145 Documentation License. A copy of the license is included in the
146 section entitled "GNU Free Documentation License".
149 * ar:: Create, modify, and extract from archives
150 * nm:: List symbols from object files
151 * objcopy:: Copy and translate object files
152 * objdump:: Display information from object files
153 * ranlib:: Generate index to archive contents
154 * readelf:: Display the contents of ELF format files.
155 * size:: List section sizes and total size
156 * strings:: List printable strings from files
157 * strip:: Discard symbols
158 * c++filt:: Filter to demangle encoded C++ symbols
159 * cxxfilt: c++filt. MS-DOS name for c++filt
160 * addr2line:: Convert addresses to file and line
161 * nlmconv:: Converts object code into an NLM
162 * windres:: Manipulate Windows resources
163 * dlltool:: Create files needed to build and use DLLs
164 * Selecting The Target System:: How these utilities determine the target.
165 * Reporting Bugs:: Reporting Bugs
166 * GNU Free Documentation License:: GNU Free Documentation License
175 @cindex collections of files
177 ar [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
178 ar -M [ <mri-script ]
181 The @sc{gnu} @code{ar} program creates, modifies, and extracts from
182 archives. An @dfn{archive} is a single file holding a collection of
183 other files in a structure that makes it possible to retrieve
184 the original individual files (called @dfn{members} of the archive).
186 The original files' contents, mode (permissions), timestamp, owner, and
187 group are preserved in the archive, and can be restored on
191 @sc{gnu} @code{ar} can maintain archives whose members have names of any
192 length; however, depending on how @code{ar} is configured on your
193 system, a limit on member-name length may be imposed for compatibility
194 with archive formats maintained with other tools. If it exists, the
195 limit is often 15 characters (typical of formats related to a.out) or 16
196 characters (typical of formats related to coff).
199 @code{ar} is considered a binary utility because archives of this sort
200 are most often used as @dfn{libraries} holding commonly needed
204 @code{ar} creates an index to the symbols defined in relocatable
205 object modules in the archive when you specify the modifier @samp{s}.
206 Once created, this index is updated in the archive whenever @code{ar}
207 makes a change to its contents (save for the @samp{q} update operation).
208 An archive with such an index speeds up linking to the library, and
209 allows routines in the library to call each other without regard to
210 their placement in the archive.
212 You may use @samp{nm -s} or @samp{nm --print-armap} to list this index
213 table. If an archive lacks the table, another form of @code{ar} called
214 @code{ranlib} can be used to add just the table.
216 @cindex compatibility, @code{ar}
217 @cindex @code{ar} compatibility
218 @sc{gnu} @code{ar} is designed to be compatible with two different
219 facilities. You can control its activity using command-line options,
220 like the different varieties of @code{ar} on Unix systems; or, if you
221 specify the single command-line option @samp{-M}, you can control it
222 with a script supplied via standard input, like the MRI ``librarian''
226 * ar cmdline:: Controlling @code{ar} on the command line
227 * ar scripts:: Controlling @code{ar} with a script
232 @section Controlling @code{ar} on the command line
235 ar [-X32_64] [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
238 @cindex Unix compatibility, @code{ar}
239 When you use @code{ar} in the Unix style, @code{ar} insists on at least two
240 arguments to execute: one keyletter specifying the @emph{operation}
241 (optionally accompanied by other keyletters specifying
242 @emph{modifiers}), and the archive name to act on.
244 Most operations can also accept further @var{member} arguments,
245 specifying particular files to operate on.
247 @sc{gnu} @code{ar} allows you to mix the operation code @var{p} and modifier
248 flags @var{mod} in any order, within the first command-line argument.
250 If you wish, you may begin the first command-line argument with a
253 @cindex operations on archive
254 The @var{p} keyletter specifies what operation to execute; it may be
255 any of the following, but you must specify only one of them:
259 @cindex deleting from archive
260 @emph{Delete} modules from the archive. Specify the names of modules to
261 be deleted as @var{member}@dots{}; the archive is untouched if you
262 specify no files to delete.
264 If you specify the @samp{v} modifier, @code{ar} lists each module
268 @cindex moving in archive
269 Use this operation to @emph{move} members in an archive.
271 The ordering of members in an archive can make a difference in how
272 programs are linked using the library, if a symbol is defined in more
275 If no modifiers are used with @code{m}, any members you name in the
276 @var{member} arguments are moved to the @emph{end} of the archive;
277 you can use the @samp{a}, @samp{b}, or @samp{i} modifiers to move them to a
278 specified place instead.
281 @cindex printing from archive
282 @emph{Print} the specified members of the archive, to the standard
283 output file. If the @samp{v} modifier is specified, show the member
284 name before copying its contents to standard output.
286 If you specify no @var{member} arguments, all the files in the archive are
290 @cindex quick append to archive
291 @emph{Quick append}; Historically, add the files @var{member}@dots{} to the end of
292 @var{archive}, without checking for replacement.
294 The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this
295 operation; new members are always placed at the end of the archive.
297 The modifier @samp{v} makes @code{ar} list each file as it is appended.
299 Since the point of this operation is speed, the archive's symbol table
300 index is not updated, even if it already existed; you can use @samp{ar s} or
301 @code{ranlib} explicitly to update the symbol table index.
303 However, too many different systems assume quick append rebuilds the
304 index, so GNU ar implements @code{q} as a synonym for @code{r}.
307 @cindex replacement in archive
308 Insert the files @var{member}@dots{} into @var{archive} (with
309 @emph{replacement}). This operation differs from @samp{q} in that any
310 previously existing members are deleted if their names match those being
313 If one of the files named in @var{member}@dots{} does not exist, @code{ar}
314 displays an error message, and leaves undisturbed any existing members
315 of the archive matching that name.
317 By default, new members are added at the end of the file; but you may
318 use one of the modifiers @samp{a}, @samp{b}, or @samp{i} to request
319 placement relative to some existing member.
321 The modifier @samp{v} used with this operation elicits a line of
322 output for each file inserted, along with one of the letters @samp{a} or
323 @samp{r} to indicate whether the file was appended (no old member
324 deleted) or replaced.
327 @cindex contents of archive
328 Display a @emph{table} listing the contents of @var{archive}, or those
329 of the files listed in @var{member}@dots{} that are present in the
330 archive. Normally only the member name is shown; if you also want to
331 see the modes (permissions), timestamp, owner, group, and size, you can
332 request that by also specifying the @samp{v} modifier.
334 If you do not specify a @var{member}, all files in the archive
337 @cindex repeated names in archive
338 @cindex name duplication in archive
339 If there is more than one file with the same name (say, @samp{fie}) in
340 an archive (say @samp{b.a}), @samp{ar t b.a fie} lists only the
341 first instance; to see them all, you must ask for a complete
342 listing---in our example, @samp{ar t b.a}.
343 @c WRS only; per Gumby, this is implementation-dependent, and in a more
344 @c recent case in fact works the other way.
347 @cindex extract from archive
348 @emph{Extract} members (named @var{member}) from the archive. You can
349 use the @samp{v} modifier with this operation, to request that
350 @code{ar} list each name as it extracts it.
352 If you do not specify a @var{member}, all files in the archive
357 A number of modifiers (@var{mod}) may immediately follow the @var{p}
358 keyletter, to specify variations on an operation's behavior:
362 @cindex relative placement in archive
363 Add new files @emph{after} an existing member of the
364 archive. If you use the modifier @samp{a}, the name of an existing archive
365 member must be present as the @var{relpos} argument, before the
366 @var{archive} specification.
369 Add new files @emph{before} an existing member of the
370 archive. If you use the modifier @samp{b}, the name of an existing archive
371 member must be present as the @var{relpos} argument, before the
372 @var{archive} specification. (same as @samp{i}).
375 @cindex creating archives
376 @emph{Create} the archive. The specified @var{archive} is always
377 created if it did not exist, when you request an update. But a warning is
378 issued unless you specify in advance that you expect to create it, by
382 Truncate names in the archive. @sc{gnu} @code{ar} will normally permit file
383 names of any length. This will cause it to create archives which are
384 not compatible with the native @code{ar} program on some systems. If
385 this is a concern, the @samp{f} modifier may be used to truncate file
386 names when putting them in the archive.
389 Insert new files @emph{before} an existing member of the
390 archive. If you use the modifier @samp{i}, the name of an existing archive
391 member must be present as the @var{relpos} argument, before the
392 @var{archive} specification. (same as @samp{b}).
395 This modifier is accepted but not used.
396 @c whaffor ar l modifier??? presumably compat; with
397 @c what???---doc@@cygnus.com, 25jan91
400 Uses the @var{count} parameter. This is used if there are multiple
401 entries in the archive with the same name. Extract or delete instance
402 @var{count} of the given name from the archive.
405 @cindex dates in archive
406 Preserve the @emph{original} dates of members when extracting them. If
407 you do not specify this modifier, files extracted from the archive
408 are stamped with the time of extraction.
411 Use the full path name when matching names in the archive. @sc{gnu}
412 @code{ar} can not create an archive with a full path name (such archives
413 are not POSIX complaint), but other archive creators can. This option
414 will cause @sc{gnu} @code{ar} to match file names using a complete path
415 name, which can be convenient when extracting a single file from an
416 archive created by another tool.
419 @cindex writing archive index
420 Write an object-file index into the archive, or update an existing one,
421 even if no other change is made to the archive. You may use this modifier
422 flag either with any operation, or alone. Running @samp{ar s} on an
423 archive is equivalent to running @samp{ranlib} on it.
426 @cindex not writing archive index
427 Do not generate an archive symbol table. This can speed up building a
428 large library in several steps. The resulting archive can not be used
429 with the linker. In order to build a symbol table, you must omit the
430 @samp{S} modifier on the last execution of @samp{ar}, or you must run
431 @samp{ranlib} on the archive.
434 @cindex updating an archive
435 Normally, @samp{ar r}@dots{} inserts all files
436 listed into the archive. If you would like to insert @emph{only} those
437 of the files you list that are newer than existing members of the same
438 names, use this modifier. The @samp{u} modifier is allowed only for the
439 operation @samp{r} (replace). In particular, the combination @samp{qu} is
440 not allowed, since checking the timestamps would lose any speed
441 advantage from the operation @samp{q}.
444 This modifier requests the @emph{verbose} version of an operation. Many
445 operations display additional information, such as filenames processed,
446 when the modifier @samp{v} is appended.
449 This modifier shows the version number of @code{ar}.
452 @code{ar} ignores an initial option spelt @code{-X32_64}, for
453 compatibility with AIX. The behaviour produced by this option is the
454 default for GNU @code{ar}. @code{ar} does not support any of the other
455 @code{-X} options; in particular, it does not support @code{-X32}
456 which is the default for AIX @code{ar}.
459 @section Controlling @code{ar} with a script
462 ar -M [ <@var{script} ]
465 @cindex MRI compatibility, @code{ar}
466 @cindex scripts, @code{ar}
467 If you use the single command-line option @samp{-M} with @code{ar}, you
468 can control its operation with a rudimentary command language. This
469 form of @code{ar} operates interactively if standard input is coming
470 directly from a terminal. During interactive use, @code{ar} prompts for
471 input (the prompt is @samp{AR >}), and continues executing even after
472 errors. If you redirect standard input to a script file, no prompts are
473 issued, and @code{ar} abandons execution (with a nonzero exit code)
476 The @code{ar} command language is @emph{not} designed to be equivalent
477 to the command-line options; in fact, it provides somewhat less control
478 over archives. The only purpose of the command language is to ease the
479 transition to @sc{gnu} @code{ar} for developers who already have scripts
480 written for the MRI ``librarian'' program.
482 The syntax for the @code{ar} command language is straightforward:
485 commands are recognized in upper or lower case; for example, @code{LIST}
486 is the same as @code{list}. In the following descriptions, commands are
487 shown in upper case for clarity.
490 a single command may appear on each line; it is the first word on the
494 empty lines are allowed, and have no effect.
497 comments are allowed; text after either of the characters @samp{*}
498 or @samp{;} is ignored.
501 Whenever you use a list of names as part of the argument to an @code{ar}
502 command, you can separate the individual names with either commas or
503 blanks. Commas are shown in the explanations below, for clarity.
506 @samp{+} is used as a line continuation character; if @samp{+} appears
507 at the end of a line, the text on the following line is considered part
508 of the current command.
511 Here are the commands you can use in @code{ar} scripts, or when using
512 @code{ar} interactively. Three of them have special significance:
514 @code{OPEN} or @code{CREATE} specify a @dfn{current archive}, which is
515 a temporary file required for most of the other commands.
517 @code{SAVE} commits the changes so far specified by the script. Prior
518 to @code{SAVE}, commands affect only the temporary copy of the current
522 @item ADDLIB @var{archive}
523 @itemx ADDLIB @var{archive} (@var{module}, @var{module}, @dots{} @var{module})
524 Add all the contents of @var{archive} (or, if specified, each named
525 @var{module} from @var{archive}) to the current archive.
527 Requires prior use of @code{OPEN} or @code{CREATE}.
529 @item ADDMOD @var{member}, @var{member}, @dots{} @var{member}
530 @c FIXME! w/Replacement?? If so, like "ar r @var{archive} @var{names}"
531 @c else like "ar q..."
532 Add each named @var{member} as a module in the current archive.
534 Requires prior use of @code{OPEN} or @code{CREATE}.
537 Discard the contents of the current archive, canceling the effect of
538 any operations since the last @code{SAVE}. May be executed (with no
539 effect) even if no current archive is specified.
541 @item CREATE @var{archive}
542 Creates an archive, and makes it the current archive (required for many
543 other commands). The new archive is created with a temporary name; it
544 is not actually saved as @var{archive} until you use @code{SAVE}.
545 You can overwrite existing archives; similarly, the contents of any
546 existing file named @var{archive} will not be destroyed until @code{SAVE}.
548 @item DELETE @var{module}, @var{module}, @dots{} @var{module}
549 Delete each listed @var{module} from the current archive; equivalent to
550 @samp{ar -d @var{archive} @var{module} @dots{} @var{module}}.
552 Requires prior use of @code{OPEN} or @code{CREATE}.
554 @item DIRECTORY @var{archive} (@var{module}, @dots{} @var{module})
555 @itemx DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) @var{outputfile}
556 List each named @var{module} present in @var{archive}. The separate
557 command @code{VERBOSE} specifies the form of the output: when verbose
558 output is off, output is like that of @samp{ar -t @var{archive}
559 @var{module}@dots{}}. When verbose output is on, the listing is like
560 @samp{ar -tv @var{archive} @var{module}@dots{}}.
562 Output normally goes to the standard output stream; however, if you
563 specify @var{outputfile} as a final argument, @code{ar} directs the
567 Exit from @code{ar}, with a @code{0} exit code to indicate successful
568 completion. This command does not save the output file; if you have
569 changed the current archive since the last @code{SAVE} command, those
572 @item EXTRACT @var{module}, @var{module}, @dots{} @var{module}
573 Extract each named @var{module} from the current archive, writing them
574 into the current directory as separate files. Equivalent to @samp{ar -x
575 @var{archive} @var{module}@dots{}}.
577 Requires prior use of @code{OPEN} or @code{CREATE}.
580 @c FIXME Tokens but no commands???
587 Display full contents of the current archive, in ``verbose'' style
588 regardless of the state of @code{VERBOSE}. The effect is like @samp{ar
589 tv @var{archive}}. (This single command is a @sc{gnu} @code{ar}
590 enhancement, rather than present for MRI compatibility.)
592 Requires prior use of @code{OPEN} or @code{CREATE}.
594 @item OPEN @var{archive}
595 Opens an existing archive for use as the current archive (required for
596 many other commands). Any changes as the result of subsequent commands
597 will not actually affect @var{archive} until you next use @code{SAVE}.
599 @item REPLACE @var{module}, @var{module}, @dots{} @var{module}
600 In the current archive, replace each existing @var{module} (named in
601 the @code{REPLACE} arguments) from files in the current working directory.
602 To execute this command without errors, both the file, and the module in
603 the current archive, must exist.
605 Requires prior use of @code{OPEN} or @code{CREATE}.
608 Toggle an internal flag governing the output from @code{DIRECTORY}.
609 When the flag is on, @code{DIRECTORY} output matches output from
610 @samp{ar -tv }@dots{}.
613 Commit your changes to the current archive, and actually save it as a
614 file with the name specified in the last @code{CREATE} or @code{OPEN}
617 Requires prior use of @code{OPEN} or @code{CREATE}.
626 The @sc{gnu} linker @code{ld} is now described in a separate manual.
627 @xref{Top,, Overview,, Using LD: the @sc{gnu} linker}.
636 nm [ -a | --debug-syms ] [ -g | --extern-only ]
637 [ -B ] [ -C | --demangle[=@var{style}] ] [ -D | --dynamic ]
638 [ -s | --print-armap ] [ -A | -o | --print-file-name ]
639 [ -n | -v | --numeric-sort ] [ -p | --no-sort ]
640 [ -r | --reverse-sort ] [ --size-sort ] [ -u | --undefined-only ]
641 [ -t @var{radix} | --radix=@var{radix} ] [ -P | --portability ]
642 [ --target=@var{bfdname} ] [ -f @var{format} | --format=@var{format} ]
643 [ --defined-only ] [-l | --line-numbers ] [ --no-demangle ]
644 [ -V | --version ] [ -X 32_64 ] [ --help ] [ @var{objfile}@dots{} ]
647 @sc{gnu} @code{nm} lists the symbols from object files @var{objfile}@dots{}.
648 If no object files are listed as arguments, @code{nm} assumes the file
651 For each symbol, @code{nm} shows:
655 The symbol value, in the radix selected by options (see below), or
656 hexadecimal by default.
659 The symbol type. At least the following types are used; others are, as
660 well, depending on the object file format. If lowercase, the symbol is
661 local; if uppercase, the symbol is global (external).
663 @c Some more detail on exactly what these symbol types are used for
667 The symbol's value is absolute, and will not be changed by further
671 The symbol is in the uninitialized data section (known as BSS).
674 The symbol is common. Common symbols are uninitialized data. When
675 linking, multiple common symbols may appear with the same name. If the
676 symbol is defined anywhere, the common symbols are treated as undefined
677 references. For more details on common symbols, see the discussion of
678 --warn-common in @ref{Options,,Linker options,ld.info,The GNU linker}.
681 The symbol is in the initialized data section.
684 The symbol is in an initialized data section for small objects. Some
685 object file formats permit more efficient access to small data objects,
686 such as a global int variable as opposed to a large global array.
689 The symbol is an indirect reference to another symbol. This is a GNU
690 extension to the a.out object file format which is rarely used.
693 The symbol is a debugging symbol.
696 The symbol is in a read only data section.
699 The symbol is in an uninitialized data section for small objects.
702 The symbol is in the text (code) section.
705 The symbol is undefined.
708 The symbol is a weak object. When a weak defined symbol is linked with
709 a normal defined symbol, the normal defined symbol is used with no error.
710 When a weak undefined symbol is linked and the symbol is not defined,
711 the value of the weak symbol becomes zero with no error.
714 The symbol is a weak symbol that has not been specifically tagged as a
715 weak object symbol. When a weak defined symbol is linked with a normal
716 defined symbol, the normal defined symbol is used with no error.
717 When a weak undefined symbol is linked and the symbol is not defined,
718 the value of the weak symbol becomes zero with no error.
721 The symbol is a stabs symbol in an a.out object file. In this case, the
722 next values printed are the stabs other field, the stabs desc field, and
723 the stab type. Stabs symbols are used to hold debugging information;
724 for more information, see @ref{Top,Stabs,Stabs Overview,stabs.info, The
725 ``stabs'' debug format}.
728 The symbol type is unknown, or object file format specific.
735 The long and short forms of options, shown here as alternatives, are
741 @itemx --print-file-name
742 @cindex input file name
744 @cindex source file name
745 Precede each symbol by the name of the input file (or archive member)
746 in which it was found, rather than identifying the input file once only,
747 before all of its symbols.
751 @cindex debugging symbols
752 Display all symbols, even debugger-only symbols; normally these are not
756 @cindex @code{nm} format
757 @cindex @code{nm} compatibility
758 The same as @samp{--format=bsd} (for compatibility with the MIPS @code{nm}).
761 @itemx --demangle[=@var{style}]
762 @cindex demangling in nm
763 Decode (@dfn{demangle}) low-level symbol names into user-level names.
764 Besides removing any initial underscore prepended by the system, this
765 makes C++ function names readable. Different compilers have different
766 mangling styles. The optional demangling style argument can be used to
767 choose an appropriate demangling style for your compiler. @xref{c++filt},
768 for more information on demangling.
771 Do not demangle low-level symbol names. This is the default.
775 @cindex dynamic symbols
776 Display the dynamic symbols rather than the normal symbols. This is
777 only meaningful for dynamic objects, such as certain types of shared
780 @item -f @var{format}
781 @itemx --format=@var{format}
782 @cindex @code{nm} format
783 @cindex @code{nm} compatibility
784 Use the output format @var{format}, which can be @code{bsd},
785 @code{sysv}, or @code{posix}. The default is @code{bsd}.
786 Only the first character of @var{format} is significant; it can be
787 either upper or lower case.
791 @cindex external symbols
792 Display only external symbols.
795 @itemx --line-numbers
796 @cindex symbol line numbers
797 For each symbol, use debugging information to try to find a filename and
798 line number. For a defined symbol, look for the line number of the
799 address of the symbol. For an undefined symbol, look for the line
800 number of a relocation entry which refers to the symbol. If line number
801 information can be found, print it after the other symbol information.
805 @itemx --numeric-sort
806 Sort symbols numerically by their addresses, rather than alphabetically
811 @cindex sorting symbols
812 Do not bother to sort the symbols in any order; print them in the order
817 Use the POSIX.2 standard output format instead of the default format.
818 Equivalent to @samp{-f posix}.
822 @cindex symbol index, listing
823 When listing symbols from archive members, include the index: a mapping
824 (stored in the archive by @code{ar} or @code{ranlib}) of which modules
825 contain definitions for which names.
828 @itemx --reverse-sort
829 Reverse the order of the sort (whether numeric or alphabetic); let the
833 Sort symbols by size. The size is computed as the difference between
834 the value of the symbol and the value of the symbol with the next higher
835 value. The size of the symbol is printed, rather than the value.
838 @itemx --radix=@var{radix}
839 Use @var{radix} as the radix for printing the symbol values. It must be
840 @samp{d} for decimal, @samp{o} for octal, or @samp{x} for hexadecimal.
842 @item --target=@var{bfdname}
843 @cindex object code format
844 Specify an object code format other than your system's default format.
845 @xref{Target Selection}, for more information.
848 @itemx --undefined-only
849 @cindex external symbols
850 @cindex undefined symbols
851 Display only undefined symbols (those external to each object file).
854 @cindex external symbols
855 @cindex undefined symbols
856 Display only defined symbols for each object file.
860 Show the version number of @code{nm} and exit.
863 This option is ignored for compatibility with the AIX version of
864 @code{nm}. It takes one parameter which must be the string
865 @code{32_64}. The default mode of AIX @code{nm} corresponds
866 to @code{-X 32}, which is not supported by @sc{gnu} @code{nm}.
869 Show a summary of the options to @code{nm} and exit.
876 objcopy [ -F @var{bfdname} | --target=@var{bfdname} ]
877 [ -I @var{bfdname} | --input-target=@var{bfdname} ]
878 [ -O @var{bfdname} | --output-target=@var{bfdname} ]
879 [ -B @var{bfdarch} | --binary-architecture=@var{bfdarch} ]
880 [ -S | --strip-all ] [ -g | --strip-debug ]
881 [ -K @var{symbolname} | --keep-symbol=@var{symbolname} ]
882 [ -N @var{symbolname} | --strip-symbol=@var{symbolname} ]
883 [ -L @var{symbolname} | --localize-symbol=@var{symbolname} ]
884 [ -W @var{symbolname} | --weaken-symbol=@var{symbolname} ]
885 [ -x | --discard-all ] [ -X | --discard-locals ]
886 [ -b @var{byte} | --byte=@var{byte} ]
887 [ -i @var{interleave} | --interleave=@var{interleave} ]
888 [ -j @var{sectionname} | --only-section=@var{sectionname} ]
889 [ -R @var{sectionname} | --remove-section=@var{sectionname} ]
890 [ -p | --preserve-dates ] [ --debugging ]
891 [ --gap-fill=@var{val} ] [ --pad-to=@var{address} ]
892 [ --set-start=@var{val} ] [ --adjust-start=@var{incr} ]
893 [ --change-addresses=@var{incr} ]
894 [ --change-section-address @var{section}@{=,+,-@}@var{val} ]
895 [ --change-section-lma @var{section}@{=,+,-@}@var{val} ]
896 [ --change-section-vma @var{section}@{=,+,-@}@var{val} ]
897 [ --change-warnings ] [ --no-change-warnings ]
898 [ --set-section-flags @var{section}=@var{flags} ]
899 [ --add-section @var{sectionname}=@var{filename} ]
900 [ --change-leading-char ] [ --remove-leading-char ]
901 [ --srec-len=@var{ival} ] [ --srec-forceS3 ]
902 [ --redefine-sym @var{old}=@var{new} ] [ --weaken ]
903 [ -v | --verbose ] [ -V | --version ] [ --help ]
904 @var{infile} [@var{outfile}]
907 The @sc{gnu} @code{objcopy} utility copies the contents of an object
908 file to another. @code{objcopy} uses the @sc{gnu} @sc{bfd} Library to
909 read and write the object files. It can write the destination object
910 file in a format different from that of the source object file. The
911 exact behavior of @code{objcopy} is controlled by command-line options.
912 Note that @code{objcopy} should be able to copy a fully linked file
913 between any two formats. However, copying a relocatable object file
914 between any two formats may not work as expected.
916 @code{objcopy} creates temporary files to do its translations and
917 deletes them afterward. @code{objcopy} uses @sc{bfd} to do all its
918 translation work; it has access to all the formats described in @sc{bfd}
919 and thus is able to recognize most formats without being told
920 explicitly. @xref{BFD,,BFD,ld.info,Using LD}.
922 @code{objcopy} can be used to generate S-records by using an output
923 target of @samp{srec} (e.g., use @samp{-O srec}).
925 @code{objcopy} can be used to generate a raw binary file by using an
926 output target of @samp{binary} (e.g., use @samp{-O binary}). When
927 @code{objcopy} generates a raw binary file, it will essentially produce
928 a memory dump of the contents of the input object file. All symbols and
929 relocation information will be discarded. The memory dump will start at
930 the load address of the lowest section copied into the output file.
932 When generating an S-record or a raw binary file, it may be helpful to
933 use @samp{-S} to remove sections containing debugging information. In
934 some cases @samp{-R} will be useful to remove sections which contain
935 information that is not needed by the binary file.
937 Note - @code{objcopy} is not able to change the endianness of its input
938 files. If the input format has an endianness, (some formats do not),
939 @code{objcopy} can only copy the inputs into file formats that have the
940 same endianness or which have no endianness (eg @samp{srec}).
945 The input and output files, respectively.
946 If you do not specify @var{outfile}, @code{objcopy} creates a
947 temporary file and destructively renames the result with
948 the name of @var{infile}.
950 @item -I @var{bfdname}
951 @itemx --input-target=@var{bfdname}
952 Consider the source file's object format to be @var{bfdname}, rather than
953 attempting to deduce it. @xref{Target Selection}, for more information.
955 @item -O @var{bfdname}
956 @itemx --output-target=@var{bfdname}
957 Write the output file using the object format @var{bfdname}.
958 @xref{Target Selection}, for more information.
960 @item -F @var{bfdname}
961 @itemx --target=@var{bfdname}
962 Use @var{bfdname} as the object format for both the input and the output
963 file; i.e., simply transfer data from source to destination with no
964 translation. @xref{Target Selection}, for more information.
966 @item -B @var{bfdarch}
967 @itemx --binary-architecture=@var{bfdarch}
968 Useful when transforming a raw binary input file into an object file.
969 In this case the output architecture can be set to @var{bfdarch}. This
970 option will be ignored if the input file has a known @var{bfdarch}. You
971 can access this binary data inside a program by referencing the special
972 symbols that are created by the conversion process. These symbols are
973 called _binary_@var{objfile}_start, _binary_@var{objfile}_end and
974 _binary_@var{objfile}_size. e.g. you can transform a picture file into
975 an object file and then access it in your code using these symbols.
977 @item -j @var{sectionname}
978 @itemx --only-section=@var{sectionname}
979 Copy only the named section from the input file to the output file.
980 This option may be given more than once. Note that using this option
981 inappropriately may make the output file unusable.
983 @item -R @var{sectionname}
984 @itemx --remove-section=@var{sectionname}
985 Remove any section named @var{sectionname} from the output file. This
986 option may be given more than once. Note that using this option
987 inappropriately may make the output file unusable.
991 Do not copy relocation and symbol information from the source file.
995 Do not copy debugging symbols from the source file.
997 @item --strip-unneeded
998 Strip all symbols that are not needed for relocation processing.
1000 @item -K @var{symbolname}
1001 @itemx --keep-symbol=@var{symbolname}
1002 Copy only symbol @var{symbolname} from the source file. This option may
1003 be given more than once.
1005 @item -N @var{symbolname}
1006 @itemx --strip-symbol=@var{symbolname}
1007 Do not copy symbol @var{symbolname} from the source file. This option
1008 may be given more than once.
1010 @item -L @var{symbolname}
1011 @itemx --localize-symbol=@var{symbolname}
1012 Make symbol @var{symbolname} local to the file, so that it is not
1013 visible externally. This option may be given more than once.
1015 @item -W @var{symbolname}
1016 @itemx --weaken-symbol=@var{symbolname}
1017 Make symbol @var{symbolname} weak. This option may be given more than once.
1020 @itemx --discard-all
1021 Do not copy non-global symbols from the source file.
1022 @c FIXME any reason to prefer "non-global" to "local" here?
1025 @itemx --discard-locals
1026 Do not copy compiler-generated local symbols.
1027 (These usually start with @samp{L} or @samp{.}.)
1030 @itemx --byte=@var{byte}
1031 Keep only every @var{byte}th byte of the input file (header data is not
1032 affected). @var{byte} can be in the range from 0 to @var{interleave}-1,
1033 where @var{interleave} is given by the @samp{-i} or @samp{--interleave}
1034 option, or the default of 4. This option is useful for creating files
1035 to program @sc{rom}. It is typically used with an @code{srec} output
1038 @item -i @var{interleave}
1039 @itemx --interleave=@var{interleave}
1040 Only copy one out of every @var{interleave} bytes. Select which byte to
1041 copy with the @var{-b} or @samp{--byte} option. The default is 4.
1042 @code{objcopy} ignores this option if you do not specify either @samp{-b} or
1046 @itemx --preserve-dates
1047 Set the access and modification dates of the output file to be the same
1048 as those of the input file.
1051 Convert debugging information, if possible. This is not the default
1052 because only certain debugging formats are supported, and the
1053 conversion process can be time consuming.
1055 @item --gap-fill @var{val}
1056 Fill gaps between sections with @var{val}. This operation applies to
1057 the @emph{load address} (LMA) of the sections. It is done by increasing
1058 the size of the section with the lower address, and filling in the extra
1059 space created with @var{val}.
1061 @item --pad-to @var{address}
1062 Pad the output file up to the load address @var{address}. This is
1063 done by increasing the size of the last section. The extra space is
1064 filled in with the value specified by @samp{--gap-fill} (default zero).
1066 @item --set-start @var{val}
1067 Set the start address of the new file to @var{val}. Not all object file
1068 formats support setting the start address.
1070 @item --change-start @var{incr}
1071 @itemx --adjust-start @var{incr}
1072 @cindex changing start address
1073 Change the start address by adding @var{incr}. Not all object file
1074 formats support setting the start address.
1076 @item --change-addresses @var{incr}
1077 @itemx --adjust-vma @var{incr}
1078 @cindex changing object addresses
1079 Change the VMA and LMA addresses of all sections, as well as the start
1080 address, by adding @var{incr}. Some object file formats do not permit
1081 section addresses to be changed arbitrarily. Note that this does not
1082 relocate the sections; if the program expects sections to be loaded at a
1083 certain address, and this option is used to change the sections such
1084 that they are loaded at a different address, the program may fail.
1086 @item --change-section-address @var{section}@{=,+,-@}@var{val}
1087 @itemx --adjust-section-vma @var{section}@{=,+,-@}@var{val}
1088 @cindex changing section address
1089 Set or change both the VMA address and the LMA address of the named
1090 @var{section}. If @samp{=} is used, the section address is set to
1091 @var{val}. Otherwise, @var{val} is added to or subtracted from the
1092 section address. See the comments under @samp{--change-addresses},
1093 above. If @var{section} does not exist in the input file, a warning will
1094 be issued, unless @samp{--no-change-warnings} is used.
1096 @item --change-section-lma @var{section}@{=,+,-@}@var{val}
1097 @cindex changing section LMA
1098 Set or change the LMA address of the named @var{section}. The LMA
1099 address is the address where the section will be loaded into memory at
1100 program load time. Normally this is the same as the VMA address, which
1101 is the address of the section at program run time, but on some systems,
1102 especially those where a program is held in ROM, the two can be
1103 different. If @samp{=} is used, the section address is set to
1104 @var{val}. Otherwise, @var{val} is added to or subtracted from the
1105 section address. See the comments under @samp{--change-addresses},
1106 above. If @var{section} does not exist in the input file, a warning
1107 will be issued, unless @samp{--no-change-warnings} is used.
1109 @item --change-section-vma @var{section}@{=,+,-@}@var{val}
1110 @cindex changing section VMA
1111 Set or change the VMA address of the named @var{section}. The VMA
1112 address is the address where the section will be located once the
1113 program has started executing. Normally this is the same as the LMA
1114 address, which is the address where the section will be loaded into
1115 memory, but on some systems, especially those where a program is held in
1116 ROM, the two can be different. If @samp{=} is used, the section address
1117 is set to @var{val}. Otherwise, @var{val} is added to or subtracted
1118 from the section address. See the comments under
1119 @samp{--change-addresses}, above. If @var{section} does not exist in
1120 the input file, a warning will be issued, unless
1121 @samp{--no-change-warnings} is used.
1123 @item --change-warnings
1124 @itemx --adjust-warnings
1125 If @samp{--change-section-address} or @samp{--change-section-lma} or
1126 @samp{--change-section-vma} is used, and the named section does not
1127 exist, issue a warning. This is the default.
1129 @item --no-change-warnings
1130 @itemx --no-adjust-warnings
1131 Do not issue a warning if @samp{--change-section-address} or
1132 @samp{--adjust-section-lma} or @samp{--adjust-section-vma} is used, even
1133 if the named section does not exist.
1135 @item --set-section-flags @var{section}=@var{flags}
1136 Set the flags for the named section. The @var{flags} argument is a
1137 comma separated string of flag names. The recognized names are
1138 @samp{alloc}, @samp{contents}, @samp{load}, @samp{noload},
1139 @samp{readonly}, @samp{code}, @samp{data}, @samp{rom}, @samp{share}, and
1140 @samp{debug}. You can set the @samp{contents} flag for a section which
1141 does not have contents, but it is not meaningful to clear the
1142 @samp{contents} flag of a section which does have contents--just remove
1143 the section instead. Not all flags are meaningful for all object file
1146 @item --add-section @var{sectionname}=@var{filename}
1147 Add a new section named @var{sectionname} while copying the file. The
1148 contents of the new section are taken from the file @var{filename}. The
1149 size of the section will be the size of the file. This option only
1150 works on file formats which can support sections with arbitrary names.
1152 @item --change-leading-char
1153 Some object file formats use special characters at the start of
1154 symbols. The most common such character is underscore, which compilers
1155 often add before every symbol. This option tells @code{objcopy} to
1156 change the leading character of every symbol when it converts between
1157 object file formats. If the object file formats use the same leading
1158 character, this option has no effect. Otherwise, it will add a
1159 character, or remove a character, or change a character, as
1162 @item --remove-leading-char
1163 If the first character of a global symbol is a special symbol leading
1164 character used by the object file format, remove the character. The
1165 most common symbol leading character is underscore. This option will
1166 remove a leading underscore from all global symbols. This can be useful
1167 if you want to link together objects of different file formats with
1168 different conventions for symbol names. This is different from
1169 @code{--change-leading-char} because it always changes the symbol name
1170 when appropriate, regardless of the object file format of the output
1173 @item --srec-len=@var{ival}
1174 Meaningful only for srec output. Set the maximum length of the Srecords
1175 being produced to @var{ival}. This length covers both address, data and
1178 @item --srec-forceS3
1179 Meaningful only for srec output. Avoid generation of S1/S2 records,
1180 creating S3-only record format.
1182 @item --redefine-sym @var{old}=@var{new}
1183 Change the name of a symbol @var{old}, to @var{new}. This can be useful
1184 when one is trying link two things together for which you have no
1185 source, and there are name collisions.
1188 Change all global symbols in the file to be weak. This can be useful
1189 when building an object which will be linked against other objects using
1190 the @code{-R} option to the linker. This option is only effective when
1191 using an object file format which supports weak symbols.
1195 Show the version number of @code{objcopy}.
1199 Verbose output: list all object files modified. In the case of
1200 archives, @samp{objcopy -V} lists all members of the archive.
1203 Show a summary of the options to @code{objcopy}.
1209 @cindex object file information
1213 objdump [ -a | --archive-headers ]
1214 [ -b @var{bfdname} | --target=@var{bfdname} ]
1215 [ -C | --demangle[=@var{style}] ]
1216 [ -d | --disassemble ]
1217 [ -D | --disassemble-all ]
1218 [ -z | --disassemble-zeroes ]
1219 [ -EB | -EL | --endian=@{big | little @} ]
1220 [ -f | --file-headers ]
1221 [ --file-start-context ]
1222 [ -g | --debugging ]
1223 [ -h | --section-headers | --headers ]
1225 [ -j @var{section} | --section=@var{section} ]
1226 [ -l | --line-numbers ]
1228 [ -m @var{machine} | --architecture=@var{machine} ]
1229 [ -M @var{options} | --disassembler-options=@var{options}]
1230 [ -p | --private-headers ]
1232 [ -R | --dynamic-reloc ]
1233 [ -s | --full-contents ]
1236 [ -T | --dynamic-syms ]
1237 [ -x | --all-headers ]
1239 [ --start-address=@var{address} ]
1240 [ --stop-address=@var{address} ]
1241 [ --prefix-addresses]
1242 [ --[no-]show-raw-insn ]
1243 [ --adjust-vma=@var{offset} ]
1246 @var{objfile}@dots{}
1249 @code{objdump} displays information about one or more object files.
1250 The options control what particular information to display. This
1251 information is mostly useful to programmers who are working on the
1252 compilation tools, as opposed to programmers who just want their
1253 program to compile and work.
1255 @var{objfile}@dots{} are the object files to be examined. When you
1256 specify archives, @code{objdump} shows information on each of the member
1259 The long and short forms of options, shown here as alternatives, are
1260 equivalent. At least one option from the list
1261 @samp{-a,-d,-D,-f,-g,-G,-h,-H,-p,-r,-R,-S,-t,-T,-V,-x} must be given.
1265 @itemx --archive-header
1266 @cindex archive headers
1267 If any of the @var{objfile} files are archives, display the archive
1268 header information (in a format similar to @samp{ls -l}). Besides the
1269 information you could list with @samp{ar tv}, @samp{objdump -a} shows
1270 the object file format of each archive member.
1272 @item --adjust-vma=@var{offset}
1273 @cindex section addresses in objdump
1274 @cindex VMA in objdump
1275 When dumping information, first add @var{offset} to all the section
1276 addresses. This is useful if the section addresses do not correspond to
1277 the symbol table, which can happen when putting sections at particular
1278 addresses when using a format which can not represent section addresses,
1281 @item -b @var{bfdname}
1282 @itemx --target=@var{bfdname}
1283 @cindex object code format
1284 Specify that the object-code format for the object files is
1285 @var{bfdname}. This option may not be necessary; @var{objdump} can
1286 automatically recognize many formats.
1290 objdump -b oasys -m vax -h fu.o
1293 displays summary information from the section headers (@samp{-h}) of
1294 @file{fu.o}, which is explicitly identified (@samp{-m}) as a VAX object
1295 file in the format produced by Oasys compilers. You can list the
1296 formats available with the @samp{-i} option.
1297 @xref{Target Selection}, for more information.
1300 @itemx --demangle[=@var{style}]
1301 @cindex demangling in objdump
1302 Decode (@dfn{demangle}) low-level symbol names into user-level names.
1303 Besides removing any initial underscore prepended by the system, this
1304 makes C++ function names readable. Different compilers have different
1305 mangling styles. The optional demangling style argument can be used to
1306 choose an appropriate demangling style for your compiler. @xref{c++filt},
1307 for more information on demangling.
1311 Display debugging information. This attempts to parse debugging
1312 information stored in the file and print it out using a C like syntax.
1313 Only certain types of debugging information have been implemented.
1316 @itemx --disassemble
1317 @cindex disassembling object code
1318 @cindex machine instructions
1319 Display the assembler mnemonics for the machine instructions from
1320 @var{objfile}. This option only disassembles those sections which are
1321 expected to contain instructions.
1324 @itemx --disassemble-all
1325 Like @samp{-d}, but disassemble the contents of all sections, not just
1326 those expected to contain instructions.
1328 @item --prefix-addresses
1329 When disassembling, print the complete address on each line. This is
1330 the older disassembly format.
1332 @item --disassemble-zeroes
1333 Normally the disassembly output will skip blocks of zeroes. This
1334 option directs the disassembler to disassemble those blocks, just like
1339 @itemx --endian=@{big|little@}
1341 @cindex disassembly endianness
1342 Specify the endianness of the object files. This only affects
1343 disassembly. This can be useful when disassembling a file format which
1344 does not describe endianness information, such as S-records.
1347 @itemx --file-header
1348 @cindex object file header
1349 Display summary information from the overall header of
1350 each of the @var{objfile} files.
1352 @item --file-start-context
1353 @cindex source code context
1354 Specify that when displaying interlisted source code/disassembly
1355 (assumes '-S') from a file that has not yet been displayed, extend the
1356 context to the start of the file.
1359 @itemx --section-header
1361 @cindex section headers
1362 Display summary information from the section headers of the
1365 File segments may be relocated to nonstandard addresses, for example by
1366 using the @samp{-Ttext}, @samp{-Tdata}, or @samp{-Tbss} options to
1367 @code{ld}. However, some object file formats, such as a.out, do not
1368 store the starting address of the file segments. In those situations,
1369 although @code{ld} relocates the sections correctly, using @samp{objdump
1370 -h} to list the file section headers cannot show the correct addresses.
1371 Instead, it shows the usual addresses, which are implicit for the
1375 Print a summary of the options to @code{objdump} and exit.
1379 @cindex architectures available
1380 @cindex object formats available
1381 Display a list showing all architectures and object formats available
1382 for specification with @samp{-b} or @samp{-m}.
1385 @itemx --section=@var{name}
1386 @cindex section information
1387 Display information only for section @var{name}.
1390 @itemx --line-numbers
1391 @cindex source filenames for object files
1392 Label the display (using debugging information) with the filename and
1393 source line numbers corresponding to the object code or relocs shown.
1394 Only useful with @samp{-d}, @samp{-D}, or @samp{-r}.
1396 @item -m @var{machine}
1397 @itemx --architecture=@var{machine}
1398 @cindex architecture
1399 @cindex disassembly architecture
1400 Specify the architecture to use when disassembling object files. This
1401 can be useful when disassembling object files which do not describe
1402 architecture information, such as S-records. You can list the available
1403 architectures with the @samp{-i} option.
1405 @item -M @var{options}
1406 @itemx --disassembler-options=@var{options}
1407 Pass target specific information to the disassembler. Only supported on
1410 If the target is an ARM architecture then this switch can be used to
1411 select which register name set is used during disassembler. Specifying
1412 @samp{-M reg-name-std} (the default) will select the register names as
1413 used in ARM's instruction set documentation, but with register 13 called
1414 'sp', register 14 called 'lr' and register 15 called 'pc'. Specifying
1415 @samp{-M reg-names-apcs} will select the name set used by the ARM
1416 Procedure Call Standard, whilst specifying @samp{-M reg-names-raw} will
1417 just use @samp{r} followed by the register number.
1419 There are also two variants on the APCS register naming scheme enabled
1420 by @samp{-M reg-names-atpcs} and @samp{-M reg-names-special-atpcs} which
1421 use the ARM/Thumb Procedure Call Standard naming conventions. (Eiuther
1422 with the normal register name sor the special register names).
1424 This option can also be used for ARM architectures to force the
1425 disassembler to interpret all instructions as THUMB instructions by
1426 using the switch @samp{--disassembler-options=force-thumb}. This can be
1427 useful when attempting to disassemble thumb code produced by other
1431 @itemx --private-headers
1432 Print information that is specific to the object file format. The exact
1433 information printed depends upon the object file format. For some
1434 object file formats, no additional information is printed.
1438 @cindex relocation entries, in object file
1439 Print the relocation entries of the file. If used with @samp{-d} or
1440 @samp{-D}, the relocations are printed interspersed with the
1444 @itemx --dynamic-reloc
1445 @cindex dynamic relocation entries, in object file
1446 Print the dynamic relocation entries of the file. This is only
1447 meaningful for dynamic objects, such as certain types of shared
1451 @itemx --full-contents
1452 @cindex sections, full contents
1453 @cindex object file sections
1454 Display the full contents of any sections requested.
1458 @cindex source disassembly
1459 @cindex disassembly, with source
1460 Display source code intermixed with disassembly, if possible. Implies
1463 @item --show-raw-insn
1464 When disassembling instructions, print the instruction in hex as well as
1465 in symbolic form. This is the default except when
1466 @code{--prefix-addresses} is used.
1468 @item --no-show-raw-insn
1469 When disassembling instructions, do not print the instruction bytes.
1470 This is the default when @code{--prefix-addresses} is used.
1476 @cindex debug symbols
1477 @cindex ELF object file format
1478 Display the full contents of any sections requested. Display the
1479 contents of the .stab and .stab.index and .stab.excl sections from an
1480 ELF file. This is only useful on systems (such as Solaris 2.0) in which
1481 @code{.stab} debugging symbol-table entries are carried in an ELF
1482 section. In most other file formats, debugging symbol-table entries are
1483 interleaved with linkage symbols, and are visible in the @samp{--syms}
1484 output. For more information on stabs symbols, see @ref{Top,Stabs,Stabs
1485 Overview,stabs.info, The ``stabs'' debug format}.
1487 @item --start-address=@var{address}
1488 @cindex start-address
1489 Start displaying data at the specified address. This affects the output
1490 of the @code{-d}, @code{-r} and @code{-s} options.
1492 @item --stop-address=@var{address}
1493 @cindex stop-address
1494 Stop displaying data at the specified address. This affects the output
1495 of the @code{-d}, @code{-r} and @code{-s} options.
1499 @cindex symbol table entries, printing
1500 Print the symbol table entries of the file.
1501 This is similar to the information provided by the @samp{nm} program.
1504 @itemx --dynamic-syms
1505 @cindex dynamic symbol table entries, printing
1506 Print the dynamic symbol table entries of the file. This is only
1507 meaningful for dynamic objects, such as certain types of shared
1508 libraries. This is similar to the information provided by the @samp{nm}
1509 program when given the @samp{-D} (@samp{--dynamic}) option.
1512 Print the version number of @code{objdump} and exit.
1516 @cindex all header information, object file
1517 @cindex header information, all
1518 Display all available header information, including the symbol table and
1519 relocation entries. Using @samp{-x} is equivalent to specifying all of
1520 @samp{-a -f -h -r -t}.
1524 @cindex wide output, printing
1525 Format some lines for output devices that have more than 80 columns.
1532 @cindex archive contents
1533 @cindex symbol index
1536 ranlib [-vV] @var{archive}
1539 @code{ranlib} generates an index to the contents of an archive and
1540 stores it in the archive. The index lists each symbol defined by a
1541 member of an archive that is a relocatable object file.
1543 You may use @samp{nm -s} or @samp{nm --print-armap} to list this index.
1545 An archive with such an index speeds up linking to the library and
1546 allows routines in the library to call each other without regard to
1547 their placement in the archive.
1549 The @sc{gnu} @code{ranlib} program is another form of @sc{gnu} @code{ar}; running
1550 @code{ranlib} is completely equivalent to executing @samp{ar -s}.
1557 Show the version number of @code{ranlib}.
1564 @cindex section sizes
1567 size [ -A | -B | --format=@var{compatibility} ]
1568 [ --help ] [ -d | -o | -x | --radix=@var{number} ]
1569 [ --target=@var{bfdname} ] [ -V | --version ]
1570 [ @var{objfile}@dots{} ]
1573 The @sc{gnu} @code{size} utility lists the section sizes---and the total
1574 size---for each of the object or archive files @var{objfile} in its
1575 argument list. By default, one line of output is generated for each
1576 object file or each module in an archive.
1578 @var{objfile}@dots{} are the object files to be examined.
1579 If none are specified, the file @code{a.out} will be used.
1581 The command line options have the following meanings:
1586 @itemx --format=@var{compatibility}
1587 @cindex @code{size} display format
1588 Using one of these options, you can choose whether the output from @sc{gnu}
1589 @code{size} resembles output from System V @code{size} (using @samp{-A},
1590 or @samp{--format=sysv}), or Berkeley @code{size} (using @samp{-B}, or
1591 @samp{--format=berkeley}). The default is the one-line format similar to
1593 @c Bonus for doc-source readers: you can also say --format=strange (or
1594 @c anything else that starts with 's') for sysv, and --format=boring (or
1595 @c anything else that starts with 'b') for Berkeley.
1597 Here is an example of the Berkeley (default) format of output from
1600 $ size --format=Berkeley ranlib size
1601 text data bss dec hex filename
1602 294880 81920 11592 388392 5ed28 ranlib
1603 294880 81920 11888 388688 5ee50 size
1607 This is the same data, but displayed closer to System V conventions:
1610 $ size --format=SysV ranlib size
1628 Show a summary of acceptable arguments and options.
1633 @itemx --radix=@var{number}
1634 @cindex @code{size} number format
1635 @cindex radix for section sizes
1636 Using one of these options, you can control whether the size of each
1637 section is given in decimal (@samp{-d}, or @samp{--radix=10}); octal
1638 (@samp{-o}, or @samp{--radix=8}); or hexadecimal (@samp{-x}, or
1639 @samp{--radix=16}). In @samp{--radix=@var{number}}, only the three
1640 values (8, 10, 16) are supported. The total size is always given in two
1641 radices; decimal and hexadecimal for @samp{-d} or @samp{-x} output, or
1642 octal and hexadecimal if you're using @samp{-o}.
1644 @item --target=@var{bfdname}
1645 @cindex object code format
1646 Specify that the object-code format for @var{objfile} is
1647 @var{bfdname}. This option may not be necessary; @code{size} can
1648 automatically recognize many formats.
1649 @xref{Target Selection}, for more information.
1653 Display the version number of @code{size}.
1659 @cindex listings strings
1660 @cindex printing strings
1661 @cindex strings, printing
1664 strings [-afov] [-@var{min-len}] [-n @var{min-len}] [-t @var{radix}] [-]
1665 [--all] [--print-file-name] [--bytes=@var{min-len}]
1666 [--radix=@var{radix}] [--target=@var{bfdname}]
1667 [--help] [--version] @var{file}@dots{}
1670 For each @var{file} given, @sc{gnu} @code{strings} prints the printable
1671 character sequences that are at least 4 characters long (or the number
1672 given with the options below) and are followed by an unprintable
1673 character. By default, it only prints the strings from the initialized
1674 and loaded sections of object files; for other types of files, it prints
1675 the strings from the whole file.
1677 @code{strings} is mainly useful for determining the contents of non-text
1684 Do not scan only the initialized and loaded sections of object files;
1685 scan the whole files.
1688 @itemx --print-file-name
1689 Print the name of the file before each string.
1692 Print a summary of the program usage on the standard output and exit.
1694 @item -@var{min-len}
1695 @itemx -n @var{min-len}
1696 @itemx --bytes=@var{min-len}
1697 Print sequences of characters that are at least @var{min-len} characters
1698 long, instead of the default 4.
1701 Like @samp{-t o}. Some other versions of @code{strings} have @samp{-o}
1702 act like @samp{-t d} instead. Since we can not be compatible with both
1703 ways, we simply chose one.
1705 @item -t @var{radix}
1706 @itemx --radix=@var{radix}
1707 Print the offset within the file before each string. The single
1708 character argument specifies the radix of the offset---@samp{o} for
1709 octal, @samp{x} for hexadecimal, or @samp{d} for decimal.
1711 @item --target=@var{bfdname}
1712 @cindex object code format
1713 Specify an object code format other than your system's default format.
1714 @xref{Target Selection}, for more information.
1718 Print the program version number on the standard output and exit.
1725 @cindex removing symbols
1726 @cindex discarding symbols
1727 @cindex symbols, discarding
1730 strip [ -F @var{bfdname} | --target=@var{bfdname} ]
1731 [ -I @var{bfdname} | --input-target=@var{bfdname} ]
1732 [ -O @var{bfdname} | --output-target=@var{bfdname} ]
1733 [ -s | --strip-all ] [ -S | -g | --strip-debug ]
1734 [ -K @var{symbolname} | --keep-symbol=@var{symbolname} ]
1735 [ -N @var{symbolname} | --strip-symbol=@var{symbolname} ]
1736 [ -x | --discard-all ] [ -X | --discard-locals ]
1737 [ -R @var{sectionname} | --remove-section=@var{sectionname} ]
1738 [ -o @var{file} ] [ -p | --preserve-dates ]
1739 [ -v | --verbose ] [ -V | --version ] [ --help ]
1740 @var{objfile}@dots{}
1743 @sc{gnu} @code{strip} discards all symbols from object files
1744 @var{objfile}. The list of object files may include archives.
1745 At least one object file must be given.
1747 @code{strip} modifies the files named in its argument,
1748 rather than writing modified copies under different names.
1751 @item -F @var{bfdname}
1752 @itemx --target=@var{bfdname}
1753 Treat the original @var{objfile} as a file with the object
1754 code format @var{bfdname}, and rewrite it in the same format.
1755 @xref{Target Selection}, for more information.
1758 Show a summary of the options to @code{strip} and exit.
1760 @item -I @var{bfdname}
1761 @itemx --input-target=@var{bfdname}
1762 Treat the original @var{objfile} as a file with the object
1763 code format @var{bfdname}.
1764 @xref{Target Selection}, for more information.
1766 @item -O @var{bfdname}
1767 @itemx --output-target=@var{bfdname}
1768 Replace @var{objfile} with a file in the output format @var{bfdname}.
1769 @xref{Target Selection}, for more information.
1771 @item -R @var{sectionname}
1772 @itemx --remove-section=@var{sectionname}
1773 Remove any section named @var{sectionname} from the output file. This
1774 option may be given more than once. Note that using this option
1775 inappropriately may make the output file unusable.
1783 @itemx --strip-debug
1784 Remove debugging symbols only.
1786 @item --strip-unneeded
1787 Remove all symbols that are not needed for relocation processing.
1789 @item -K @var{symbolname}
1790 @itemx --keep-symbol=@var{symbolname}
1791 Keep only symbol @var{symbolname} from the source file. This option may
1792 be given more than once.
1794 @item -N @var{symbolname}
1795 @itemx --strip-symbol=@var{symbolname}
1796 Remove symbol @var{symbolname} from the source file. This option may be
1797 given more than once, and may be combined with strip options other than
1801 Put the stripped output in @var{file}, rather than replacing the
1802 existing file. When this argument is used, only one @var{objfile}
1803 argument may be specified.
1806 @itemx --preserve-dates
1807 Preserve the access and modification dates of the file.
1810 @itemx --discard-all
1811 Remove non-global symbols.
1814 @itemx --discard-locals
1815 Remove compiler-generated local symbols.
1816 (These usually start with @samp{L} or @samp{.}.)
1820 Show the version number for @code{strip}.
1824 Verbose output: list all object files modified. In the case of
1825 archives, @samp{strip -v} lists all members of the archive.
1828 @node c++filt, addr2line, strip, Top
1832 @cindex demangling C++ symbols
1835 c++filt [ -_ | --strip-underscores ]
1837 [ -n | --no-strip-underscores ]
1838 [ -s @var{format} | --format=@var{format} ]
1839 [ --help ] [ --version ] [ @var{symbol}@dots{} ]
1843 The C++ and Java languages provides function overloading, which means
1844 that you can write many functions with the same name (providing each
1845 takes parameters of different types). All C++ and Java function names
1846 are encoded into a low-level assembly label (this process is known as
1847 @dfn{mangling}). The @code{c++filt}
1848 @footnote{MS-DOS does not allow @kbd{+} characters in file names, so on
1849 MS-DOS this program is named @code{cxxfilt}.}
1850 program does the inverse mapping: it decodes (@dfn{demangles}) low-level
1851 names into user-level names so that the linker can keep these overloaded
1852 functions from clashing.
1854 Every alphanumeric word (consisting of letters, digits, underscores,
1855 dollars, or periods) seen in the input is a potential label. If the
1856 label decodes into a C++ name, the C++ name replaces the low-level
1859 You can use @code{c++filt} to decipher individual symbols:
1862 c++filt @var{symbol}
1865 If no @var{symbol} arguments are given, @code{c++filt} reads symbol
1866 names from the standard input and writes the demangled names to the
1867 standard output. All results are printed on the standard output.
1871 @itemx --strip-underscores
1872 On some systems, both the C and C++ compilers put an underscore in front
1873 of every name. For example, the C name @code{foo} gets the low-level
1874 name @code{_foo}. This option removes the initial underscore. Whether
1875 @code{c++filt} removes the underscore by default is target dependent.
1879 Prints demangled names using Java syntax. The default is to use C++
1883 @itemx --no-strip-underscores
1884 Do not remove the initial underscore.
1886 @item -s @var{format}
1887 @itemx --format=@var{format}
1888 @sc{gnu} @code{nm} can decode three different methods of mangling, used by
1889 different C++ compilers. The argument to this option selects which
1894 the one used by the @sc{gnu} compiler (the default method)
1896 the one used by the Lucid compiler
1898 the one specified by the C++ Annotated Reference Manual
1900 the one used by the HP compiler
1902 the one used by the EDG compiler
1904 the one used by the @sc{gnu} compiler with the new ABI.
1908 Print a summary of the options to @code{c++filt} and exit.
1911 Print the version number of @code{c++filt} and exit.
1915 @emph{Warning:} @code{c++filt} is a new utility, and the details of its
1916 user interface are subject to change in future releases. In particular,
1917 a command-line option may be required in the the future to decode a name
1918 passed as an argument on the command line; in other words,
1921 c++filt @var{symbol}
1925 may in a future release become
1928 c++filt @var{option} @var{symbol}
1936 @cindex address to file name and line number
1939 addr2line [ -b @var{bfdname} | --target=@var{bfdname} ]
1940 [ -C | --demangle[=@var{style} ]
1941 [ -e @var{filename} | --exe=@var{filename} ]
1942 [ -f | --functions ] [ -s | --basename ]
1943 [ -H | --help ] [ -V | --version ]
1947 @code{addr2line} translates program addresses into file names and line
1948 numbers. Given an address and an executable, it uses the debugging
1949 information in the executable to figure out which file name and line
1950 number are associated with a given address.
1952 The executable to use is specified with the @code{-e} option. The
1953 default is the file @file{a.out}.
1955 @code{addr2line} has two modes of operation.
1957 In the first, hexadecimal addresses are specified on the command line,
1958 and @code{addr2line} displays the file name and line number for each
1961 In the second, @code{addr2line} reads hexadecimal addresses from
1962 standard input, and prints the file name and line number for each
1963 address on standard output. In this mode, @code{addr2line} may be used
1964 in a pipe to convert dynamically chosen addresses.
1966 The format of the output is @samp{FILENAME:LINENO}. The file name and
1967 line number for each address is printed on a separate line. If the
1968 @code{-f} option is used, then each @samp{FILENAME:LINENO} line is
1969 preceded by a @samp{FUNCTIONNAME} line which is the name of the function
1970 containing the address.
1972 If the file name or function name can not be determined,
1973 @code{addr2line} will print two question marks in their place. If the
1974 line number can not be determined, @code{addr2line} will print 0.
1976 The long and short forms of options, shown here as alternatives, are
1980 @item -b @var{bfdname}
1981 @itemx --target=@var{bfdname}
1982 @cindex object code format
1983 Specify that the object-code format for the object files is
1987 @itemx --demangle[=@var{style}]
1988 @cindex demangling in objdump
1989 Decode (@dfn{demangle}) low-level symbol names into user-level names.
1990 Besides removing any initial underscore prepended by the system, this
1991 makes C++ function names readable. Different compilers have different
1992 mangling styles. The optional demangling style argument can be used to
1993 choose an appropriate demangling style for your compiler. @xref{c++filt},
1994 for more information on demangling.
1996 @item -e @var{filename}
1997 @itemx --exe=@var{filename}
1998 Specify the name of the executable for which addresses should be
1999 translated. The default file is @file{a.out}.
2003 Display function names as well as file and line number information.
2007 Display only the base of each file name.
2013 @code{nlmconv} converts a relocatable object file into a NetWare
2017 @code{nlmconv} currently works with @samp{i386} object
2018 files in @code{coff}, @sc{elf}, or @code{a.out} format, and @sc{SPARC}
2019 object files in @sc{elf}, or @code{a.out} format@footnote{
2020 @code{nlmconv} should work with any @samp{i386} or @sc{sparc} object
2021 format in the Binary File Descriptor library. It has only been tested
2022 with the above formats.}.
2026 @emph{Warning:} @code{nlmconv} is not always built as part of the binary
2027 utilities, since it is only useful for NLM targets.
2031 nlmconv [ -I @var{bfdname} | --input-target=@var{bfdname} ]
2032 [ -O @var{bfdname} | --output-target=@var{bfdname} ]
2033 [ -T @var{headerfile} | --header-file=@var{headerfile} ]
2034 [ -d | --debug] [ -l @var{linker} | --linker=@var{linker} ]
2035 [ -h | --help ] [ -V | --version ]
2036 @var{infile} @var{outfile}
2039 @code{nlmconv} converts the relocatable @samp{i386} object file
2040 @var{infile} into the NetWare Loadable Module @var{outfile}, optionally
2041 reading @var{headerfile} for NLM header information. For instructions
2042 on writing the NLM command file language used in header files, see the
2043 @samp{linkers} section, @samp{NLMLINK} in particular, of the @cite{NLM
2044 Development and Tools Overview}, which is part of the NLM Software
2045 Developer's Kit (``NLM SDK''), available from Novell, Inc.
2046 @code{nlmconv} uses the @sc{gnu} Binary File Descriptor library to read
2047 @var{infile}; see @ref{BFD,,BFD,ld.info,Using LD}, for
2050 @code{nlmconv} can perform a link step. In other words, you can list
2051 more than one object file for input if you list them in the definitions
2052 file (rather than simply specifying one input file on the command line).
2053 In this case, @code{nlmconv} calls the linker for you.
2056 @item -I @var{bfdname}
2057 @itemx --input-target=@var{bfdname}
2058 Object format of the input file. @code{nlmconv} can usually determine
2059 the format of a given file (so no default is necessary).
2060 @xref{Target Selection}, for more information.
2062 @item -O @var{bfdname}
2063 @itemx --output-target=@var{bfdname}
2064 Object format of the output file. @code{nlmconv} infers the output
2065 format based on the input format, e.g. for a @samp{i386} input file the
2066 output format is @samp{nlm32-i386}.
2067 @xref{Target Selection}, for more information.
2069 @item -T @var{headerfile}
2070 @itemx --header-file=@var{headerfile}
2071 Reads @var{headerfile} for NLM header information. For instructions on
2072 writing the NLM command file language used in header files, see@ see the
2073 @samp{linkers} section, of the @cite{NLM Development and Tools
2074 Overview}, which is part of the NLM Software Developer's Kit, available
2079 Displays (on standard error) the linker command line used by @code{nlmconv}.
2081 @item -l @var{linker}
2082 @itemx --linker=@var{linker}
2083 Use @var{linker} for any linking. @var{linker} can be an absolute or a
2088 Prints a usage summary.
2092 Prints the version number for @code{nlmconv}.
2098 @code{windres} may be used to manipulate Windows resources.
2101 @emph{Warning:} @code{windres} is not always built as part of the binary
2102 utilities, since it is only useful for Windows targets.
2106 windres [options] [input-file] [output-file]
2109 @code{windres} reads resources from an input file and copies them into
2110 an output file. Either file may be in one of three formats:
2114 A text format read by the Resource Compiler.
2117 A binary format generated by the Resource Compiler.
2120 A COFF object or executable.
2123 The exact description of these different formats is available in
2124 documentation from Microsoft.
2126 When @code{windres} converts from the @code{rc} format to the @code{res}
2127 format, it is acting like the Windows Resource Compiler. When
2128 @code{windres} converts from the @code{res} format to the @code{coff}
2129 format, it is acting like the Windows @code{CVTRES} program.
2131 When @code{windres} generates an @code{rc} file, the output is similar
2132 but not identical to the format expected for the input. When an input
2133 @code{rc} file refers to an external filename, an output @code{rc} file
2134 will instead include the file contents.
2136 If the input or output format is not specified, @code{windres} will
2137 guess based on the file name, or, for the input file, the file contents.
2138 A file with an extension of @file{.rc} will be treated as an @code{rc}
2139 file, a file with an extension of @file{.res} will be treated as a
2140 @code{res} file, and a file with an extension of @file{.o} or
2141 @file{.exe} will be treated as a @code{coff} file.
2143 If no output file is specified, @code{windres} will print the resources
2144 in @code{rc} format to standard output.
2146 The normal use is for you to write an @code{rc} file, use @code{windres}
2147 to convert it to a COFF object file, and then link the COFF file into
2148 your application. This will make the resources described in the
2149 @code{rc} file available to Windows.
2152 @item -i @var{filename}
2153 @itemx --input @var{filename}
2154 The name of the input file. If this option is not used, then
2155 @code{windres} will use the first non-option argument as the input file
2156 name. If there are no non-option arguments, then @code{windres} will
2157 read from standard input. @code{windres} can not read a COFF file from
2160 @item -o @var{filename}
2161 @itemx --output @var{filename}
2162 The name of the output file. If this option is not used, then
2163 @code{windres} will use the first non-option argument, after any used
2164 for the input file name, as the output file name. If there is no
2165 non-option argument, then @code{windres} will write to standard output.
2166 @code{windres} can not write a COFF file to standard output.
2168 @item -I @var{format}
2169 @itemx --input-format @var{format}
2170 The input format to read. @var{format} may be @samp{res}, @samp{rc}, or
2171 @samp{coff}. If no input format is specified, @code{windres} will
2172 guess, as described above.
2174 @item -O @var{format}
2175 @itemx --output-format @var{format}
2176 The output format to generate. @var{format} may be @samp{res},
2177 @samp{rc}, or @samp{coff}. If no output format is specified,
2178 @code{windres} will guess, as described above.
2180 @item -F @var{target}
2181 @itemx --target @var{target}
2182 Specify the BFD format to use for a COFF file as input or output. This
2183 is a BFD target name; you can use the @code{--help} option to see a list
2184 of supported targets. Normally @code{windres} will use the default
2185 format, which is the first one listed by the @code{--help} option.
2186 @ref{Target Selection}.
2188 @item --preprocessor @var{program}
2189 When @code{windres} reads an @code{rc} file, it runs it through the C
2190 preprocessor first. This option may be used to specify the preprocessor
2191 to use, including any leading arguments. The default preprocessor
2192 argument is @code{gcc -E -xc-header -DRC_INVOKED}.
2194 @item --include-dir @var{directory}
2195 Specify an include directory to use when reading an @code{rc} file.
2196 @code{windres} will pass this to the preprocessor as an @code{-I}
2197 option. @code{windres} will also search this directory when looking for
2198 files named in the @code{rc} file.
2200 @item -D @var{target}
2201 @itemx --define @var{sym}[=@var{val}]
2202 Specify a @code{-D} option to pass to the preprocessor when reading an
2206 Enable verbose mode. This tells you what the preprocessor is if you
2209 @item --language @var{val}
2210 Specify the default language to use when reading an @code{rc} file.
2211 @var{val} should be a hexadecimal language code. The low eight bits are
2212 the language, and the high eight bits are the sublanguage.
2214 @item --use-temp-file
2215 Use a temporary file to instead of using popen to read the output of
2216 the preprocessor. Use this option if the popen implementation is buggy
2217 on the host (eg., certain non-English language versions of Windows 95 and
2218 Windows 98 are known to have buggy popen where the output will instead
2221 @item --no-use-temp-file
2222 Use popen, not a temporary file, to read the output of the preprocessor.
2223 This is the default behaviour.
2226 Prints a usage summary.
2229 Prints the version number for @code{windres}.
2232 If @code{windres} is compiled with @code{YYDEBUG} defined as @code{1},
2233 this will turn on parser debugging.
2238 @chapter Create files needed to build and use DLLs
2242 @code{dlltool} may be used to create the files needed to build and use
2243 dynamic link libraries (DLLs).
2246 @emph{Warning:} @code{dlltool} is not always built as part of the binary
2247 utilities, since it is only useful for those targets which support DLLs.
2251 dlltool [-d|--input-def @var{def-file-name}]
2252 [-b|--base-file @var{base-file-name}]
2253 [-e|--output-exp @var{exports-file-name}]
2254 [-z|--output-def @var{def-file-name}]
2255 [-l|--output-lib @var{library-file-name}]
2256 [--export-all-symbols] [--no-export-all-symbols]
2257 [--exclude-symbols @var{list}]
2258 [--no-default-excludes]
2259 [-S|--as @var{path-to-assembler}] [-f|--as-flags @var{options}]
2260 [-D|--dllname @var{name}] [-m|--machine @var{machine}]
2261 [-a|--add-indirect] [-U|--add-underscore] [-k|--kill-at]
2262 [-A|--add-stdcall-alias]
2263 [-x|--no-idata4] [-c|--no-idata5] [-i|--interwork]
2264 [-n|--nodelete] [-v|--verbose] [-h|--help] [-V|--version]
2265 [object-file @dots{}]
2268 @code{dlltool} reads its inputs, which can come from the @samp{-d} and
2269 @samp{-b} options as well as object files specified on the command
2270 line. It then processes these inputs and if the @samp{-e} option has
2271 been specified it creates a exports file. If the @samp{-l} option
2272 has been specified it creates a library file and if the @samp{-z} option
2273 has been specified it creates a def file. Any or all of the -e, -l
2274 and -z options can be present in one invocation of dlltool.
2276 When creating a DLL, along with the source for the DLL, it is necessary
2277 to have three other files. @code{dlltool} can help with the creation of
2280 The first file is a @samp{.def} file which specifies which functions are
2281 exported from the DLL, which functions the DLL imports, and so on. This
2282 is a text file and can be created by hand, or @code{dlltool} can be used
2283 to create it using the @samp{-z} option. In this case @code{dlltool}
2284 will scan the object files specified on its command line looking for
2285 those functions which have been specially marked as being exported and
2286 put entries for them in the .def file it creates.
2288 In order to mark a function as being exported from a DLL, it needs to
2289 have an @samp{-export:<name_of_function>} entry in the @samp{.drectve}
2290 section of the object file. This can be done in C by using the
2294 asm (".section .drectve");
2295 asm (".ascii \"-export:my_func\"");
2297 int my_func (void) @{ @dots{} @}
2300 The second file needed for DLL creation is an exports file. This file
2301 is linked with the object files that make up the body of the DLL and it
2302 handles the interface between the DLL and the outside world. This is a
2303 binary file and it can be created by giving the @samp{-e} option to
2304 @code{dlltool} when it is creating or reading in a .def file.
2306 The third file needed for DLL creation is the library file that programs
2307 will link with in order to access the functions in the DLL. This file
2308 can be created by giving the @samp{-l} option to dlltool when it
2309 is creating or reading in a .def file.
2311 @code{dlltool} builds the library file by hand, but it builds the
2312 exports file by creating temporary files containing assembler statements
2313 and then assembling these. The @samp{-S} command line option can be
2314 used to specify the path to the assembler that dlltool will use,
2315 and the @samp{-f} option can be used to pass specific flags to that
2316 assembler. The @samp{-n} can be used to prevent dlltool from deleting
2317 these temporary assembler files when it is done, and if @samp{-n} is
2318 specified twice then this will prevent dlltool from deleting the
2319 temporary object files it used to build the library.
2321 Here is an example of creating a DLL from a source file @samp{dll.c} and
2322 also creating a program (from an object file called @samp{program.o})
2327 dlltool -e exports.o -l dll.lib dll.o
2328 gcc dll.o exports.o -o dll.dll
2329 gcc program.o dll.lib -o program
2332 The command line options have the following meanings:
2336 @item -d @var{filename}
2337 @itemx --input-def @var{filename}
2338 @cindex input .def file
2339 Specifies the name of a .def file to be read in and processed.
2341 @item -b @var{filename}
2342 @itemx --base-file @var{filename}
2344 Specifies the name of a base file to be read in and processed. The
2345 contents of this file will be added to the relocation section in the
2346 exports file generated by dlltool.
2348 @item -e @var{filename}
2349 @itemx --output-exp @var{filename}
2350 Specifies the name of the export file to be created by dlltool.
2352 @item -z @var{filename}
2353 @itemx --output-def @var{filename}
2354 Specifies the name of the .def file to be created by dlltool.
2356 @item -l @var{filename}
2357 @itemx --output-lib @var{filename}
2358 Specifies the name of the library file to be created by dlltool.
2360 @item --export-all-symbols
2361 Treat all global and weak defined symbols found in the input object
2362 files as symbols to be exported. There is a small list of symbols which
2363 are not exported by default; see the @code{--no-default-excludes}
2364 option. You may add to the list of symbols to not export by using the
2365 @code{--exclude-symbols} option.
2367 @item --no-export-all-symbols
2368 Only export symbols explicitly listed in an input .def file or in
2369 @samp{.drectve} sections in the input object files. This is the default
2370 behaviour. The @samp{.drectve} sections are created by @samp{dllexport}
2371 attributes in the source code.
2373 @item --exclude-symbols @var{list}
2374 Do not export the symbols in @var{list}. This is a list of symbol names
2375 separated by comma or colon characters. The symbol names should not
2376 contain a leading underscore. This is only meaningful when
2377 @code{--export-all-symbols} is used.
2379 @item --no-default-excludes
2380 When @code{--export-all-symbols} is used, it will by default avoid
2381 exporting certain special symbols. The current list of symbols to avoid
2382 exporting is @samp{DllMain@@12}, @samp{DllEntryPoint@@0},
2383 @samp{impure_ptr}. You may use the @code{--no-default-excludes} option
2384 to go ahead and export these special symbols. This is only meaningful
2385 when @code{--export-all-symbols} is used.
2388 @itemx --as @var{path}
2389 Specifies the path, including the filename, of the assembler to be used
2390 to create the exports file.
2392 @item -f @var{switches}
2393 @itemx --as-flags @var{switches}
2394 Specifies any specific command line switches to be passed to the
2395 assembler when building the exports file. This option will work even if
2396 the @samp{-S} option is not used. This option only takes one argument,
2397 and if it occurs more than once on the command line, then later
2398 occurrences will override earlier occurrences. So if it is necessary to
2399 pass multiple switches to the assembler they should be enclosed in
2403 @itemx --dll-name @var{name}
2404 Specifies the name to be stored in the .def file as the name of the DLL
2405 when the @samp{-e} option is used. If this option is not present, then
2406 the filename given to the @samp{-e} option will be used as the name of
2409 @item -m @var{machine}
2410 @itemx -machine @var{machine}
2411 Specifies the type of machine for which the library file should be
2412 built. @code{dlltool} has a built in default type, depending upon how
2413 it was created, but this option can be used to override that. This is
2414 normally only useful when creating DLLs for an ARM processor, when the
2415 contents of the DLL are actually encode using THUMB instructions.
2418 @itemx --add-indirect
2419 Specifies that when @code{dlltool} is creating the exports file it
2420 should add a section which allows the exported functions to be
2421 referenced without using the import library. Whatever the hell that
2425 @itemx --add-underscore
2426 Specifies that when @code{dlltool} is creating the exports file it
2427 should prepend an underscore to the names of the exported functions.
2431 Specifies that when @code{dlltool} is creating the exports file it
2432 should not append the string @samp{@@ <number>}. These numbers are
2433 called ordinal numbers and they represent another way of accessing the
2434 function in a DLL, other than by name.
2437 @itemx --add-stdcall-alias
2438 Specifies that when @code{dlltool} is creating the exports file it
2439 should add aliases for stdcall symbols without @samp{@@ <number>}
2440 in addition to the symbols with @samp{@@ <number>}.
2444 Specifies that when @code{dlltool} is creating the exports and library
2445 files it should omit the .idata4 section. This is for compatibility
2446 with certain operating systems.
2450 Specifies that when @code{dlltool} is creating the exports and library
2451 files it should omit the .idata5 section. This is for compatibility
2452 with certain operating systems.
2456 Specifies that @code{dlltool} should mark the objects in the library
2457 file and exports file that it produces as supporting interworking
2458 between ARM and THUMB code.
2462 Makes @code{dlltool} preserve the temporary assembler files it used to
2463 create the exports file. If this option is repeated then dlltool will
2464 also preserve the temporary object files it uses to create the library
2469 Make dlltool describe what it is doing.
2473 Displays a list of command line options and then exits.
2477 Displays dlltool's version number and then exits.
2484 @cindex ELF file information
2488 readelf [ -a | --all ]
2489 [ -h | --file-header]
2490 [ -l | --program-headers | --segments]
2491 [ -S | --section-headers | --sections]
2493 [ -s | --syms | --symbols]
2498 [ -V | --version-info]
2499 [ -D | --use-dynamic]
2500 [ -x <number> | --hex-dump=<number>]
2501 [ -w[liaprf] | --debug-dump[=info,=line,=abbrev,=pubnames,=ranges,=frames]]
2505 @var{elffile}@dots{}
2508 @code{readelf} displays information about one or more ELF format object
2509 files. The options control what particular information to display.
2511 @var{elffile}@dots{} are the object files to be examined. At the
2512 moment, @code{readelf} does not support examining archives, nor does it
2513 support examing 64 bit ELF files.
2515 The long and short forms of options, shown here as alternatives, are
2516 equivalent. At least one option besides @samp{-v} or @samp{-H} must be
2522 Equivalent to specifiying @samp{--file-header},
2523 @samp{--program-headers}, @samp{--sections}, @samp{--symbols},
2524 @samp{--relocs}, @samp{--dynamic}, @samp{--notes} and
2525 @samp{--version-info}.
2528 @itemx --file-header
2529 @cindex ELF file header information
2530 Displays the information contained in the ELF header at the start of the
2534 @itemx --program-headers
2536 @cindex ELF program header information
2537 @cindex ELF segment information
2538 Displays the information contained in the file's segment headers, if it
2543 @itemx --section-headers
2544 @cindex ELF section information
2545 Displays the information contained in the file's section headers, if it
2551 @cindex ELF symbol table information
2552 Displays the entries in symbol table section of the file, if it has one.
2556 Display all the headers in the file. Equivalent to @samp{-h -l -S}.
2560 @cindex ELF core notes
2561 Displays the contents of the NOTE segment, if it exists.
2565 @cindex ELF reloc information
2566 Displays the contents of the file's relocation section, if it has one.
2570 @cindex unwind information
2571 Displays the contents of the file's unwind section, if it has one. Only
2572 the unwind sections for IA64 ELF files are currently supported.
2576 @cindex ELF dynamic section information
2577 Displays the contents of the file's dynamic section, if it has one.
2580 @itemx --version-info
2581 @cindex ELF version sections informations
2582 Displays the contents of the version sections in the file, it they
2586 @itemx --use-dynamic
2587 When displaying symbols, this option makes @code{readelf} use the
2588 symbol table in the file's dynamic section, rather than the one in the
2592 @itemx --hex-dump=<number>
2593 Displays the contents of the indicated section as a hexadecimal dump.
2596 @itemx --debug-dump[=line,=info,=abbrev,=pubnames,=ranges,=frames]
2597 Displays the contents of the debug sections in the file, if any are
2598 present. If one of the optional letters or words follows the switch
2599 then only data found in those specific sections will be dumped.
2602 Display a histogram of bucket list lengths when displaying the contents
2603 of the symbol tables.
2607 Display the version number of readelf.
2611 Display the command line options understood by @code{readelf}.
2616 @node Selecting The Target System
2617 @chapter Selecting the target system
2619 You can specify three aspects of the target system to the @sc{gnu}
2620 binary file utilities, each in several ways:
2630 the linker emulation (which applies to the linker only)
2633 In the following summaries, the lists of ways to specify values are in
2634 order of decreasing precedence. The ways listed first override those
2637 The commands to list valid values only list the values for which the
2638 programs you are running were configured. If they were configured with
2639 @samp{--enable-targets=all}, the commands list most of the available
2640 values, but a few are left out; not all targets can be configured in at
2641 once because some of them can only be configured @dfn{native} (on hosts
2642 with the same type as the target system).
2645 * Target Selection::
2646 * Architecture Selection::
2647 * Linker Emulation Selection::
2650 @node Target Selection
2651 @section Target Selection
2653 A @dfn{target} is an object file format. A given target may be
2654 supported for multiple architectures (@pxref{Architecture Selection}).
2655 A target selection may also have variations for different operating
2656 systems or architectures.
2658 The command to list valid target values is @samp{objdump -i}
2659 (the first column of output contains the relevant information).
2661 Some sample values are: @samp{a.out-hp300bsd}, @samp{ecoff-littlemips},
2662 @samp{a.out-sunos-big}.
2664 You can also specify a target using a configuration triplet. This is
2665 the same sort of name that is passed to @file{configure} to specify a
2666 target. When you use a configuration triplet as an argument, it must be
2667 fully canonicalized. You can see the canonical version of a triplet by
2668 running the shell script @file{config.sub} which is included with the
2671 Some sample configuration triplets are: @samp{m68k-hp-bsd},
2672 @samp{mips-dec-ultrix}, @samp{sparc-sun-sunos}.
2674 @subheading @code{objdump} Target
2680 command line option: @samp{-b} or @samp{--target}
2683 environment variable @code{GNUTARGET}
2686 deduced from the input file
2689 @subheading @code{objcopy} and @code{strip} Input Target
2695 command line options: @samp{-I} or @samp{--input-target}, or @samp{-F} or @samp{--target}
2698 environment variable @code{GNUTARGET}
2701 deduced from the input file
2704 @subheading @code{objcopy} and @code{strip} Output Target
2710 command line options: @samp{-O} or @samp{--output-target}, or @samp{-F} or @samp{--target}
2713 the input target (see ``@code{objcopy} and @code{strip} Input Target'' above)
2716 environment variable @code{GNUTARGET}
2719 deduced from the input file
2722 @subheading @code{nm}, @code{size}, and @code{strings} Target
2728 command line option: @samp{--target}
2731 environment variable @code{GNUTARGET}
2734 deduced from the input file
2737 @subheading Linker Input Target
2743 command line option: @samp{-b} or @samp{--format}
2744 (@pxref{Options,,Options,ld.info,Using LD})
2747 script command @code{TARGET}
2748 (@pxref{Option Commands,,Option Commands,ld.info,Using LD})
2751 environment variable @code{GNUTARGET}
2752 (@pxref{Environment,,Environment,ld.info,Using LD})
2755 the default target of the selected linker emulation
2756 (@pxref{Linker Emulation Selection})
2759 @subheading Linker Output Target
2765 command line option: @samp{-oformat}
2766 (@pxref{Options,,Options,ld.info,Using LD})
2769 script command @code{OUTPUT_FORMAT}
2770 (@pxref{Option Commands,,Option Commands,ld.info,Using LD})
2773 the linker input target (see ``Linker Input Target'' above)
2776 @node Architecture Selection
2777 @section Architecture selection
2779 An @dfn{architecture} is a type of @sc{cpu} on which an object file is
2780 to run. Its name may contain a colon, separating the name of the
2781 processor family from the name of the particular @sc{cpu}.
2783 The command to list valid architecture values is @samp{objdump -i} (the
2784 second column contains the relevant information).
2786 Sample values: @samp{m68k:68020}, @samp{mips:3000}, @samp{sparc}.
2788 @subheading @code{objdump} Architecture
2794 command line option: @samp{-m} or @samp{--architecture}
2797 deduced from the input file
2800 @subheading @code{objcopy}, @code{nm}, @code{size}, @code{strings} Architecture
2806 deduced from the input file
2809 @subheading Linker Input Architecture
2815 deduced from the input file
2818 @subheading Linker Output Architecture
2824 script command @code{OUTPUT_ARCH}
2825 (@pxref{Option Commands,,Option Commands,ld.info,Using LD})
2828 the default architecture from the linker output target
2829 (@pxref{Target Selection})
2832 @node Linker Emulation Selection
2833 @section Linker emulation selection
2835 A linker @dfn{emulation} is a ``personality'' of the linker, which gives
2836 the linker default values for the other aspects of the target system.
2837 In particular, it consists of
2847 several ``hook'' functions that are run at certain stages of the linking
2848 process to do special things that some targets require
2851 The command to list valid linker emulation values is @samp{ld -V}.
2853 Sample values: @samp{hp300bsd}, @samp{mipslit}, @samp{sun4}.
2859 command line option: @samp{-m}
2860 (@pxref{Options,,Options,ld.info,Using LD})
2863 environment variable @code{LDEMULATION}
2866 compiled-in @code{DEFAULT_EMULATION} from @file{Makefile},
2867 which comes from @code{EMUL} in @file{config/@var{target}.mt}
2870 @node Reporting Bugs
2871 @chapter Reporting Bugs
2873 @cindex reporting bugs
2875 Your bug reports play an essential role in making the binary utilities
2878 Reporting a bug may help you by bringing a solution to your problem, or
2879 it may not. But in any case the principal function of a bug report is
2880 to help the entire community by making the next version of the binary
2881 utilities work better. Bug reports are your contribution to their
2884 In order for a bug report to serve its purpose, you must include the
2885 information that enables us to fix the bug.
2888 * Bug Criteria:: Have you found a bug?
2889 * Bug Reporting:: How to report bugs
2893 @section Have you found a bug?
2894 @cindex bug criteria
2896 If you are not sure whether you have found a bug, here are some guidelines:
2899 @cindex fatal signal
2902 If a binary utility gets a fatal signal, for any input whatever, that is
2903 a bug. Reliable utilities never crash.
2905 @cindex error on valid input
2907 If a binary utility produces an error message for valid input, that is a
2911 If you are an experienced user of binary utilities, your suggestions for
2912 improvement are welcome in any case.
2916 @section How to report bugs
2918 @cindex bugs, reporting
2920 A number of companies and individuals offer support for @sc{gnu}
2921 products. If you obtained the binary utilities from a support
2922 organization, we recommend you contact that organization first.
2924 You can find contact information for many support companies and
2925 individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
2928 In any event, we also recommend that you send bug reports for the binary
2929 utilities to @samp{bug-binutils@@gnu.org}.
2931 The fundamental principle of reporting bugs usefully is this:
2932 @strong{report all the facts}. If you are not sure whether to state a
2933 fact or leave it out, state it!
2935 Often people omit facts because they think they know what causes the
2936 problem and assume that some details do not matter. Thus, you might
2937 assume that the name of a file you use in an example does not matter.
2938 Well, probably it does not, but one cannot be sure. Perhaps the bug is
2939 a stray memory reference which happens to fetch from the location where
2940 that pathname is stored in memory; perhaps, if the pathname were
2941 different, the contents of that location would fool the utility into
2942 doing the right thing despite the bug. Play it safe and give a
2943 specific, complete example. That is the easiest thing for you to do,
2944 and the most helpful.
2946 Keep in mind that the purpose of a bug report is to enable us to fix the bug if
2947 it is new to us. Therefore, always write your bug reports on the assumption
2948 that the bug has not been reported previously.
2950 Sometimes people give a few sketchy facts and ask, ``Does this ring a
2951 bell?'' Those bug reports are useless, and we urge everyone to
2952 @emph{refuse to respond to them} except to chide the sender to report
2955 To enable us to fix the bug, you should include all these things:
2959 The version of the utility. Each utility announces it if you start it
2960 with the @samp{--version} argument.
2962 Without this, we will not know whether there is any point in looking for
2963 the bug in the current version of the binary utilities.
2966 Any patches you may have applied to the source, including any patches
2967 made to the @code{BFD} library.
2970 The type of machine you are using, and the operating system name and
2974 What compiler (and its version) was used to compile the utilities---e.g.
2978 The command arguments you gave the utility to observe the bug. To
2979 guarantee you will not omit something important, list them all. A copy
2980 of the Makefile (or the output from make) is sufficient.
2982 If we were to try to guess the arguments, we would probably guess wrong
2983 and then we might not encounter the bug.
2986 A complete input file, or set of input files, that will reproduce the
2987 bug. If the utility is reading an object file or files, then it is
2988 generally most helpful to send the actual object files, uuencoded if
2989 necessary to get them through the mail system. Note that
2990 @samp{bug-binutils@@gnu.org} is a mailing list, so you should avoid
2991 sending very large files to it. Making the files available for
2992 anonymous FTP is OK.
2994 If the source files were produced exclusively using @sc{gnu} programs
2995 (e.g., @code{gcc}, @code{gas}, and/or the @sc{gnu} @code{ld}), then it
2996 may be OK to send the source files rather than the object files. In
2997 this case, be sure to say exactly what version of @code{gcc}, or
2998 whatever, was used to produce the object files. Also say how
2999 @code{gcc}, or whatever, was configured.
3002 A description of what behavior you observe that you believe is
3003 incorrect. For example, ``It gets a fatal signal.''
3005 Of course, if the bug is that the utility gets a fatal signal, then we
3006 will certainly notice it. But if the bug is incorrect output, we might
3007 not notice unless it is glaringly wrong. You might as well not give us
3008 a chance to make a mistake.
3010 Even if the problem you experience is a fatal signal, you should still
3011 say so explicitly. Suppose something strange is going on, such as your
3012 copy of the utility is out of synch, or you have encountered a bug in
3013 the C library on your system. (This has happened!) Your copy might
3014 crash and ours would not. If you told us to expect a crash, then when
3015 ours fails to crash, we would know that the bug was not happening for
3016 us. If you had not told us to expect a crash, then we would not be able
3017 to draw any conclusion from our observations.
3020 If you wish to suggest changes to the source, send us context diffs, as
3021 generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
3022 option. Always send diffs from the old file to the new file. If you
3023 wish to discuss something in the @code{ld} source, refer to it by
3024 context, not by line number.
3026 The line numbers in our development sources will not match those in your
3027 sources. Your line numbers would convey no useful information to us.
3030 Here are some things that are not necessary:
3034 A description of the envelope of the bug.
3036 Often people who encounter a bug spend a lot of time investigating
3037 which changes to the input file will make the bug go away and which
3038 changes will not affect it.
3040 This is often time consuming and not very useful, because the way we
3041 will find the bug is by running a single example under the debugger
3042 with breakpoints, not by pure deduction from a series of examples.
3043 We recommend that you save your time for something else.
3045 Of course, if you can find a simpler example to report @emph{instead}
3046 of the original one, that is a convenience for us. Errors in the
3047 output will be easier to spot, running under the debugger will take
3048 less time, and so on.
3050 However, simplification is not vital; if you do not want to do this,
3051 report the bug anyway and send us the entire test case you used.
3054 A patch for the bug.
3056 A patch for the bug does help us if it is a good one. But do not omit
3057 the necessary information, such as the test case, on the assumption that
3058 a patch is all we need. We might see problems with your patch and decide
3059 to fix the problem another way, or we might not understand it at all.
3061 Sometimes with programs as complicated as the binary utilities it is
3062 very hard to construct an example that will make the program follow a
3063 certain path through the code. If you do not send us the example, we
3064 will not be able to construct one, so we will not be able to verify that
3067 And if we cannot understand what bug you are trying to fix, or why your
3068 patch should be an improvement, we will not install it. A test case will
3069 help us to understand.
3072 A guess about what the bug is or what it depends on.
3074 Such guesses are usually wrong. Even we cannot guess right about such
3075 things without first using the debugger to find the facts.
3078 @node GNU Free Documentation License
3079 @chapter GNU Free Documentation License
3080 @cindex GNU Free Documentation License
3082 GNU Free Documentation License
3084 Version 1.1, March 2000
3086 Copyright (C) 2000 Free Software Foundation, Inc.
3087 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
3089 Everyone is permitted to copy and distribute verbatim copies
3090 of this license document, but changing it is not allowed.
3095 The purpose of this License is to make a manual, textbook, or other
3096 written document "free" in the sense of freedom: to assure everyone
3097 the effective freedom to copy and redistribute it, with or without
3098 modifying it, either commercially or noncommercially. Secondarily,
3099 this License preserves for the author and publisher a way to get
3100 credit for their work, while not being considered responsible for
3101 modifications made by others.
3103 This License is a kind of "copyleft", which means that derivative
3104 works of the document must themselves be free in the same sense. It
3105 complements the GNU General Public License, which is a copyleft
3106 license designed for free software.
3108 We have designed this License in order to use it for manuals for free
3109 software, because free software needs free documentation: a free
3110 program should come with manuals providing the same freedoms that the
3111 software does. But this License is not limited to software manuals;
3112 it can be used for any textual work, regardless of subject matter or
3113 whether it is published as a printed book. We recommend this License
3114 principally for works whose purpose is instruction or reference.
3117 1. APPLICABILITY AND DEFINITIONS
3119 This License applies to any manual or other work that contains a
3120 notice placed by the copyright holder saying it can be distributed
3121 under the terms of this License. The "Document", below, refers to any
3122 such manual or work. Any member of the public is a licensee, and is
3125 A "Modified Version" of the Document means any work containing the
3126 Document or a portion of it, either copied verbatim, or with
3127 modifications and/or translated into another language.
3129 A "Secondary Section" is a named appendix or a front-matter section of
3130 the Document that deals exclusively with the relationship of the
3131 publishers or authors of the Document to the Document's overall subject
3132 (or to related matters) and contains nothing that could fall directly
3133 within that overall subject. (For example, if the Document is in part a
3134 textbook of mathematics, a Secondary Section may not explain any
3135 mathematics.) The relationship could be a matter of historical
3136 connection with the subject or with related matters, or of legal,
3137 commercial, philosophical, ethical or political position regarding
3140 The "Invariant Sections" are certain Secondary Sections whose titles
3141 are designated, as being those of Invariant Sections, in the notice
3142 that says that the Document is released under this License.
3144 The "Cover Texts" are certain short passages of text that are listed,
3145 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
3146 the Document is released under this License.
3148 A "Transparent" copy of the Document means a machine-readable copy,
3149 represented in a format whose specification is available to the
3150 general public, whose contents can be viewed and edited directly and
3151 straightforwardly with generic text editors or (for images composed of
3152 pixels) generic paint programs or (for drawings) some widely available
3153 drawing editor, and that is suitable for input to text formatters or
3154 for automatic translation to a variety of formats suitable for input
3155 to text formatters. A copy made in an otherwise Transparent file
3156 format whose markup has been designed to thwart or discourage
3157 subsequent modification by readers is not Transparent. A copy that is
3158 not "Transparent" is called "Opaque".
3160 Examples of suitable formats for Transparent copies include plain
3161 ASCII without markup, Texinfo input format, LaTeX input format, SGML
3162 or XML using a publicly available DTD, and standard-conforming simple
3163 HTML designed for human modification. Opaque formats include
3164 PostScript, PDF, proprietary formats that can be read and edited only
3165 by proprietary word processors, SGML or XML for which the DTD and/or
3166 processing tools are not generally available, and the
3167 machine-generated HTML produced by some word processors for output
3170 The "Title Page" means, for a printed book, the title page itself,
3171 plus such following pages as are needed to hold, legibly, the material
3172 this License requires to appear in the title page. For works in
3173 formats which do not have any title page as such, "Title Page" means
3174 the text near the most prominent appearance of the work's title,
3175 preceding the beginning of the body of the text.
3180 You may copy and distribute the Document in any medium, either
3181 commercially or noncommercially, provided that this License, the
3182 copyright notices, and the license notice saying this License applies
3183 to the Document are reproduced in all copies, and that you add no other
3184 conditions whatsoever to those of this License. You may not use
3185 technical measures to obstruct or control the reading or further
3186 copying of the copies you make or distribute. However, you may accept
3187 compensation in exchange for copies. If you distribute a large enough
3188 number of copies you must also follow the conditions in section 3.
3190 You may also lend copies, under the same conditions stated above, and
3191 you may publicly display copies.
3194 3. COPYING IN QUANTITY
3196 If you publish printed copies of the Document numbering more than 100,
3197 and the Document's license notice requires Cover Texts, you must enclose
3198 the copies in covers that carry, clearly and legibly, all these Cover
3199 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
3200 the back cover. Both covers must also clearly and legibly identify
3201 you as the publisher of these copies. The front cover must present
3202 the full title with all words of the title equally prominent and
3203 visible. You may add other material on the covers in addition.
3204 Copying with changes limited to the covers, as long as they preserve
3205 the title of the Document and satisfy these conditions, can be treated
3206 as verbatim copying in other respects.
3208 If the required texts for either cover are too voluminous to fit
3209 legibly, you should put the first ones listed (as many as fit
3210 reasonably) on the actual cover, and continue the rest onto adjacent
3213 If you publish or distribute Opaque copies of the Document numbering
3214 more than 100, you must either include a machine-readable Transparent
3215 copy along with each Opaque copy, or state in or with each Opaque copy
3216 a publicly-accessible computer-network location containing a complete
3217 Transparent copy of the Document, free of added material, which the
3218 general network-using public has access to download anonymously at no
3219 charge using public-standard network protocols. If you use the latter
3220 option, you must take reasonably prudent steps, when you begin
3221 distribution of Opaque copies in quantity, to ensure that this
3222 Transparent copy will remain thus accessible at the stated location
3223 until at least one year after the last time you distribute an Opaque
3224 copy (directly or through your agents or retailers) of that edition to
3227 It is requested, but not required, that you contact the authors of the
3228 Document well before redistributing any large number of copies, to give
3229 them a chance to provide you with an updated version of the Document.
3234 You may copy and distribute a Modified Version of the Document under
3235 the conditions of sections 2 and 3 above, provided that you release
3236 the Modified Version under precisely this License, with the Modified
3237 Version filling the role of the Document, thus licensing distribution
3238 and modification of the Modified Version to whoever possesses a copy
3239 of it. In addition, you must do these things in the Modified Version:
3241 A. Use in the Title Page (and on the covers, if any) a title distinct
3242 from that of the Document, and from those of previous versions
3243 (which should, if there were any, be listed in the History section
3244 of the Document). You may use the same title as a previous version
3245 if the original publisher of that version gives permission.
3246 B. List on the Title Page, as authors, one or more persons or entities
3247 responsible for authorship of the modifications in the Modified
3248 Version, together with at least five of the principal authors of the
3249 Document (all of its principal authors, if it has less than five).
3250 C. State on the Title page the name of the publisher of the
3251 Modified Version, as the publisher.
3252 D. Preserve all the copyright notices of the Document.
3253 E. Add an appropriate copyright notice for your modifications
3254 adjacent to the other copyright notices.
3255 F. Include, immediately after the copyright notices, a license notice
3256 giving the public permission to use the Modified Version under the
3257 terms of this License, in the form shown in the Addendum below.
3258 G. Preserve in that license notice the full lists of Invariant Sections
3259 and required Cover Texts given in the Document's license notice.
3260 H. Include an unaltered copy of this License.
3261 I. Preserve the section entitled "History", and its title, and add to
3262 it an item stating at least the title, year, new authors, and
3263 publisher of the Modified Version as given on the Title Page. If
3264 there is no section entitled "History" in the Document, create one
3265 stating the title, year, authors, and publisher of the Document as
3266 given on its Title Page, then add an item describing the Modified
3267 Version as stated in the previous sentence.
3268 J. Preserve the network location, if any, given in the Document for
3269 public access to a Transparent copy of the Document, and likewise
3270 the network locations given in the Document for previous versions
3271 it was based on. These may be placed in the "History" section.
3272 You may omit a network location for a work that was published at
3273 least four years before the Document itself, or if the original
3274 publisher of the version it refers to gives permission.
3275 K. In any section entitled "Acknowledgements" or "Dedications",
3276 preserve the section's title, and preserve in the section all the
3277 substance and tone of each of the contributor acknowledgements
3278 and/or dedications given therein.
3279 L. Preserve all the Invariant Sections of the Document,
3280 unaltered in their text and in their titles. Section numbers
3281 or the equivalent are not considered part of the section titles.
3282 M. Delete any section entitled "Endorsements". Such a section
3283 may not be included in the Modified Version.
3284 N. Do not retitle any existing section as "Endorsements"
3285 or to conflict in title with any Invariant Section.
3287 If the Modified Version includes new front-matter sections or
3288 appendices that qualify as Secondary Sections and contain no material
3289 copied from the Document, you may at your option designate some or all
3290 of these sections as invariant. To do this, add their titles to the
3291 list of Invariant Sections in the Modified Version's license notice.
3292 These titles must be distinct from any other section titles.
3294 You may add a section entitled "Endorsements", provided it contains
3295 nothing but endorsements of your Modified Version by various
3296 parties--for example, statements of peer review or that the text has
3297 been approved by an organization as the authoritative definition of a
3300 You may add a passage of up to five words as a Front-Cover Text, and a
3301 passage of up to 25 words as a Back-Cover Text, to the end of the list
3302 of Cover Texts in the Modified Version. Only one passage of
3303 Front-Cover Text and one of Back-Cover Text may be added by (or
3304 through arrangements made by) any one entity. If the Document already
3305 includes a cover text for the same cover, previously added by you or
3306 by arrangement made by the same entity you are acting on behalf of,
3307 you may not add another; but you may replace the old one, on explicit
3308 permission from the previous publisher that added the old one.
3310 The author(s) and publisher(s) of the Document do not by this License
3311 give permission to use their names for publicity for or to assert or
3312 imply endorsement of any Modified Version.
3315 5. COMBINING DOCUMENTS
3317 You may combine the Document with other documents released under this
3318 License, under the terms defined in section 4 above for modified
3319 versions, provided that you include in the combination all of the
3320 Invariant Sections of all of the original documents, unmodified, and
3321 list them all as Invariant Sections of your combined work in its
3324 The combined work need only contain one copy of this License, and
3325 multiple identical Invariant Sections may be replaced with a single
3326 copy. If there are multiple Invariant Sections with the same name but
3327 different contents, make the title of each such section unique by
3328 adding at the end of it, in parentheses, the name of the original
3329 author or publisher of that section if known, or else a unique number.
3330 Make the same adjustment to the section titles in the list of
3331 Invariant Sections in the license notice of the combined work.
3333 In the combination, you must combine any sections entitled "History"
3334 in the various original documents, forming one section entitled
3335 "History"; likewise combine any sections entitled "Acknowledgements",
3336 and any sections entitled "Dedications". You must delete all sections
3337 entitled "Endorsements."
3340 6. COLLECTIONS OF DOCUMENTS
3342 You may make a collection consisting of the Document and other documents
3343 released under this License, and replace the individual copies of this
3344 License in the various documents with a single copy that is included in
3345 the collection, provided that you follow the rules of this License for
3346 verbatim copying of each of the documents in all other respects.
3348 You may extract a single document from such a collection, and distribute
3349 it individually under this License, provided you insert a copy of this
3350 License into the extracted document, and follow this License in all
3351 other respects regarding verbatim copying of that document.
3354 7. AGGREGATION WITH INDEPENDENT WORKS
3356 A compilation of the Document or its derivatives with other separate
3357 and independent documents or works, in or on a volume of a storage or
3358 distribution medium, does not as a whole count as a Modified Version
3359 of the Document, provided no compilation copyright is claimed for the
3360 compilation. Such a compilation is called an "aggregate", and this
3361 License does not apply to the other self-contained works thus compiled
3362 with the Document, on account of their being thus compiled, if they
3363 are not themselves derivative works of the Document.
3365 If the Cover Text requirement of section 3 is applicable to these
3366 copies of the Document, then if the Document is less than one quarter
3367 of the entire aggregate, the Document's Cover Texts may be placed on
3368 covers that surround only the Document within the aggregate.
3369 Otherwise they must appear on covers around the whole aggregate.
3374 Translation is considered a kind of modification, so you may
3375 distribute translations of the Document under the terms of section 4.
3376 Replacing Invariant Sections with translations requires special
3377 permission from their copyright holders, but you may include
3378 translations of some or all Invariant Sections in addition to the
3379 original versions of these Invariant Sections. You may include a
3380 translation of this License provided that you also include the
3381 original English version of this License. In case of a disagreement
3382 between the translation and the original English version of this
3383 License, the original English version will prevail.
3388 You may not copy, modify, sublicense, or distribute the Document except
3389 as expressly provided for under this License. Any other attempt to
3390 copy, modify, sublicense or distribute the Document is void, and will
3391 automatically terminate your rights under this License. However,
3392 parties who have received copies, or rights, from you under this
3393 License will not have their licenses terminated so long as such
3394 parties remain in full compliance.
3397 10. FUTURE REVISIONS OF THIS LICENSE
3399 The Free Software Foundation may publish new, revised versions
3400 of the GNU Free Documentation License from time to time. Such new
3401 versions will be similar in spirit to the present version, but may
3402 differ in detail to address new problems or concerns. See
3403 http://www.gnu.org/copyleft/.
3405 Each version of the License is given a distinguishing version number.
3406 If the Document specifies that a particular numbered version of this
3407 License "or any later version" applies to it, you have the option of
3408 following the terms and conditions either of that specified version or
3409 of any later version that has been published (not as a draft) by the
3410 Free Software Foundation. If the Document does not specify a version
3411 number of this License, you may choose any version ever published (not
3412 as a draft) by the Free Software Foundation.
3415 ADDENDUM: How to use this License for your documents
3417 To use this License in a document you have written, include a copy of
3418 the License in the document and put the following copyright and
3419 license notices just after the title page:
3422 Copyright (c) YEAR YOUR NAME.
3423 Permission is granted to copy, distribute and/or modify this document
3424 under the terms of the GNU Free Documentation License, Version 1.1
3425 or any later version published by the Free Software Foundation;
3426 with the Invariant Sections being LIST THEIR TITLES, with the
3427 Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
3428 A copy of the license is included in the section entitled "GNU
3429 Free Documentation License".
3432 If you have no Invariant Sections, write "with no Invariant Sections"
3433 instead of saying which ones are invariant. If you have no
3434 Front-Cover Texts, write "no Front-Cover Texts" instead of
3435 "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
3437 If your document contains nontrivial examples of program code, we
3438 recommend releasing these examples in parallel under your choice of
3439 free software license, such as the GNU General Public License,
3440 to permit their use in free software.