@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1991-2019 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 compliant), 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}]
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
[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}
[@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{--dwarf-depth=@var{n}}]
[@option{--dwarf-start=@var{n}}]
[@option{--ctf-parent=}@var{section}]
- [@option{--ctf-symbols=}@var{section}]
- [@option{--ctf-strings=}@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
[@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
@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.
+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.
projects / deliverable / binutils-gdb.git / blobdiff