@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
[@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}]
@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
@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
@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
@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
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