diff options
Diffstat (limited to 'binutils/doc/binutils.texi')
| -rw-r--r-- | binutils/doc/binutils.texi | 454 |
1 files changed, 346 insertions, 108 deletions
diff --git a/binutils/doc/binutils.texi b/binutils/doc/binutils.texi index be571d2a7cc9..9499634458d6 100644 --- a/binutils/doc/binutils.texi +++ b/binutils/doc/binutils.texi @@ -1,9 +1,10 @@ \input texinfo @c -*- Texinfo -*- @setfilename binutils.info -@c Copyright 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. +@c Copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007 +@c Free Software Foundation, Inc. @c man begin INCLUDE -@include config.texi +@include bfdver.texi @c man end @ifinfo @@ -24,15 +25,16 @@ START-INFO-DIR-ENTRY * addr2line: (binutils)addr2line. Convert addresses to file and line * nlmconv: (binutils)nlmconv. Converts object code into an NLM * windres: (binutils)windres. Manipulate Windows resources +* windmc: (binutils)windmc. Generator for Windows message resources * dlltool: (binutils)dlltool. Create files needed to build and use DLLs END-INFO-DIR-ENTRY @end format @end ifinfo -@ifinfo +@copying @c man begin COPYRIGHT Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, -2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 @@ -42,23 +44,16 @@ Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. @c man end -@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 -@end ifinfo +@end copying @synindex ky cp @c @c This file documents the GNU binary utilities "ar", "ld", "objcopy", @c "objdump", "nm", "size", "strings", "strip", "readelf" and "ranlib". @c -@c Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, -@c 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. -@c +@c Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, +@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c @c This text may be freely distributed under the terms of the GNU @c Free Documentation License. @c @@ -68,6 +63,9 @@ notice identical to this one except for the removal of this paragraph @titlepage @finalout @title The @sc{gnu} Binary Utilities +@ifset VERSION_PACKAGE +@subtitle @value{VERSION_PACKAGE} +@end ifset @subtitle Version @value{VERSION} @sp 1 @subtitle @value{UPDATED} @@ -83,7 +81,7 @@ notice identical to this one except for the removal of this paragraph @vskip 0pt plus 1filll Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 @@ -93,13 +91,18 @@ Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, section entitled ``GNU Free Documentation License''. @end titlepage +@contents @node Top @top Introduction @cindex version This brief manual contains documentation for the @sc{gnu} binary -utilities (collectively version @value{VERSION}): +utilities +@ifset VERSION_PACKAGE +@value{VERSION_PACKAGE} +@end ifset +version @value{VERSION}: @iftex @table @code @@ -143,6 +146,9 @@ Convert object code into a Netware Loadable Module @item windres Manipulate Windows resources +@item windmc +Genertor for Windows message resources + @item dlltool Create the files needed to build and use Dynamic Link Libraries @end table @@ -167,12 +173,13 @@ section entitled "GNU Free Documentation License". * addr2line:: Convert addresses to file and line * nlmconv:: Converts object code into an NLM * windres:: Manipulate Windows resources +* windmc:: Generator for Windows message resources * dlltool:: Create files needed to build and use DLLs * Common Options:: Command-line options for all utilities * Selecting The Target System:: How these utilities determine the target. * Reporting Bugs:: Reporting Bugs * GNU Free Documentation License:: GNU Free Documentation License -* Index:: Index +* Binutils Index:: Binutils Index @end menu @node ar @@ -198,7 +205,7 @@ 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 can be restored on -extraction. +extraction. @cindex name length @sc{gnu} @command{ar} can maintain archives whose members have names of any @@ -289,7 +296,7 @@ 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. +than one member. If no modifiers are used with @code{m}, any members you name in the @var{member} arguments are moved to the @emph{end} of the archive; @@ -413,7 +420,7 @@ member must be present as the @var{relpos} argument, before the @item l This modifier is accepted but not used. @c whaffor ar l modifier??? presumably compat; with -@c what???---doc@@cygnus.com, 25jan91 +@c what???---doc@@cygnus.com, 25jan91 @item N Uses the @var{count} parameter. This is used if there are multiple @@ -546,7 +553,7 @@ to @code{SAVE}, commands affect only the temporary copy of the current archive. @table @code -@item ADDLIB @var{archive} +@item ADDLIB @var{archive} @itemx ADDLIB @var{archive} (@var{module}, @var{module}, @dots{} @var{module}) Add all the contents of @var{archive} (or, if specified, each named @var{module} from @var{archive}) to the current archive. @@ -627,7 +634,7 @@ will not actually affect @var{archive} until you next use @code{SAVE}. In the current archive, replace each existing @var{module} (named in the @code{REPLACE} arguments) from files in the current working directory. To execute this command without errors, both the file, and the module in -the current archive, must exist. +the current archive, must exist. Requires prior use of @code{OPEN} or @code{CREATE}. @@ -639,7 +646,7 @@ When the flag is on, @code{DIRECTORY} output matches output from @item SAVE Commit your changes to the current archive, and actually save it as a file with the name specified in the last @code{CREATE} or @code{OPEN} -command. +command. Requires prior use of @code{OPEN} or @code{CREATE}. @@ -752,7 +759,7 @@ weak object symbol. When a weak defined symbol is linked with a normal defined symbol, the normal defined symbol is used with no error. When a weak undefined symbol is linked and the symbol is not defined, the value of the symbol is determined in a system-specific manner without -error. On some systems, uppercase indicates that a default value has been +error. On some systems, uppercase indicates that a default value has been specified. @@ -782,7 +789,7 @@ equivalent. @table @env @item -A @itemx -o -@itemx --print-file-name +@itemx --print-file-name @cindex input file name @cindex file name @cindex source file name @@ -791,7 +798,7 @@ in which it was found, rather than identifying the input file once only, before all of its symbols. @item -a -@itemx --debug-syms +@itemx --debug-syms @cindex debugging symbols Display all symbols, even debugger-only symbols; normally these are not listed. @@ -807,8 +814,8 @@ The same as @option{--format=bsd} (for compatibility with the MIPS @command{nm}) Decode (@dfn{demangle}) low-level symbol names into user-level names. Besides removing any initial underscore prepended by the system, this makes C++ function names readable. Different compilers have different -mangling styles. The optional demangling style argument can be used to -choose an appropriate demangling style for your compiler. @xref{c++filt}, +mangling styles. The optional demangling style argument can be used to +choose an appropriate demangling style for your compiler. @xref{c++filt}, for more information on demangling. @item --no-demangle @@ -831,7 +838,7 @@ Only the first character of @var{format} is significant; it can be either upper or lower case. @item -g -@itemx --extern-only +@itemx --extern-only @cindex external symbols Display only external symbols. @@ -846,12 +853,12 @@ information can be found, print it after the other symbol information. @item -n @itemx -v -@itemx --numeric-sort +@itemx --numeric-sort Sort symbols numerically by their addresses, rather than alphabetically -by their names. +by their names. @item -p -@itemx --no-sort +@itemx --no-sort @cindex sorting symbols Do not bother to sort the symbols in any order; print them in the order encountered. @@ -873,15 +880,15 @@ When listing symbols from archive members, include the index: a mapping contain definitions for which names. @item -r -@itemx --reverse-sort +@itemx --reverse-sort Reverse the order of the sort (whether numeric or alphabetic); let the last come first. @item --size-sort Sort symbols by size. The size is computed as the difference between the value of the symbol and the value of the symbol with the next higher -value. If the @code{bsd} output format is used the size of the symbol -is printed, rather than the value, and @samp{-S} must be used in order +value. If the @code{bsd} output format is used the size of the symbol +is printed, rather than the value, and @samp{-S} must be used in order both size and value to be printed. @item --special-syms @@ -889,7 +896,7 @@ Display symbols which have a target-specific special meaning. These symbols are usually used by the target for some special processing and are not normally helpful when included included in the normal symbol lists. For example for ARM targets this option would skip the mapping -symbols used to mark transistions between ARM code, THUMB code and +symbols used to mark transitions between ARM code, THUMB code and data. @item -t @var{radix} @@ -903,7 +910,7 @@ Specify an object code format other than your system's default format. @xref{Target Selection}, for more information. @item -u -@itemx --undefined-only +@itemx --undefined-only @cindex external symbols @cindex undefined symbols Display only undefined symbols (those external to each object file). @@ -952,6 +959,7 @@ objcopy [@option{-F} @var{bfdname}|@option{--target=}@var{bfdname}] [@option{-N} @var{symbolname}|@option{--strip-symbol=}@var{symbolname}] [@option{--strip-unneeded-symbol=}@var{symbolname}] [@option{-G} @var{symbolname}|@option{--keep-global-symbol=}@var{symbolname}] + [@option{--localize-hidden}] [@option{-L} @var{symbolname}|@option{--localize-symbol=}@var{symbolname}] [@option{--globalize-symbol=}@var{symbolname}] [@option{-W} @var{symbolname}|@option{--weaken-symbol=}@var{symbolname}] @@ -977,6 +985,7 @@ objcopy [@option{-F} @var{bfdname}|@option{--target=}@var{bfdname}] [@option{--add-section} @var{sectionname}=@var{filename}] [@option{--rename-section} @var{oldname}=@var{newname}[,@var{flags}]] [@option{--change-leading-char}] [@option{--remove-leading-char}] + [@option{--reverse-bytes=}@var{num}] [@option{--srec-len=}@var{ival}] [@option{--srec-forceS3}] [@option{--redefine-sym} @var{old}=@var{new}] [@option{--redefine-syms=}@var{filename}] @@ -995,12 +1004,13 @@ objcopy [@option{-F} @var{bfdname}|@option{--target=}@var{bfdname}] [@option{--add-gnu-debuglink=}@var{path-to-file}] [@option{--keep-file-symbols}] [@option{--only-keep-debug}] + [@option{--extract-symbol}] [@option{--writable-text}] [@option{--readonly-text}] [@option{--pure}] [@option{--impure}] [@option{-v}|@option{--verbose}] - [@option{-V}|@option{--version}] + [@option{-V}|@option{--version}] [@option{--help}] [@option{--info}] @var{infile} [@var{outfile}] @c man end @@ -1041,6 +1051,7 @@ Note---@command{objcopy} is not able to change the endianness of its input files. If the input format has an endianness (some formats do not), @command{objcopy} can only copy the inputs into file formats that have the same endianness or which have no endianness (e.g., @samp{srec}). +(However, see the @option{--reverse-bytes} option.) @c man end @@ -1079,7 +1090,7 @@ can access this binary data inside a program by referencing the special symbols that are created by the conversion process. These symbols are called _binary_@var{objfile}_start, _binary_@var{objfile}_end and _binary_@var{objfile}_size. e.g. you can transform a picture file into -an object file and then access it in your code using these symbols. +an object file and then access it in your code using these symbols. @item -j @var{sectionname} @itemx --only-section=@var{sectionname} @@ -1124,6 +1135,11 @@ Keep only symbol @var{symbolname} global. Make all other symbols local to the file, so that they are not visible externally. This option may be given more than once. +@item --localize-hidden +In an ELF object, mark all symbols that have hidden or internal visibility +as local. This option applies on top of symbol-specific localization options +such as @option{-L}. + @item -L @var{symbolname} @itemx --localize-symbol=@var{symbolname} Make symbol @var{symbolname} local to the file, so that it is not @@ -1219,7 +1235,7 @@ address, by adding @var{incr}. Some object file formats do not permit section addresses to be changed arbitrarily. Note that this does not relocate the sections; if the program expects sections to be loaded at a certain address, and this option is used to change the sections such -that they are loaded at a different address, the program may fail. +that they are loaded at a different address, the program may fail. @item --change-section-address @var{section}@{=,+,-@}@var{val} @itemx --adjust-section-vma @var{section}@{=,+,-@}@var{val} @@ -1242,7 +1258,7 @@ different. If @samp{=} is used, the section address is set to @var{val}. Otherwise, @var{val} is added to or subtracted from the section address. See the comments under @option{--change-addresses}, above. If @var{section} does not exist in the input file, a warning -will be issued, unless @option{--no-change-warnings} is used. +will be issued, unless @option{--no-change-warnings} is used. @item --change-section-vma @var{section}@{=,+,-@}@var{val} @cindex changing section VMA @@ -1256,19 +1272,19 @@ is set to @var{val}. Otherwise, @var{val} is added to or subtracted from the section address. See the comments under @option{--change-addresses}, above. If @var{section} does not exist in the input file, a warning will be issued, unless -@option{--no-change-warnings} is used. +@option{--no-change-warnings} is used. @item --change-warnings @itemx --adjust-warnings If @option{--change-section-address} or @option{--change-section-lma} or @option{--change-section-vma} is used, and the named section does not -exist, issue a warning. This is the default. +exist, issue a warning. This is the default. @item --no-change-warnings @itemx --no-adjust-warnings Do not issue a warning if @option{--change-section-address} or @option{--adjust-section-lma} or @option{--adjust-section-vma} is used, even -if the named section does not exist. +if the named section does not exist. @item --set-section-flags @var{section}=@var{flags} Set the flags for the named section. The @var{flags} argument is a @@ -1326,13 +1342,37 @@ different conventions for symbol names. This is different from when appropriate, regardless of the object file format of the output file. +@item --reverse-bytes=@var{num} +Reverse the bytes in a section with output contents. A section length must +be evenly divisible by the value given in order for the swap to be able to +take place. Reversing takes place before the interleaving is performed. + +This option is used typically in generating ROM images for problematic +target systems. For example, on some target boards, the 32-bit words +fetched from 8-bit ROMs are re-assembled in little-endian byte order +regardless of the CPU byte order. Depending on the programming model, the +endianness of the ROM may need to be modified. + +Consider a simple file with a section containing the following eight +bytes: @code{12345678}. + +Using @samp{--reverse-bytes=2} for the above example, the bytes in the +output file would be ordered @code{21436587}. + +Using @samp{--reverse-bytes=4} for the above example, the bytes in the +output file would be ordered @code{43218765}. + +By using @samp{--reverse-bytes=2} for the above example, followed by +@samp{--reverse-bytes=4} on the output file, the bytes in the second +output file would be ordered @code{34127856}. + @item --srec-len=@var{ival} Meaningful only for srec output. Set the maximum length of the Srecords being produced to @var{ival}. This length covers both address, data and crc fields. @item --srec-forceS3 -Meaningful only for srec output. Avoid generation of S1/S2 records, +Meaningful only for srec output. Avoid generation of S1/S2 records, creating S3-only record format. @item --redefine-sym @var{old}=@var{new} @@ -1397,7 +1437,7 @@ This option may be given more than once. @item --alt-machine-code=@var{index} If the output architecture has alternate machine codes, use the @var{index}th code instead of the default one. This is useful in case -a machine is assigned an official code and the tool-chain adopts the +a machine is assigned an official code and the tool-chain adopts the new code, but other applications still depend on the original code being used. For ELF based architectures if the @var{index} alternative does not exist then the value is treated as an absolute @@ -1441,7 +1481,7 @@ which would otherwise get stripped. @item --only-keep-debug Strip a file, removing contents of any sections that would not be stripped by @option{--strip-debug} and leaving the debugging sections -intact. +intact. In ELF files, this preserves all note sections in the output. The intention is that this option will be used in conjunction with @option{--add-gnu-debuglink} to create a two part executable. One a @@ -1472,10 +1512,32 @@ optional. You could instead do this: @item Run @code{objcopy --add-gnu-debuglink=foo.full foo} @end enumerate -i.e. the file pointed to by the @option{--add-gnu-debuglink} can be the +i.e., the file pointed to by the @option{--add-gnu-debuglink} can be the full executable. It does not have to be a file created by the @option{--only-keep-debug} switch. +Note - this switch is only intended for use on fully linked files. It +does not make sense to use it on object files where the debugging +information may be incomplete. Besides the gnu_debuglink feature +currently only supports the presence of one filename containing +debugging information, not multiple filenames on a one-per-object-file +basis. + +@item --extract-symbol +Keep the file's section flags and symbols but remove all section data. +Specifically, the option: + +@itemize +@item sets the virtual and load addresses of every section to zero; +@item removes the contents of all sections; +@item sets the size of every section to zero; and +@item sets the file's start address to zero. +@end itemize + +This option is used to build a @file{.sym} file for a VxWorks kernel. +It can also be a useful way of reducing the size of a @option{--just-symbols} +linker input file. + @item -V @itemx --version Show the version number of @command{objcopy}. @@ -1612,8 +1674,8 @@ formats available with the @option{-i} option. Decode (@dfn{demangle}) low-level symbol names into user-level names. Besides removing any initial underscore prepended by the system, this makes C++ function names readable. Different compilers have different -mangling styles. The optional demangling style argument can be used to -choose an appropriate demangling style for your compiler. @xref{c++filt}, +mangling styles. The optional demangling style argument can be used to +choose an appropriate demangling style for your compiler. @xref{c++filt}, for more information on demangling. @item -g @@ -1747,7 +1809,7 @@ switch, but allow finer grained control. Multiple selections from the following may be specified as a comma separated string. @option{x86-64}, @option{i386} and @option{i8086} select disassembly for the given architecture. @option{intel} and @option{att} select between -intel syntax mode and AT&T syntax mode. @option{addr32}, +intel syntax mode and AT&T syntax mode. @option{addr64}, @option{addr32}, @option{addr16}, @option{data32} and @option{data16} specify the default address size and operand size. These four options will be overridden if @option{x86-64}, @option{i386} or @option{i8086} appear later in the @@ -1758,17 +1820,18 @@ suffix could be inferred by the operands. For PPC, @option{booke}, @option{booke32} and @option{booke64} select disassembly of BookE instructions. @option{32} and @option{64} select PowerPC and PowerPC64 disassembly, respectively. @option{e300} selects -disassembly for the e300 family. +disassembly for the e300 family. @option{440} selects disassembly for +the PowerPC 440. -For MIPS, this option controls the printing of instruction mneumonic +For MIPS, this option controls the printing of instruction mnemonic names and register names in disassembled instructions. Multiple selections from the following may be specified as a comma separated string, and invalid options are ignored: @table @code @item no-aliases -Print the 'raw' instruction mneumonic instead of some pseudo -instruction mneumonic. I.E. print 'daddu' or 'or' instead of 'move', +Print the 'raw' instruction mnemonic instead of some pseudo +instruction mnemonic. I.e., print 'daddu' or 'or' instead of 'move', 'sll' instead of 'nop', etc. @item gpr-names=@var{ABI} @@ -1811,7 +1874,7 @@ For VAX, you can specify function entry addresses with @option{-M entry:0xf00ba}. You can use this multiple times to properly disassemble VAX binary files that don't contain symbol tables (like ROM dumps). In these cases, the function entry mask would otherwise -be decoded as VAX instructions, which would probably lead the the rest +be decoded as VAX instructions, which would probably lead the rest of the function being wrongly disassembled. @item -p @@ -1963,7 +2026,7 @@ ranlib [@option{-vV}] @var{archive} @command{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. +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. @@ -2008,7 +2071,7 @@ size [@option{-A}|@option{-B}|@option{--format=}@var{compatibility}] [@option{--help}] [@option{-d}|@option{-o}|@option{-x}|@option{--radix=}@var{number}] [@option{-t}|@option{--totals}] - [@option{--target=}@var{bfdname}] [@option{-V}|@option{--version}] + [@option{--target=}@var{bfdname}] [@option{-V}|@option{--version}] [@var{objfile}@dots{}] @c man end @end smallexample @@ -2038,13 +2101,13 @@ Using one of these options, you can choose whether the output from @sc{gnu} @command{size} resembles output from System V @command{size} (using @option{-A}, or @option{--format=sysv}), or Berkeley @command{size} (using @option{-B}, or @option{--format=berkeley}). The default is the one-line format similar to -Berkeley's. +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 -@command{size}: +@command{size}: @smallexample $ size --format=Berkeley ranlib size text data bss dec hex filename @@ -2059,18 +2122,18 @@ This is the same data, but displayed closer to System V conventions: $ size --format=SysV ranlib size ranlib : section size addr -.text 294880 8192 -.data 81920 303104 -.bss 11592 385024 -Total 388392 +.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 +.text 294880 8192 +.data 81920 303104 +.bss 11888 385024 +Total 388688 @end smallexample @item --help @@ -2130,7 +2193,7 @@ strings [@option{-afov}] [@option{-}@var{min-len}] [@option{-t} @var{radix}] [@option{--radix=}@var{radix}] [@option{-e} @var{encoding}] [@option{--encoding=}@var{encoding}] [@option{-}] [@option{--all}] [@option{--print-file-name}] - [@option{--target=}@var{bfdname}] + [@option{-T} @var{bfdname}] [@option{--target=}@var{bfdname}] [@option{--help}] [@option{--version}] @var{file}@dots{} @c man end @end smallexample @@ -2191,7 +2254,8 @@ single-8-bit-byte characters, @samp{b} = 16-bit bigendian, @samp{l} = 16-bit littleendian, @samp{B} = 32-bit bigendian, @samp{L} = 32-bit littleendian. Useful for finding wide character strings. -@item --target=@var{bfdname} +@item -T @var{bfdname} +@itemx --target=@var{bfdname} @cindex object code format Specify an object code format other than your system's default format. @xref{Target Selection}, for more information. @@ -2348,8 +2412,9 @@ When stripping a file, perhaps with @option{--strip-debug} or which would otherwise get stripped. @item --only-keep-debug -Strip a file, removing any sections that would be stripped by -@option{--strip-debug} and leaving the debugging sections. +Strip a file, removing contents of any sections that would not be +stripped by @option{--strip-debug} and leaving the debugging sections +intact. In ELF files, this preserves all note sections in the output. The intention is that this option will be used in conjunction with @option{--add-gnu-debuglink} to create a two part executable. One a @@ -2384,6 +2449,13 @@ ie the file pointed to by the @option{--add-gnu-debuglink} can be the full executable. It does not have to be a file created by the @option{--only-keep-debug} switch. +Note - this switch is only intended for use on fully linked files. It +does not make sense to use it on object files where the debugging +information may be incomplete. Besides the gnu_debuglink feature +currently only supports the presence of one filename containing +debugging information, not multiple filenames on a one-per-object-file +basis. + @item -V @itemx --version Show the version number for @command{strip}. @@ -2432,7 +2504,7 @@ able to distinguish these similarly named functions C++ and Java encode them into a low-level assembler name which uniquely identifies each different version. This process is known as @dfn{mangling}. The @command{c++filt} -@footnote{MS-DOS does not allow @kbd{+} characters in file names, so on +@footnote{MS-DOS does not allow @kbd{+} characters in file names, so on MS-DOS this program is named @command{CXXFILT}.} program does the inverse mapping: it decodes (@dfn{demangles}) low-level names into user-level names so that they can be read. @@ -2457,7 +2529,7 @@ names from the standard input instead. All the results are printed on the standard output. The difference between reading names from the command line versus reading names from the standard input is that command line arguments are expected to be just mangled names and no -checking is performed to seperate them from surrounding text. Thus +checking is performed to separate them from surrounding text. Thus for example: @smallexample @@ -2571,8 +2643,8 @@ the Info entries for @file{binutils}. @quotation @emph{Warning:} @command{c++filt} is a new utility, and the details of its user interface are subject to change in future releases. In particular, -a command-line option may be required in the the future to decode a name -passed as an argument on the command line; in other words, +a command-line option may be required in the future to decode a name +passed as an argument on the command line; in other words, @example c++filt @var{symbol} @@ -2659,8 +2731,8 @@ Specify that the object-code format for the object files is Decode (@dfn{demangle}) low-level symbol names into user-level names. Besides removing any initial underscore prepended by the system, this makes C++ function names readable. Different compilers have different -mangling styles. The optional demangling style argument can be used to -choose an appropriate demangling style for your compiler. @xref{c++filt}, +mangling styles. The optional demangling style argument can be used to +choose an appropriate demangling style for your compiler. @xref{c++filt}, for more information on demangling. @item -e @var{filename} @@ -2803,6 +2875,168 @@ the Info entries for @file{binutils}. @c man end @end ignore +@node windmc +@chapter windmc + +@command{windmc} may be used to generator Windows message resources. + +@quotation +@emph{Warning:} @command{windmc} is not always built as part of the binary +utilities, since it is only useful for Windows targets. +@end quotation + +@c man title windmc generates Windows message resources. + +@smallexample +@c man begin SYNOPSIS windres +windmc [options] input-file +@c man end +@end smallexample + +@c man begin DESCRIPTION windmc + +@command{windmc} reads message definitions from an input file (.mc) and +translate them into a set of output files. The output files may be of +four kinds: + +@table @code +@item h +A C header file containing the message definitions. + +@item rc +A resource file compilable by the @command{windres} tool. + +@item bin +One or more binary files containing the resource data for a specific +message language. + +@item dbg +A C include file that maps message id's to their symbolic name. +@end table + +The exact description of these different formats is available in +documentation from Microsoft. + +When @command{windmc} converts from the @code{mc} format to the @code{bin} +format, @code{rc}, @code{h}, and optional @code{dbg} it is acting like the +Windows Message Compiler. + +@c man end + +@c man begin OPTIONS windmc + +@table @env +@item -a +@itemx --ascii_in +Specifies that the input file specified is ANSI. This is the default +behaviour. + +@item -A +@itemx --ascii_out +Specifies that messages in the output @code{bin} files should be in ANSI +format. + +@item -b +@itemx --binprefix +Specifies that @code{bin} filenames should have to be prefixed by the +basename of the source file. + +@item -c +@itemx --customflag +Sets the customer bit in all message id's. + +@item -C @var{codepage} +@itemx --codepage_in @var{codepage} +Sets the default codepage to be used to convert input file to UTF16. The +default is ocdepage 1252. + +@item -d +@itemx --decimal_values +Outputs the constants in the header file in decimal. Default is using +hexadecimal output. + +@item -e @var{ext} +@itemx --extension @var{ext} +The extension for the header file. The default is .h extension. + +@item -F @var{target} +@itemx --target @var{target} +Specify the BFD format to use for a bin file as output. This +is a BFD target name; you can use the @option{--help} option to see a list +of supported targets. Normally @command{windmc} will use the default +format, which is the first one listed by the @option{--help} option. +@ifclear man +@ref{Target Selection}. +@end ifclear + +@item -h @var{path} +@itemx --headerdir @var{path} +The target directory of the generated header file. The default is the +current directory. + +@item -H +@itemx --help +Displays a list of command line options and then exits. + +@item -m @var{characters} +@itemx --maxlength @var{characters} +Instructs @command{windmc} to generate a warning if the length +of any message exceeds the number specified. + +@item -n +@itemx --nullterminate +Terminate message text in @code{bin} files by zero. By default they are +terminated by CR/LF. + +@item -o +@itemx --hresult_use +Not yet implemented. Instructs @code{windmc} to generate an OLE2 header +file, using HRESULT definitions. Status codes are used if the flag is not +specified. + +@item -O @var{codepage} +@itemx --codepage_out @var{codepage} +Sets the default codepage to be used to output text files. The default +is ocdepage 1252. + +@item -r @var{path} +@itemx --rcdir @var{path} +The target directory for the generated @code{rc} script and the generated +@code{bin} files that the resource compiler script includes. The default +is the current directory. + +@item -u +@itemx --unicode_in +Specifies that the input file is UTF16. + +@item -U +@itemx --unicode_out +Specifies that messages in the output @code{bin} file should be in UTF16 +format. This is the default behaviour. + +@item -v +@item --verbose +Enable verbose mode. This tells you what the preprocessor is if you +didn't specify one. + +@item -V +@item --version +Prints the version number for @command{windres}. + +@item -x @var{path} +@itemx --xdgb @var{path} +The path of the @code{dbg} C include file that maps message id's to the +symbolic name. No such file is generated without specifying the switch. +@end table + +@c man end + +@ignore +@c man begin SEEALSO windmc +the Info entries for @file{binutils}. +@c man end +@end ignore + @node windres @chapter windres @@ -2885,7 +3119,7 @@ The name of the output file. If this option is not used, then for the input file name, as the output file name. If there is no non-option argument, then @command{windres} will write to standard output. @command{windres} can not write a COFF file to standard output. Note, -for compatability with @command{rc} the option @option{-fo} is also +for compatibility with @command{rc} the option @option{-fo} is also accepted, but its use is not recommended. @item -J @var{format} @@ -2922,7 +3156,7 @@ Specify an include directory to use when reading an @code{rc} file. @command{windres} will pass this to the preprocessor as an @option{-I} option. @command{windres} will also search this directory when looking for files named in the @code{rc} file. If the argument passed to this command -matches any of the supported @var{formats} (as descrived in the @option{-J} +matches any of the supported @var{formats} (as described in the @option{-J} option), it will issue a deprecation warning, and behave just like the @option{-J} option. New programs should not use this behaviour. If a directory happens to match a @var{format}, simple prefix it with @samp{./} @@ -2945,6 +3179,13 @@ Ignored for compatibility with rc. Enable verbose mode. This tells you what the preprocessor is if you didn't specify one. +@item -c @var{val} +@item --codepage @var{val} +Specify the default codepage to use when reading an @code{rc} file. +@var{val} should be a hexadecimal prefixed by @samp{0x} or decimal +codepage code. The valid range is from zero up to 0xffff, but the +validity of the codepage is host and configuration dependent. + @item -l @var{val} @item --language @var{val} Specify the default language to use when reading an @code{rc} file. @@ -2953,8 +3194,8 @@ the language, and the high eight bits are the sublanguage. @item --use-temp-file Use a temporary file to instead of using popen to read the output of -the preprocessor. Use this option if the popen implementation is buggy -on the host (eg., certain non-English language versions of Windows 95 and +the preprocessor. Use this option if the popen implementation is buggy +on the host (eg., certain non-English language versions of Windows 95 and Windows 98 are known to have buggy popen where the output will instead go the console). @@ -3013,7 +3254,7 @@ dlltool [@option{-d}|@option{--input-def} @var{def-file-name}] [@option{-b}|@option{--base-file} @var{base-file-name}] [@option{-e}|@option{--output-exp} @var{exports-file-name}] [@option{-z}|@option{--output-def} @var{def-file-name}] - [@option{-l}|@option{--output-lib} @var{library-file-name}] + [@option{-l}|@option{--output-lib} @var{library-file-name}] [@option{--export-all-symbols}] [@option{--no-export-all-symbols}] [@option{--exclude-symbols} @var{list}] [@option{--no-default-excludes}] @@ -3025,7 +3266,7 @@ dlltool [@option{-d}|@option{--input-def} @var{def-file-name}] [@option{-p}|@option{--ext-prefix-alias} @var{prefix}] [@option{-x}|@option{--no-idata4}] [@option{-c}|@option{--no-idata5}] [@option{-i}|@option{--interwork}] [@option{-n}|@option{--nodelete}] [@option{-t}|@option{--temp-prefix} @var{prefix}] - [@option{-v}|@option{--verbose}] + [@option{-v}|@option{--verbose}] [@option{-h}|@option{--help}] [@option{-V}|@option{--version}] [object-file @dots{}] @c man end @@ -3038,8 +3279,8 @@ dlltool [@option{-d}|@option{--input-def} @var{def-file-name}] line. It then processes these inputs and if the @option{-e} option has been specified it creates a exports file. If the @option{-l} option has been specified it creates a library file and if the @option{-z} option -has been specified it creates a def file. Any or all of the @option{-e}, -@option{-l} and @option{-z} options can be present in one invocation of +has been specified it creates a def file. Any or all of the @option{-e}, +@option{-l} and @option{-z} options can be present in one invocation of dlltool. When creating a DLL, along with the source for the DLL, it is necessary @@ -3060,7 +3301,7 @@ section of the object file. This can be done in C by using the asm() operator: @smallexample - asm (".section .drectve"); + asm (".section .drectve"); asm (".ascii \"-export:my_func\""); int my_func (void) @{ @dots{} @} @@ -3070,7 +3311,7 @@ The second file needed for DLL creation is an exports file. This file is linked with the object files that make up the body of the DLL and it handles the interface between the DLL and the outside world. This is a binary file and it can be created by giving the @option{-e} option to -@command{dlltool} when it is creating or reading in a @file{.def} file. +@command{dlltool} when it is creating or reading in a @file{.def} file. The third file needed for DLL creation is the library file that programs will link with in order to access the functions in the DLL. This file @@ -3192,12 +3433,12 @@ contents of the DLL are actually encode using Thumb instructions. Specifies that when @command{dlltool} is creating the exports file it should add a section which allows the exported functions to be referenced without using the import library. Whatever the hell that -means! +means! @item -U @itemx --add-underscore Specifies that when @command{dlltool} is creating the exports file it -should prepend an underscore to the names of @emph{all} exported symbols. +should prepend an underscore to the names of @emph{all} exported symbols. @item --add-stdcall-underscore Specifies that when @command{dlltool} is creating the exports file it @@ -3254,7 +3495,7 @@ file. @itemx --temp-prefix @var{prefix} Makes @command{dlltool} use @var{prefix} when constructing the names of temporary assembler and object files. By default, the temp file prefix -is generated from the pid. +is generated from the pid. @item -v @itemx --verbose @@ -3339,7 +3580,7 @@ The Info pages for @file{binutils}. @smallexample @c man begin SYNOPSIS readelf -readelf [@option{-a}|@option{--all}] +readelf [@option{-a}|@option{--all}] [@option{-h}|@option{--file-header}] [@option{-l}|@option{--program-headers}|@option{--segments}] [@option{-S}|@option{--section-headers}|@option{--sections}] @@ -3384,15 +3625,15 @@ affected. The long and short forms of options, shown here as alternatives, are equivalent. At least one option besides @samp{-v} or @samp{-H} must be -given. +given. @table @env @item -a @itemx --all -Equivalent to specifiying @option{--file-header}, +Equivalent to specifying @option{--file-header}, @option{--program-headers}, @option{--sections}, @option{--symbols}, @option{--relocs}, @option{--dynamic}, @option{--notes} and -@option{--version-info}. +@option{--version-info}. @item -h @itemx --file-header @@ -3564,8 +3805,8 @@ once because some of them can only be configured @dfn{native} (on hosts with the same type as the target system). @menu -* Target Selection:: -* Architecture Selection:: +* Target Selection:: +* Architecture Selection:: @end menu @node Target Selection @@ -3746,8 +3987,10 @@ You can find contact information for many support companies and individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs distribution. +@ifset BUGURL In any event, we also recommend that you send bug reports for the binary -utilities to @samp{bug-binutils@@gnu.org}. +utilities to @value{BUGURL}. +@end ifset The fundamental principle of reporting bugs usefully is this: @strong{report all the facts}. If you are not sure whether to state a @@ -3806,11 +4049,7 @@ and then we might not encounter the bug. @item A complete input file, or set of input files, that will reproduce the bug. If the utility is reading an object file or files, then it is -generally most helpful to send the actual object files, uuencoded if -necessary to get them through the mail system. Note that -@samp{bug-binutils@@gnu.org} is a mailing list, so you should avoid -sending very large files to it. Making the files available for -anonymous FTP is OK. +generally most helpful to send the actual object files. If the source files were produced exclusively using @sc{gnu} programs (e.g., @command{gcc}, @command{gas}, and/or the @sc{gnu} @command{ld}), then it @@ -3830,7 +4069,7 @@ a chance to make a mistake. Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as your -copy of the utility is out of synch, or you have encountered a bug in +copy of the utility is out of sync, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and ours would not. If you told us to expect a crash, then when ours fails to crash, we would know that the bug was not happening for @@ -3898,10 +4137,9 @@ things without first using the debugger to find the facts. @include fdl.texi -@node Index -@unnumbered Index +@node Binutils Index +@unnumbered Binutils Index @printindex cp -@contents @bye |