diff options
Diffstat (limited to 'binutils/binutils.texinfo')
| -rwxr-xr-x | binutils/binutils.texinfo | 730 |
1 files changed, 0 insertions, 730 deletions
diff --git a/binutils/binutils.texinfo b/binutils/binutils.texinfo deleted file mode 100755 index 37167e5..0000000 --- a/binutils/binutils.texinfo +++ /dev/null @@ -1,730 +0,0 @@ -\input texinfo -@setfilename binutils.info -@synindex ky cp -@c -@c This file documents the GNU binary utilities "ar", "ld", "objdump", "nm", -@c "size", "strip", and "ranlib". -@c -@c Copyright (C) 1991 Free Software Foundation, Inc. -@c -@c This text may be freely distributed under the terms of the GNU -@c General Public License. -@c -@c $Id$ -@iftex -@finalout -@c @smallbook -@end iftex -@c @cropmarks -@setchapternewpage odd -@settitle GNU Binary Utilities -@titlepage -@title The GNU Binary Utilities -@subtitle Version 1.90 -@sp 1 -@subtitle October 1991 -@author Roland H. Pesch -@author Cygnus Support -@page - -@tex -\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision$} % For use in headers, footers too -{\parskip=0pt \hfill Cygnus Support\par \hfill \manvers\par \hfill -\TeX{}info \texinfoversion\par } -@end tex - -@vskip 0pt plus 1filll -Copyright @copyright{} 1991 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. -@end titlepage - -@node Top, ar, (dir), (dir) -@chapter Introduction - -@cindex version -This brief manual contains preliminary documentation for the GNU binary -utilities (collectively version 1.90): -@table @code -@item ar -Create, modify, and extract from archives - -@item nm -List symbols from object files - -@item objdump -Display information from object files - -@item ranlib -Generate index to archive contents - -@item size -List section sizes and total size - -@item strip -Discard symbols -@end table - -@ifinfo -Copyright @copyright{} 1991 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries a copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. -@end ifinfo - -@menu -* ar:: Create, modify, and extract from archives -* ld:: See ld.info -* nm:: List symbols from object files -* objdump:: Display information from object files -* ranlib:: Generate index to archive contents -* size:: List section sizes and total size -* strip:: Discard symbols -* Index:: -@end menu - -@node ar, ld, Top, Top -@chapter ar - -@kindex ar -@cindex archives -@cindex collections of files -@smallexample - ar [-]@var{p}@var{mod} [ @var{membername} ] @var{archive} @var{files}@dots{} -@end smallexample - -The GNU @code{ar} program creates, modifies, and extracts from -archives. An @dfn{archive} is a single file holding a collection of -other files in a structure that makes it possible to retrieve -the original individual files (called @dfn{members} of the archive). - -The original files' contents, mode (permissions), timestamp, owner, and -group are preserved in the archive, and may be reconstituted on -extraction. - -@cindex name length -GNU @code{ar} can maintain archives whose members have names of any -length; however, depending on how @code{ar} is configured on your -system, a limit on member-name length may be imposed (for compatibility -with archive formats maintained with other tools). If it exists, the -limit is often 15 characters (typical of formats related to a.out) or 16 -characters (typical of formats related to coff). - -@cindex libraries -@code{ar} is considered a binary utility because archives of this sort -are most often used as @dfn{libraries} holding commonly needed -subroutines. - -@cindex symbol index -@code{ar} will create an index to the symbols defined in relocatable -object modules in the archive when you specify the modifier @samp{s}. -Once created, this index is updated in the archive whenever @code{ar} -makes a change to its contents (save for the @samp{q} update operation). -An archive with such an index speeds up linking to the library, and -allows routines in the library to call each other without regard to -their placement in the archive. - -You may use @samp{nm -s} or @samp{nm +print-armap} to list this index -table. If an archive lacks the table, another form of @code{ar} called -@code{ranlib} can be used to add just the table. - -@code{ar} insists on at least two arguments to execute: one -keyletter specifying the @emph{operation} (optionally accompanied by other -keyletters specifying @emph{modifiers}), and the archive name to act on. - -Most operations can also accept further @var{files} arguments, -specifying particular files to operate on. - -GNU @code{ar} allows you to mix the operation code @var{p} and modifier -flags @var{mod} in any order, within the first command-line argument. - -If you wish, you may begin the first command-line argument with a -dash. - -@cindex operations on archive -The @var{p} keyletter specifies what operation to execute; it may be -any of the following, but you must specify only one of them: - -@table @code -@item d -@cindex deleting from archive -@emph{Delete} modules from the archive. Specify the names of modules to -be deleted as @var{files}; the archive is untouched if you -specify no files to delete. - -If you specify the @samp{v} modifier, @code{ar} will list each module -as it is deleted. - -@item m -@cindex moving in archive -Use this operation to @emph{move} members in an archive. - -The ordering of members in an archive can make a difference in how -programs are linked using the library, if a symbol is defined in more -than one member. - -If no modifiers are used with @code{m}, any members you name in the -@var{files} arguments are moved to the @emph{end} of the archive; -you can use the @samp{a}, @samp{b}, or @samp{i} modifiers to move them to a -specified place instead. - -@item p -@cindex printing from archive -@emph{Print} the specified members of the archive, to the standard -output file. If the @samp{v} modifier is specified, show the member -name before copying its contents to standard output. - -If you specify no @var{files}, all the files in the archive are printed. - -@item q -@cindex quick append to archive -@emph{Quick append}; add @var{files} to the end of @var{archive}, -without checking for replacement. - -The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this -operation; new members are always placed at the end of the archive. - -The modifier @samp{v} makes @code{ar} list each file as it is appended. - -Since the point of this operation is speed, the archive's symbol table -index is not updated, even if it already existed; you can use @samp{ar s} or -@code{ranlib} explicitly to update the symbol table index. - -@item r -@cindex replacement in archive -Insert @var{files} into @var{archive} (with @emph{replacement}). This -operation differs from @samp{q} in that any previously existing members -are deleted if their names match those being added. - -If one of the files named in @var{files} doesn't exist, @code{ar} -displays an error message, and leaves undisturbed any existing members -of the archive matching that name. - -By default, new members are added at the end of the file; but you may -use one of the modifiers @samp{a}, @samp{b}, or @samp{i} to request -placement relative to some existing member. - -The modifier @samp{v} used with this operation elicits a line of -output for each file inserted, along with one of the letters @samp{a} or -@samp{r} to indicate whether the file was appended (no old member -deleted) or replaced. - -@item t -@cindex contents of archive -Display a @emph{table} listing the contents of @var{archive}, or those -of the files listed in @var{files} that are present in the -archive. Normally only the member name is shown; if you also want to -see the modes (permissions), timestamp, owner, group, and size, you can -request that by also specifying the @samp{v} modifier. - -If you do not specify any @var{files}, all files in the archive -are listed. - -@cindex repeated names in archive -@cindex name duplication in archive -If there is more than one file with the same name (say, @samp{fie}) in -an archive (say @samp{b.a}), @samp{ar t b.a fie} will list only the -first instance; to see them all, you must ask for a complete -listing---in our example, @samp{ar t b.a}. -@c WRS only; per Gumby, this is implementation-dependent, and in a more -@c recent case in fact works the other way. - -@item x -@cindex extract from archive -@emph{Extract} members (named @var{files}) from the archive. You can -use the @samp{v} modifier with this operation, to request that -@code{ar} list each name as it extracts it. - -If you do not specify any @var{files}, all files in the archive -are extracted. - -@end table - -A number of modifiers (@var{mod}) may immediately follow the @var{p} -keyletter, to specify variations on an operation's behavior: - -@table @code -@item a -@cindex relative placement in archive -Add new files @emph{after} an existing member of the -archive. If you use the modifier @code{a}, the name of an existing archive -member must be present as the @var{membername} argument, before the -@var{archive} specification. - -@item b -Add new files @emph{before} an existing member of the -archive. If you use the modifier @code{b}, the name of an existing archive -member must be present as the @var{membername} argument, before the -@var{archive} specification. (same as @samp{i}). - -@item c -@cindex creating archives -@emph{Create} the archive. The specified @var{archive} is always -created if it didn't exist, when you request an update. But a warning is -issued unless you specify in advance that you expect to create it, by -using this modifier. - -@item i -Insert new files @emph{before} an existing member of the -archive. If you use the modifier @code{i}, the name of an existing archive -member must be present as the @var{membername} argument, before the -@var{archive} specification. (same as @samp{b}). - -@item l -This modifier is accepted but not used. -@c whaffor ar l modifier??? presumably compat; with -@c what???---pesch@@cygnus.com, 25jan91 - -@item o -@cindex dates in archive -Preserve the @emph{original} dates of members when extracting them. If -you do not specify this modifier, files extracted from the archive -will be stamped with the time of extraction. - -@item s -@cindex writing archive index -Write an object-file index into the archive, or update an existing one, -even if no other change is made to the archive. You may use this modifier -flag either with any operation, or alone. Running @samp{ar s} on an -archive is equivalent to running @samp{ranlib} on it. - -@item u -@cindex updating an archive -Normally, @code{ar r}@dots{} inserts all files -listed into the archive. If you would like to insert @emph{only} those -of the files you list that are newer than existing members of the same -names, use this modifier. The @samp{u} modifier is allowed only for the -operation @samp{r} (replace). In particular, the combination @samp{qu} is -not allowed, since checking the timestamps would lose any speed -advantage from the operation @samp{q}. - -@item v -This modifier requests the @emph{verbose} version of an operation. Many -operations display additional information, such as filenames processed, -when the modifier @samp{v} is appended. - -@end table - -@node ld, nm, ar, Top -@chapter ld -@cindex linker -@kindex ld -The GNU linker @code{ld} is now described in a separate manual. -@xref{Top,, Overview,, GLD: the GNU linker}. - -@node nm, objdump, ld, Top -@chapter nm -@cindex symbols -@kindex nm - -@smallexample - nm [ -a | +debug-syms ] [ -g | +extern-only ] - [ -s | +print-armap ] [ -o | +print-file-name ] - [ -n | +numeric-sort ] [ -p | +no-sort ] - [ -r | +reverse-sort ] [ -u | +undefined-only ] - [ +target @var{bfdname} ] - [ @var{objfiles}@dots{} ] -@end smallexample - -GNU @code{nm} will list the symbols from object files @var{objfiles}. - -The long and short forms of options, shown here as alternatives, are -equivalent. - -@table @code -@item @var{objfiles}@dots{} -@kindex a.out -Object files whose symbols are to be listed. If no object files are -listed as arguments, @code{nm} assumes @samp{a.out}. - -@item -a -@itemx +debug-syms -@cindex debugging symbols -Display debugger-only symbols; normally these are not listed. - -@item -g -@itemx +extern-only -@cindex external symbols -Display only external symbols. - -@item -p -@itemx +no-sort -@cindex sorting symbols -Don't bother to sort the symbols in any order; just print them in the -order encountered. - -@item -n -@itemx +numeric-sort -Sort symbols numerically by their addresses, not alphabetically by their -names. - -@item -s -@itemx +print-armap -@cindex symbol index, listing -When listing symbols from archive members, include the index: a mapping -(stored in the archive by @code{ar} or @code{ranlib}) of what modules -contain definitions for what names. - -@item -o -@itemx +print-file-name -@cindex input file name -@cindex file name -@cindex source file name -Precede each symbol by the name of the input file where it was found, -rather than identifying the input file once only before all of its -symbols. - -@item -r -@itemx +reverse-sort -Reverse the sense of the sort (whether numeric or alphabetic); let the -last come first. - -@item +target @var{bfdname} -@c @item +target -@cindex object code format -Specify an object code format other than your system's default format. -@xref{objdump}, for information on listing available formats. -@c FIXME what *does* +target/no arg do? - -@item -u -@itemx +undefined-only -@cindex external symbols -@cindex undefined symbols -Display only undefined symbols (those external to each object file). - -@end table - -@node objdump, ranlib, nm, Top -@chapter objdump - -@cindex object file information -@kindex objdump - -@smallexample - objdump [ -a ] [ -b @var{bfdname} ] [ -d ] [ -f ] - [ -h | +header ] [ -i ] [ -j @var{section} ] [ -l ] - [ -m @var{machine} ] [ -r | +reloc ] [ -s ] - [ -t | +syms ] [ -x ] - @var{objfiles}@dots{} -@end smallexample - -@code{objdump} displays information about one or more object files. -The options control what particular information to display. This -information is mostly useful to programmers who are working on the -compilation tools, as opposed to programmers who just want their -program to compile and work. - -The long and short forms of options, shown here as alternatives, are -equivalent. - -@table @code -@item @var{objfiles}@dots{} -The object files to be examined. When you specify archives, -@code{objdump} shows information on each of the member object files. - -@item -a -@c print_arelt_descr -@cindex archive headers -If any files from @var{objfiles} are archives, display the archive -header information (in a format similar to @samp{ls -l}). Besides the -information you could list with @samp{ar tv}, @samp{objdump -a} shows -the object file format of each archive member. - -@c suggest longname +target or +format or +bfd -@item -b @var{bfdname} -@cindex object code format -You can specify a particular object-code format for your object files as -@var{bfdname}. This may not be necessary; @var{objdump} can -automatically recognize many formats. For example, -@example -objdump -b oasys -m vax -h fu.o -@end example -@noindent -Displays summary information from the section headers (@samp{-h}) of -@file{fu.o}, which is explicitly identified (@samp{-m}) as a Vax object -file in the format produced by Oasys compilers. You can list the -formats available with the @samp{-i} option. - -@item -d -@cindex disassembling object code -@cindex machine instructions -Disassemble. Display the assembler mnemonics for the machine -instructions from @var{objfiles}. - -@item -f -@cindex object file header -File header. Display summary information from the overall header of -each file in @var{objfiles}. - -@item -h -@itemx +header -@cindex section headers -Header. Display summary information from the section headers of the -object file. - -@item -i -@cindex architectures available -@cindex object formats available -Display a list showing all architectures and object formats available -for specification with @code{-b} or @code{-m}. - -@c suggest longname +section -@item -j @var{name} -@cindex section information -Display information only for section @var{name} - -@c suggest longname +label or +linespec -@item -l -@cindex source filenames for object files -Label the display (using debugging information) with the source filename -and line numbers corresponding to the object code shown. - -@c suggest longname +architecture -@item -m @var{machine} -@cindex architecture -Specify the object files @var{objfiles} are for architecture -@var{machine}. You can list available architectures using the @samp{-i} -option. - -@item -r -@itemx +reloc -@cindex relocation entries, in object file -Relocation. Print the relocation entries of the file. - -@item -s -@cindex sections, full contents -@cindex object file sections -Display the full contents of any sections requested. - -@item -t -@itemx +syms -@cindex symbol table entries, printing -Symbol Table. Print the symbol table entries of the file. -This is similar to the information provided by the @samp{nm} program. - -@item -x -@cindex all header information, object file -@cindex header information, all -Display all available header information, including the symbol table and -relocation entries. Using @samp{-x} is equivalent to specifying all of -@samp{-a -f -h -r -t}. - -@end table - -@node ranlib, size, objdump, Top -@chapter ranlib - -@kindex ranlib -@cindex archive contents -@cindex symbol index - -@smallexample - ranlib @var{archive} -@end smallexample - -@code{ranlib} generates an index to the contents of an archive, and -stores it in the archive. The index lists each symbol defined by a -member of an archive that is a relocatable object file. - -You may use @samp{nm -s} or @samp{nm +print-armap} to list this index. - -An archive with such an index speeds up linking to the library, and -allows routines in the library to call each other without regard to -their placement in the archive. - -The GNU @code{ranlib} program is another form of GNU @code{ar}; running -@code{ranlib} is completely equivalent to executing @samp{ar -s}. -@xref{ar}. - -@node size, strip, ranlib, Top -@chapter size - -@kindex size -@cindex section sizes - -@smallexample - size [ -A | -B | +format @var{compatibility} ] - [ +help ] [ -d | -o | -x | +radix @var{number} ] - [ +target @var{bfdname} ] [ -V | +version ] - @var{objfiles}@dots{} -@end smallexample - -The GNU @code{size} utility lists the section sizes---and the total -size---for each of the object files @var{objfiles} in its argument list. -By default, one line of output is generated for each object file or each -module in an archive. - -The command line options have the following meanings: -@table @code -@item @var{objfiles}@dots{} -The object files to be examined. - -@item -A -@itemx -B -@itemx +format @var{compatibility} -@cindex size display format -Using one of these options, you can choose whether the output from GNU -@code{size} resembles output from System V @code{size} (using @samp{-A}, -or @samp{+format sysv}), or Berkeley @code{size} (using @samp{-B}, or -@samp{+format berkeley}). The default is the one-line format similar to -Berkeley's. -@c Bonus for doc-source readers: you can also say +format=strange (or -@c anything else that starts with 's') for sysv, and +format=boring (or -@c anything else that starts with 'b') for Berkeley. - -Here is an example of the Berkeley (default) format of output from -@code{size}: -@smallexample - eg$ size +format Berkeley ranlib size -text data bss dec hex filename -294880 81920 11592 388392 5ed28 ranlib -294880 81920 11888 388688 5ee50 size -@end smallexample - -@noindent -This is the same data, but displayed closer to System V conventions: - -@smallexample - eg$ size +format SysV ranlib size -ranlib : -section size addr -.text 294880 8192 -.data 81920 303104 -.bss 11592 385024 -Total 388392 - - -size : -section size addr -.text 294880 8192 -.data 81920 303104 -.bss 11888 385024 -Total 388688 -@end smallexample - -@item +help -Show a summary of acceptable arguments and options. - -@item -d -@itemx -o -@itemx -x -@itemx +radix @var{number} -@cindex size number format -@cindex radix for section sizes -Using one of these options, you can control whether the size of each -section is given in decimal (@samp{-d}, or @samp{+radix 10}); octal -(@samp{-o}, or @samp{+radix 8}); or hexadecimal (@samp{-x}, or -@samp{+radix 16}). In @samp{+radix @var{number}}, only the three -values (8, 10, 16) are supported. The total size is always given in two -radices; decimal and hexadecimal for @samp{-d} or @samp{-x} output, or -octal and hexadecimal if you're using @samp{-o}. - -@item +target @var{bfdname} -@cindex object code format -You can specify a particular object-code format for @var{objfiles} as -@var{bfdname}. This may not be necessary; @var{size} can -automatically recognize many formats. @xref{objdump}, for information -on listing available formats. - -@item -V -@itemx +version -Display version number information on @code{size} itself. - -@end table - -@node strip, Index, size, Top -@chapter strip - -@kindex strip -@cindex removing symbols -@cindex discarding symbols - -@smallexample - strip [ -s | +strip-all ] [ -g | -S | +strip-debug ] - [ -x | +discard-all ] [ -X | +discard-locals ] - [ -T @var{bfdname} ] - @var{objfiles}@dots{} -@end smallexample - -GNU @code{strip} will discard all symbols from object files -@var{objfiles}, if no options are specified; or only certain symbols, -depending on its command-line options. - -@code{strip} will not execute unless at least one object file is listed. - -@quotation -@emph{WARNING:} @code{strip} modifies the files named in its argument, -rather than writing modified copies under different names. -@end quotation - -The long and short forms of options, shown here as alternatives, are -equivalent. - -@table @code -@item -s -@itemx +strip-all -@cindex all symbols, discarding -This is the default case: strip all symbol entries from @var{objfiles}. - -@item -g -@itemx -S -@itemx +strip-debug -@cindex debugging symbols, discarding -Discard only debugging symbol information from @var{objfiles}. - -@item -x -@itemx +discard-all -@cindex local symbols, discarding -Discard all symbols local to each file in @var{objfiles}. -@emph{WARNING:} Note that @code{+discard-all} discards only @emph{local} -symbols, in spite of its name. - -@item -X -@itemx +discard-locals -Discard local symbols starting with @samp{L} from each file in -@var{objfiles}. (Some compilers produce internally-used symbols that -begin with @samp{L}.) - -@item -T @var{bfdname} -@cindex object code format -You can specify a particular object-code format @var{bfdname} for -@var{objfiles}. This may not be necessary; @var{strip} can automatically -recognize many formats. @xref{objdump}, for information on listing -available formats. -@end table - -@node Index, , strip, Top -@unnumbered Index - -@printindex cp - -@contents -@bye |