@copying
@c man begin COPYRIGHT
Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
-2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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.3
@c man title ar create, modify, and extract from archives
@smallexample
-ar [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
+ar [@option{--plugin} @var{name}] [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
ar -M [ <mri-script ]
@end smallexample
@smallexample
@c man begin SYNOPSIS ar
-ar [@option{-X32_64}] [@option{-}]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
+ar [@option{--plugin} @var{name}] [@option{-X32_64}] [@option{-}]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
@c man end
@end smallexample
issued unless you specify in advance that you expect to create it, by
using this modifier.
+@item D
+@cindex deterministic archives
+Operate in @emph{deterministic} mode. When adding files and the archive
+index use zero for UIDs, GIDs, timestamps, and use consistent file modes
+for all files. When this option is used, if @command{ar} is used with
+identical options and identical input files, multiple runs will create
+identical output files regardless of the input files' owners, groups,
+file modes, or modification times.
+
@item f
Truncate names in the archive. @sc{gnu} @command{ar} will normally permit file
names of any length. This will cause it to create archives which are
@samp{-X} options; in particular, it does not support @option{-X32}
which is the default for AIX @command{ar}.
+The optional command line switch @option{--plugin} @var{name} causes
+@command{ar} to load the plugin called @var{name} which adds support
+for more file formats. This option is only available if the toolchain
+has been built with plugin support enabled.
+
@c man end
@ignore
@smallexample
@c man begin SYNOPSIS nm
-nm [@option{-a}|@option{--debug-syms}] [@option{-g}|@option{--extern-only}]
+nm [@option{-a}|@option{--debug-syms}]
+ [@option{-g}|@option{--extern-only}][@option{--plugin} @var{name}]
[@option{-B}] [@option{-C}|@option{--demangle}[=@var{style}]] [@option{-D}|@option{--dynamic}]
[@option{-S}|@option{--print-size}] [@option{-s}|@option{--print-armap}]
[@option{-A}|@option{-o}|@option{--print-file-name}][@option{--special-syms}]
object file formats permit more efficient access to small data objects,
such as a global int variable as opposed to a large global array.
-@item I
-The symbol is an indirect reference to another symbol. This is a @sc{gnu}
-extension to the a.out object file format which is rarely used.
-
@item i
The symbol is in a section specific to the implementation of DLLs.
@cindex external symbols
Display only external symbols.
+@item --plugin @var{name}
+@cindex load plugin
+Load the plugin called @var{name} to add support for extra target
+types. This option is only available if the toolchain has been built
+with plugin support enabled.
+
@item -l
@itemx --line-numbers
@cindex symbol line numbers
@item -S
@itemx --print-size
-Print size, not the value, of defined symbols for the @code{bsd} output format.
+Print both value and size of defined symbols for the @code{bsd} output style.
+This option has no effect for object formats that do not record symbol
+sizes, unless @samp{--size-sort} is also used in which case a
+calculated size is displayed.
@item -s
@itemx --print-armap
[@option{--set-section-flags} @var{section}=@var{flags}]
[@option{--add-section} @var{sectionname}=@var{filename}]
[@option{--rename-section} @var{oldname}=@var{newname}[,@var{flags}]]
+ [@option{--long-section-names} @{enable,disable,keep@}]
[@option{--change-leading-char}] [@option{--remove-leading-char}]
[@option{--reverse-bytes=}@var{num}]
[@option{--srec-len=}@var{ival}] [@option{--srec-forceS3}]
[@option{--readonly-text}]
[@option{--pure}]
[@option{--impure}]
+ [@option{--file-alignment=}@var{num}]
+ [@option{--heap=}@var{size}]
+ [@option{--image-base=}@var{address}]
+ [@option{--section-alignment=}@var{num}]
+ [@option{--stack=}@var{size}]
+ [@option{--subsystem=}@var{which}:@var{major}.@var{minor}]
[@option{-v}|@option{--verbose}]
[@option{-V}|@option{--version}]
[@option{--help}] [@option{--info}]
<input_binary_file> <output_object_file>
@end smallexample
+@item --long-section-names @{enable,disable,keep@}
+Controls the handling of long section names when processing @code{COFF}
+and @code{PE-COFF} object formats. The default behaviour, @samp{keep},
+is to preserve long section names if any are present in the input file.
+The @samp{enable} and @samp{disable} options forcibly enable or disable
+the use of long section names in the output object; when @samp{disable}
+is in effect, any long section names in the input object will be truncated.
+The @samp{enable} option will only emit long section names if any are
+present in the inputs; this is mostly the same as @samp{keep}, but it
+is left undefined whether the @samp{enable} option might force the
+creation of an empty string table in the output file.
+
@item --change-leading-char
Some object file formats use special characters at the start of
symbols. The most common such character is underscore, which compilers
needed if debugging abilities are required. The suggested procedure
to create these files is as follows:
+@item --file-alignment @var{num}
+Specify the file alignment. Sections in the file will always begin at
+file offsets which are multiples of this number. This defaults to
+512.
+[This option is specific to PE targets.]
+
+@item --heap @var{reserve}
+@itemx --heap @var{reserve},@var{commit}
+Specify the number of bytes of memory to reserve (and optionally commit)
+to be used as heap for this program.
+[This option is specific to PE targets.]
+
+@item --image-base @var{value}
+Use @var{value} as the base address of your program or dll. This is
+the lowest memory location that will be used when your program or dll
+is loaded. To reduce the need to relocate and improve performance of
+your dlls, each should have a unique base address and not overlap any
+other dlls. The default is 0x400000 for executables, and 0x10000000
+for dlls.
+[This option is specific to PE targets.]
+
+@item --section-alignment @var{num}
+Sets the section alignment. Sections in memory will always begin at
+addresses which are a multiple of this number. Defaults to 0x1000.
+[This option is specific to PE targets.]
+
+@item --stack @var{reserve}
+@itemx --stack @var{reserve},@var{commit}
+Specify the number of bytes of memory to reserve (and optionally commit)
+to be used as stack for this program.
+[This option is specific to PE targets.]
+
+@item --subsystem @var{which}
+@itemx --subsystem @var{which}:@var{major}
+@itemx --subsystem @var{which}:@var{major}.@var{minor}
+Specifies the subsystem under which your program will execute. The
+legal values for @var{which} are @code{native}, @code{windows},
+@code{console}, @code{posix}, @code{efi-app}, @code{efi-bsd},
+@code{efi-rtd}, @code{sal-rtd}, and @code{xbox}. You may optionally set
+the subsystem version also. Numeric values are also accepted for
+@var{which}.
+[This option is specific to PE targets.]
+
@enumerate
@item Link the executable as normal. Assuming that is is called
@code{foo} then...
[@option{-r}|@option{--reloc}]
[@option{-R}|@option{--dynamic-reloc}]
[@option{-s}|@option{--full-contents}]
- [@option{-W}|@option{--dwarf}]
+ [@option{-W[lLiaprmfFsoR]}|
+ @option{--dwarf}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]]
[@option{-G}|@option{--stabs}]
[@option{-t}|@option{--syms}]
[@option{-T}|@option{--dynamic-syms}]
[@option{--[no-]show-raw-insn}]
[@option{--adjust-vma=}@var{offset}]
[@option{--special-syms}]
+ [@option{--prefix=}@var{prefix}]
+ [@option{--prefix-strip=}@var{level}]
[@option{-V}|@option{--version}]
[@option{-H}|@option{--help}]
@var{objfile}@dots{}
Like @option{-d}, but disassemble the contents of all sections, not just
those expected to contain instructions.
+If the target is an ARM architecture this switch also has the effect
+of forcing the disassembler to decode pieces of data found in code
+sections as if they were instructions.
+
@item --prefix-addresses
When disassembling, print the complete address on each line. This is
the older disassembly format.
architecture information, such as S-records. You can list the available
architectures with the @option{-i} option.
+If the target is an ARM architecture then this switch has an
+additional effect. It restricts the disassembly to only those
+instructions supported by the architecture specified by @var{machine}.
+If it is necessary to use this switch because the input file does not
+contain any architecture information, but it is also desired to
+disassemble all the instructions use @option{-marm}.
+
@item -M @var{options}
@itemx --disassembler-options=@var{options}
Pass target specific information to the disassembler. Only supported on
@cindex dynamic relocation entries, in object file
Print the dynamic relocation entries of the file. This is only
meaningful for dynamic objects, such as certain types of shared
-libraries.
+libraries. As for @option{-r}, if used with @option{-d} or
+@option{-D}, the relocations are printed interspersed with the
+disassembly.
@item -s
@itemx --full-contents
Display source code intermixed with disassembly, if possible. Implies
@option{-d}.
+@item --prefix=@var{prefix}
+@cindex Add prefix to absolute paths
+Specify @var{prefix} to add to the absolute paths when used with
+@option{-S}.
+
+@item --prefix-strip=@var{level}
+@cindex Strip absolute paths
+Indicate how many initial directory names to strip off the hardwired
+absolute paths. It has no effect without @option{--prefix=}@var{prefix}.
+
@item --show-raw-insn
When disassembling instructions, print the instruction in hex as well as
in symbolic form. This is the default except when
When disassembling instructions, do not print the instruction bytes.
This is the default when @option{--prefix-addresses} is used.
-@item -W
-@itemx --dwarf
+@item -W[lLiaprmfFsoR]
+@itemx --dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]
@cindex DWARF
@cindex debug symbols
-Displays the contents of the DWARF debug sections in the file, if any
-are present.
+Displays the contents of the debug sections in the file, if any are
+present. If one of the optional letters or words follows the switch
+then only data found in those specific sections will be dumped.
@item -G
@itemx --stabs
@smallexample
@c man begin SYNOPSIS strings
-strings [@option{-afov}] [@option{-}@var{min-len}]
+strings [@option{-afovV}] [@option{-}@var{min-len}]
[@option{-n} @var{min-len}] [@option{--bytes=}@var{min-len}]
[@option{-t} @var{radix}] [@option{--radix=}@var{radix}]
[@option{-e} @var{encoding}] [@option{--encoding=}@var{encoding}]
@xref{Target Selection}, for more information.
@item -v
+@itemx -V
@itemx --version
Print the program version number on the standard output and exit.
@end table
[@option{-k}|@option{--kill-at}] [@option{-A}|@option{--add-stdcall-alias}]
[@option{-p}|@option{--ext-prefix-alias} @var{prefix}]
[@option{-x}|@option{--no-idata4}] [@option{-c}|@option{--no-idata5}]
- [@option{-I}|@option{--identify} @var{library-file-name}] [@option{-i}|@option{--interwork}]
+ [@option{--use-nul-prefixed-import-tables}]
+ [@option{-I}|@option{--identify} @var{library-file-name}] [@option{--identify-strict}]
+ [@option{-i}|@option{--interwork}]
[@option{-n}|@option{--nodelete}] [@option{-t}|@option{--temp-prefix} @var{prefix}]
[@option{-v}|@option{--verbose}]
[@option{-h}|@option{--help}] [@option{-V}|@option{--version}]
files it should omit the @code{.idata4} section. This is for compatibility
with certain operating systems.
+@item --use-nul-prefixed-import-tables
+Specifies that when @command{dlltool} is creating the exports and library
+files it should prefix the @code{.idata4} and @code{.idata5} by zero an
+element. This emulates old gnu import library generation of
+@code{dlltool}. By default this option is turned off.
+
@item -c
@itemx --no-idata5
Specifies that when @command{dlltool} is creating the exports and library
@item -I @var{filename}
@itemx --identify @var{filename}
Specifies that @command{dlltool} should inspect the import library
-indicated by @var{filename} and report, on @code{stdout}, the name of
-the associated DLL. This can be performed in addition to any other
-operations indicated by the other options and arguments. @command{dlltool}
-@option{--identify} fails if the import library does not exist, is not
-actually an import library, or (rarely) if the import library somehow
-specifies more than one associated DLL.
+indicated by @var{filename} and report, on @code{stdout}, the name(s)
+of the associated DLL(s). This can be performed in addition to any
+other operations indicated by the other options and arguments.
+@command{dlltool} fails if the import library does not exist or is not
+actually an import library. See also @option{--identify-strict}.
+
+@item --identify-strict
+Modifies the behavior of the @option{--identify} option, such
+that an error is reported if @var{filename} is associated with
+more than one DLL.
@item -i
@itemx --interwork
[@option{-D}|@option{--use-dynamic}]
[@option{-x} <number or name>|@option{--hex-dump=}<number or name>]
[@option{-p} <number or name>|@option{--string-dump=}<number or name>]
+ [@option{-R} <number or name>|@option{--relocated-dump=}<number or name>]
[@option{-c}|@option{--archive-index}]
[@option{-w[lLiaprmfFsoR]}|
@option{--debug-dump}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]]
@item -x <number or name>
@itemx --hex-dump=<number or name>
-Displays the contents of the indicated section as a hexadecimal dump.
+Displays the contents of the indicated section as a hexadecimal bytes.
A number identifies a particular section by index in the section table;
any other string identifies all sections with that name in the object file.
+@item -R <number or name>
+@itemx --relocated-dump=<number or name>
+Displays the contents of the indicated section as a hexadecimal
+bytes. A number identifies a particular section by index in the
+section table; any other string identifies all sections with that name
+in the object file. The contents of the section will be relocated
+before they are displayed.
+
@item -p <number or name>
@itemx --string-dump=<number or name>
Displays the contents of the indicated section as printable strings.