@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1991-2018 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2020 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}] [@option{--plugin} @var{name}] [@option{--target} @var{bfdname}] [@var{relpos}] [@var{count}] @var{archive} [@var{member}@dots{}]
+ar [-]@var{p}[@var{mod}] [@option{--plugin} @var{name}] [@option{--target} @var{bfdname}] [@option{--output} @var{dirname}] [@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}] [@option{--plugin} @var{name}] [@option{--target} @var{bfdname}] [@var{relpos}] [@var{count}] @var{archive} [@var{member}@dots{}]
+ar [@option{-X32_64}] [@option{-}]@var{p}[@var{mod}] [@option{--plugin} @var{name}] [@option{--target} @var{bfdname}] [@option{--output} @var{dirname}] [@var{relpos}] [@var{count}] @var{archive} [@var{member}@dots{}]
@c man end
@end smallexample
If you do not specify a @var{member}, all files in the archive
are extracted.
-Files cannot be extracted from a thin archive.
+Files cannot be extracted from a thin archive, and there are
+restrictions on extracting from archives created with @option{P}: The
+paths must not be absolute, may not contain @code{..}, and any
+subdirectories in the paths must exist. If it is desired to avoid
+these restrictions then used the @option{--output} option to specify
+an output directory.
@end table
A number of modifiers (@var{mod}) may immediately follow the @var{p}
option.
@item P
-Use the full path name when matching names in the archive. @sc{gnu}
-@command{ar} can not create an archive with a full path name (such archives
-are not POSIX complaint), but other archive creators can. This option
-will cause @sc{gnu} @command{ar} to match file names using a complete path
-name, which can be convenient when extracting a single file from an
-archive created by another tool.
+Use the full path name when matching or storing names in the archive.
+Archives created with full path names are not POSIX compliant, and
+thus may not work with tools other than up to date @sc{gnu} tools.
+Modifying such archives with @sc{gnu} @command{ar} without using
+@option{P} will remove the full path names unless the archive is a
+thin archive. Note that @option{P} may be useful when adding files to
+a thin archive since @option{r} without @option{P} ignores the path
+when choosing which element to replace. Thus
+@smallexample
+ar rcST archive.a subdir/file1 subdir/file2 file1
+@end smallexample
+will result in the first @code{subdir/file1} being replaced with
+@code{file1} from the current directory. Adding @option{P} will
+prevent this replacement.
@item s
@cindex writing archive index
Displays the version information of @command{ar} and then exits.
@item -X32_64
-@command{ar} ignores an initial option spelt @samp{-X32_64}, for
+@command{ar} ignores an initial option spelled @samp{-X32_64}, for
compatibility with AIX. The behaviour produced by this option is the
default for @sc{gnu} @command{ar}. @command{ar} does not support any
of the other @samp{-X} options; in particular, it does not support
specifies that the archive members are in an object code format
different from your system's default format. See
@xref{Target Selection}, for more information.
+
+@item --output @var{dirname}
+The @option{--output} option can be used to specify a path to a
+directory into which archive members should be extracted. If this
+option is not specified then the current directory will be used.
+
+Note - although the presence of this option does imply a @option{x}
+extraction operation that option must still be included on the command
+line.
+
@end table
@c man end
@item N
The symbol is a debugging symbol.
+@item n
+The symbol is in the read-only data section.
+
@item p
-The symbols is in a stack unwind section.
+The symbol is in a stack unwind section.
@item R
@itemx r
an inifinite level of recursion it is possible to create strings whose
decoding will exhaust the amount of stack space available on the host
machine, triggering a memory fault. The limit tries to prevent this
-from happening by restricting recursion to 1024 levels of nesting.
+from happening by restricting recursion to 2048 levels of nesting.
The default is for this limit to be enabled, but disabling it may be
necessary in order to demangle truly complicated names. Note however
[@option{--interleave-width=}@var{width}]
[@option{-j} @var{sectionpattern}|@option{--only-section=}@var{sectionpattern}]
[@option{-R} @var{sectionpattern}|@option{--remove-section=}@var{sectionpattern}]
+ [@option{--keep-section=}@var{sectionpattern}]
[@option{--remove-relocations=}@var{sectionpattern}]
[@option{-p}|@option{--preserve-dates}]
[@option{-D}|@option{--enable-deterministic-archives}]
[@option{--change-section-vma} @var{sectionpattern}@{=,+,-@}@var{val}]
[@option{--change-warnings}] [@option{--no-change-warnings}]
[@option{--set-section-flags} @var{sectionpattern}=@var{flags}]
+ [@option{--set-section-alignment} @var{sectionpattern}=@var{align}]
[@option{--add-section} @var{sectionname}=@var{filename}]
[@option{--dump-section} @var{sectionname}=@var{filename}]
[@option{--update-section} @var{sectionname}=@var{filename}]
[@option{--elf-stt-common=@var{val}}]
[@option{--merge-notes}]
[@option{--no-merge-notes}]
+ [@option{--verilog-data-width=@var{val}}]
[@option{-v}|@option{--verbose}]
[@option{-V}|@option{--version}]
[@option{--help}] [@option{--info}]
will remove all sections matching the pattern '.text.*', but will not
remove the section '.text.foo'.
+@item --keep-section=@var{sectionpattern}
+When removing sections from the output file, keep sections that match
+@var{sectionpattern}.
+
@item --remove-relocations=@var{sectionpattern}
Remove non-dynamic relocations from the output file for any section
matching @var{sectionpattern}. This option may be given more than
contents--just remove the section instead. Not all flags are
meaningful for all object file formats.
+@item --set-section-alignment @var{sectionpattern}=@var{align}
+Set the alignment for any sections matching @var{sectionpattern}.
+@var{align} specifies the alignment in bytes and must be a power of
+two, i.e. 1, 2, 4, 8@dots{}.
+
@item --add-section @var{sectionname}=@var{filename}
Add a new section named @var{sectionname} while copying the file. The
contents of the new section are taken from the file @var{filename}. The
@smallexample
objcopy --add-gnu-debuglink=foo.debug
@end smallexample
-
+
At debug time the debugger will attempt to look for the separate debug
info file in a set of known locations. The exact set of these
locations varies depending upon the distribution being used, but it
[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.
+Sets the section alignment field in the PE header. 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 --version
Show the version number of @command{objcopy}.
+@item --verilog-data-width=@var{bytes}
+For Verilog output, this options controls the number of bytes
+converted for each output data element. The input target controls the
+endianness of the conversion.
+
@item -v
@itemx --verbose
Verbose output: list all object files modified. In the case of
@cindex object file information
@kindex objdump
-@c man title objdump display information from object files.
+@c man title objdump display information from object files
@smallexample
@c man begin SYNOPSIS objdump
[@option{-j} @var{section}|@option{--section=}@var{section}]
[@option{-l}|@option{--line-numbers}]
[@option{-S}|@option{--source}]
+ [@option{--source-comment}[=@var{text}]]
[@option{-m} @var{machine}|@option{--architecture=}@var{machine}]
[@option{-M} @var{options}|@option{--disassembler-options=}@var{options}]
[@option{-p}|@option{--private-headers}]
[@option{-s}|@option{--full-contents}]
[@option{-W[lLiaprmfFsoRtUuTgAckK]}|
@option{--dwarf}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]]
+ [@option{--ctf=}@var{section}]
[@option{-G}|@option{--stabs}]
[@option{-t}|@option{--syms}]
[@option{-T}|@option{--dynamic-syms}]
[@option{--adjust-vma=}@var{offset}]
[@option{--dwarf-depth=@var{n}}]
[@option{--dwarf-start=@var{n}}]
+ [@option{--ctf-parent=}@var{section}]
[@option{--no-recurse-limit}|@option{--recurse-limit}]
[@option{--special-syms}]
[@option{--prefix=}@var{prefix}]
an inifinite level of recursion it is possible to create strings whose
decoding will exhaust the amount of stack space available on the host
machine, triggering a memory fault. The limit tries to prevent this
-from happening by restricting recursion to 1024 levels of nesting.
+from happening by restricting recursion to 2048 levels of nesting.
The default is for this limit to be enabled, but disabling it may be
necessary in order to demangle truly complicated names. Note however
Display the assembler mnemonics for the machine instructions from the
input file. This option only disassembles those sections which are
expected to contain instructions. If the optional @var{symbol}
-argument is given, then display the assembler mnemonics only from
-@var{symbol} up to next symbol. If there are no matches for
-@var{symbol} then nothing will be displayed.
+argument is given, then display the assembler mnemonics starting at
+@var{symbol}. If @var{symbol} is a function name then disassembly
+will stop at the end of the function, otherwise it will stop when the
+next symbol is encountered. If there are no matches for @var{symbol}
+then nothing will be displayed.
+
+Note if the @option{--dwarf=follow-links} option has also been enabled
+then any symbol tables in linked debug info files will be read in and
+used when disassembling.
@item -D
@itemx --disassemble-all
of forcing the disassembler to decode pieces of data found in code
sections as if they were instructions.
+Note if the @option{--dwarf=follow-links} option has also been enabled
+then any symbol tables in linked debug info files will be read in and
+used when disassembling.
+
@item --prefix-addresses
When disassembling, print the complete address on each line. This is
the older disassembly format.
@itemx addr16
@itemx data32
@itemx data16
-Specify the default address size and operand size. These four options
+Specify the default address size and operand size. These five options
will be overridden if @code{x86-64}, @code{i386} or @code{i8086}
appear later in the option string.
Display source code intermixed with disassembly, if possible. Implies
@option{-d}.
+@item --source-comment[=@var{txt}]
+@cindex source disassembly
+@cindex disassembly, with source
+Like the @option{-S} option, but all source code lines are displayed
+with a prefix of @var{txt}. Typically @var{txt} will be a comment
+string which can be used to distinguish the assembler code from the
+source code. If @var{txt} is not provided then a default string of
+@var{``# ``} (hash followed by a space), will be used.
+
@item --prefix=@var{prefix}
@cindex Add prefix to absolute paths
Specify @var{prefix} to add to the absolute paths when used with
@item --dwarf-check
Enable additional checks for consistency of Dwarf information.
+@include ctf.options.texi
+
@item -G
@itemx --stabs
@cindex stab
@cindex archive contents
@cindex symbol index
-@c man title ranlib generate index to archive.
+@c man title ranlib generate an index to an archive
@smallexample
@c man begin SYNOPSIS ranlib
@kindex size
@cindex section sizes
-@c man title size list section sizes and total size.
+@c man title size list section sizes and total size of binary files
@smallexample
@c man begin SYNOPSIS size
-size [@option{-A}|@option{-B}|@option{--format=}@var{compatibility}]
+size [@option{-A}|@option{-B}|@option{-G}|@option{--format=}@var{compatibility}]
[@option{--help}]
[@option{-d}|@option{-o}|@option{-x}|@option{--radix=}@var{number}]
[@option{--common}]
@c man begin DESCRIPTION size
-The @sc{gnu} @command{size} utility lists the section sizes---and the total
-size---for each of the object or archive files @var{objfile} in its
-argument list. By default, one line of output is generated for each
-object file or each module in an archive.
+The @sc{gnu} @command{size} utility lists the section sizes and the total
+size for each of the binary files @var{objfile} on its argument list.
+By default, one line of output is generated for each file or each
+module if the file is an archive.
-@var{objfile}@dots{} are the object files to be examined.
-If none are specified, the file @code{a.out} will be used.
+@var{objfile}@dots{} are the files to be examined. If none are
+specified, the file @code{a.out} will be used instead.
@c man end
@table @env
@item -A
@itemx -B
+@itemx -G
@itemx --format=@var{compatibility}
@cindex @command{size} display format
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. Alternatively, you can choose the GNU format output
+(using @option{-G}, or @option{--format=gnu}), this is similar to
+Berkeley's output format, but sizes are counted differently.
@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.
@command{size}:
@smallexample
$ size --format=Berkeley ranlib size
-text data bss dec hex filename
-294880 81920 11592 388392 5ed28 ranlib
-294880 81920 11888 388688 5ee50 size
+ text data bss dec hex filename
+ 294880 81920 11592 388392 5ed28 ranlib
+ 294880 81920 11888 388688 5ee50 size
+@end smallexample
+
+The Berkeley style output counts read only data in the @code{text}
+column, not in the @code{data} column, the @code{dec} and @code{hex}
+columns both display the sum of the @code{text}, @code{data}, and
+@code{bss} columns in decimal and hexadecimal respectively.
+
+The GNU format counts read only data in the @code{data} column, not
+the @code{text} column, and only displays the sum of the @code{text},
+@code{data}, and @code{bss} columns once, in the @code{total} column.
+The @option{--radix} option can be used to change the number base for
+all columns. Here is the same data displayed with GNU conventions:
+
+@smallexample
+$ size --format=GNU ranlib size
+ text data bss total filename
+ 279880 96920 11592 388392 ranlib
+ 279880 96920 11888 388688 size
@end smallexample
@noindent
@item --common
Print total size of common symbols in each file. When using Berkeley
-format these are included in the bss size.
+or GNU format these are included in the bss size.
@item -t
@itemx --totals
-Show totals of all objects listed (Berkeley format listing mode only).
+Show totals of all objects listed (Berkeley or GNU format mode only).
@item --target=@var{bfdname}
@cindex object code format
@cindex printing strings
@cindex strings, printing
-@c man title strings print the strings of printable characters in files.
+@c man title strings print the sequences of printable characters in files
@smallexample
@c man begin SYNOPSIS strings
For backwards compatibility any file that occurs after a command-line
option of just @option{-} will also be scanned in full, regardless of
-the presence of any @option{-d} option.
+the presence of any @option{-d} option.
@command{strings} is mainly useful for determining the contents of
non-text files.
@cindex discarding symbols
@cindex symbols, discarding
-@c man title strip Discard symbols from object files.
+@c man title strip discard symbols and other data from object files
@smallexample
@c man begin SYNOPSIS strip
[@option{-w}|@option{--wildcard}]
[@option{-x}|@option{--discard-all}] [@option{-X} |@option{--discard-locals}]
[@option{-R} @var{sectionname} |@option{--remove-section=}@var{sectionname}]
+ [@option{--keep-section=}@var{sectionpattern}]
[@option{--remove-relocations=}@var{sectionpattern}]
[@option{-o} @var{file}] [@option{-p}|@option{--preserve-dates}]
[@option{-D}|@option{--enable-deterministic-archives}]
will remove all sections matching the pattern '.text.*', but will not
remove the section '.text.foo'.
+@item --keep-section=@var{sectionpattern}
+When removing sections from the output file, keep sections that match
+@var{sectionpattern}.
+
@item --remove-relocations=@var{sectionpattern}
Remove relocations from the output file for any section matching
@var{sectionpattern}. This option may be given more than once. Note
@itemx --no-merge-notes
For ELF files, attempt (or do not attempt) to reduce the size of any
SHT_NOTE type sections by removing duplicate notes. The default is to
-attempt this reduction.
+attempt this reduction unless stripping debug or DWO information.
@item -N @var{symbolname}
@itemx --strip-symbol=@var{symbolname}
@kindex c++filt
@cindex demangling C++ symbols
-@c man title cxxfilt Demangle C++ and Java symbols.
+@c man title cxxfilt demangle C++ and Java symbols
@smallexample
@c man begin SYNOPSIS cxxfilt
an inifinite level of recursion it is possible to create strings whose
decoding will exhaust the amount of stack space available on the host
machine, triggering a memory fault. The limit tries to prevent this
-from happening by restricting recursion to 1024 levels of nesting.
+from happening by restricting recursion to 2048 levels of nesting.
The default is for this limit to be enabled, but disabling it may be
necessary in order to demangle truly complicated names. Note however
@kindex addr2line
@cindex address to file name and line number
-@c man title addr2line convert addresses into file names and line numbers.
+@c man title addr2line convert addresses into file names and line numbers
@smallexample
@c man begin SYNOPSIS addr2line
an inifinite level of recursion it is possible to create strings whose
decoding will exhaust the amount of stack space available on the host
machine, triggering a memory fault. The limit tries to prevent this
-from happening by restricting recursion to 1024 levels of nesting.
+from happening by restricting recursion to 2048 levels of nesting.
The default is for this limit to be enabled, but disabling it may be
necessary in order to demangle truly complicated names. Note however
utilities, since it is only useful for Windows targets.
@end quotation
-@c man title windmc generates Windows message resources.
+@c man title windmc generates Windows message resources
@smallexample
@c man begin SYNOPSIS windmc
utilities, since it is only useful for Windows targets.
@end quotation
-@c man title windres manipulate Windows resources.
+@c man title windres manipulate Windows resources
@smallexample
@c man begin SYNOPSIS windres
support DLLs.
@end quotation
-@c man title dlltool Create files needed to build and use DLLs.
+@c man title dlltool create files needed to build and use DLLs
@smallexample
@c man begin SYNOPSIS dlltool
@cindex ELF file information
@kindex readelf
-@c man title readelf Displays information about ELF files.
+@c man title readelf display information about ELF files
@smallexample
@c man begin SYNOPSIS readelf
@option{--debug-dump}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]]
[@option{--dwarf-depth=@var{n}}]
[@option{--dwarf-start=@var{n}}]
+ [@option{--ctf=}@var{section}]
+ [@option{--ctf-parent=}@var{section}]
+ [@option{--ctf-symbols=}@var{section}]
+ [@option{--ctf-strings=}@var{section}]
[@option{-I}|@option{--histogram}]
[@option{-v}|@option{--version}]
[@option{-W}|@option{--wide}]
@itemx --debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]
@include debug.options.texi
+@include ctf.options.texi
+@item --ctf-symbols=@var{section}
+@item --ctf-strings=@var{section}
+Specify the name of another section from which the CTF file can inherit
+strings and symbols. By default, the @code{.symtab} and its linked
+string table are used.
+
+If either of @option{--ctf-symbols} or @option{--ctf-strings} is specified, the
+other must be specified as well.
+
@item -I
@itemx --histogram
Display a histogram of bucket list lengths when displaying the contents
@cindex Update ELF header
@kindex elfedit
-@c man title elfedit Update ELF header and program property of ELF files.
+@c man title elfedit update ELF header and program property of ELF files
@smallexample
@c man begin SYNOPSIS elfedit
projects / deliverable / binutils-gdb.git / blobdiff