Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 464 insertions, 0 deletions

diff --git a/upstream/archlinux/man1/ar.1 b/upstream/archlinux/man1/ar.1
new file mode 100644
index 00000000..0257f0cc
--- /dev/null
+++ b/upstream/archlinux/man1/ar.1
@@ -0,0 +1,464 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "AR 1"
+.TH AR 1 2024-02-01 binutils-2.42.0 "GNU Development Tools"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+ar \- create, modify, and extract from archives
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+ar [\fB\-X32_64\fR] [\fB\-\fR]\fIp\fR[\fImod\fR] [\fB\-\-plugin\fR \fIname\fR] [\fB\-\-target\fR \fIbfdname\fR] [\fB\-\-output\fR \fIdirname\fR] [\fB\-\-record\-libdeps\fR \fIlibdeps\fR] [\fB\-\-thin\fR] [\fIrelpos\fR] [\fIcount\fR] \fIarchive\fR [\fImember\fR...]
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The GNU \fBar\fR program creates, modifies, and extracts from
+archives.  An \fIarchive\fR is a single file holding a collection of
+other files in a structure that makes it possible to retrieve
+the original individual files (called \fImembers\fR of the archive).
+.PP
+The original files' contents, mode (permissions), timestamp, owner, and
+group are preserved in the archive, and can be restored on
+extraction.
+.PP
+GNU \fBar\fR can maintain archives whose members have names of any
+length; however, depending on how \fBar\fR is configured on your
+system, a limit on member-name length may be imposed for compatibility
+with archive formats maintained with other tools.  If it exists, the
+limit is often 15 characters (typical of formats related to a.out) or 16
+characters (typical of formats related to coff).
+.PP
+\&\fBar\fR is considered a binary utility because archives of this sort
+are most often used as \fIlibraries\fR holding commonly needed
+subroutines.  Since libraries often will depend on other libraries,
+\&\fBar\fR can also record the dependencies of a library when the
+\&\fB\-\-record\-libdeps\fR option is specified.
+.PP
+\&\fBar\fR creates an index to the symbols defined in relocatable
+object modules in the archive when you specify the modifier \fBs\fR.
+Once created, this index is updated in the archive whenever \fBar\fR
+makes a change to its contents (save for the \fBq\fR update operation).
+An archive with such an index speeds up linking to the library, and
+allows routines in the library to call each other without regard to
+their placement in the archive.
+.PP
+You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index
+table.  If an archive lacks the table, another form of \fBar\fR called
+\&\fBranlib\fR can be used to add just the table.
+.PP
+GNU \fBar\fR can optionally create a \fIthin\fR archive,
+which contains a symbol index and references to the original copies
+of the member files of the archive.  This is useful for building
+libraries for use within a local build tree, where the relocatable
+objects are expected to remain available, and copying the contents of
+each object would only waste time and space.
+.PP
+An archive can either be \fIthin\fR or it can be normal.  It cannot
+be both at the same time.  Once an archive is created its format
+cannot be changed without first deleting it and then creating a new
+archive in its place.
+.PP
+Thin archives are also \fIflattened\fR, so that adding one thin
+archive to another thin archive does not nest it, as would happen with
+a normal archive.  Instead the elements of the first archive are added
+individually to the second archive.
+.PP
+The paths to the elements of the archive are stored relative to the
+archive itself.
+.PP
+GNU \fBar\fR is designed to be compatible with two different
+facilities.  You can control its activity using command-line options,
+like the different varieties of \fBar\fR on Unix systems; or, if you
+specify the single command-line option \fB\-M\fR, you can control it
+with a script supplied via standard input, like the MRI "librarian"
+program.
+.SH OPTIONS
+.IX Header "OPTIONS"
+GNU \fBar\fR allows you to mix the operation code \fIp\fR and modifier
+flags \fImod\fR in any order, within the first command-line argument.
+.PP
+If you wish, you may begin the first command-line argument with a
+dash.
+.PP
+The \fIp\fR keyletter specifies what operation to execute; it may be
+any of the following, but you must specify only one of them:
+.IP \fBd\fR 4
+.IX Item "d"
+\&\fIDelete\fR modules from the archive.  Specify the names of modules to
+be deleted as \fImember\fR...; the archive is untouched if you
+specify no files to delete.
+.Sp
+If you specify the \fBv\fR modifier, \fBar\fR lists each module
+as it is deleted.
+.IP \fBm\fR 4
+.IX Item "m"
+Use this operation to \fImove\fR members in an archive.
+.Sp
+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.
+.Sp
+If no modifiers are used with \f(CW\*(C`m\*(C'\fR, any members you name in the
+\&\fImember\fR arguments are moved to the \fIend\fR of the archive;
+you can use the \fBa\fR, \fBb\fR, or \fBi\fR modifiers to move them to a
+specified place instead.
+.IP \fBp\fR 4
+.IX Item "p"
+\&\fIPrint\fR the specified members of the archive, to the standard
+output file.  If the \fBv\fR modifier is specified, show the member
+name before copying its contents to standard output.
+.Sp
+If you specify no \fImember\fR arguments, all the files in the archive are
+printed.
+.IP \fBq\fR 4
+.IX Item "q"
+\&\fIQuick append\fR; Historically, add the files \fImember\fR... to the end of
+\&\fIarchive\fR, without checking for replacement.
+.Sp
+The modifiers \fBa\fR, \fBb\fR, and \fBi\fR do \fInot\fR affect this
+operation; new members are always placed at the end of the archive.
+.Sp
+The modifier \fBv\fR makes \fBar\fR list each file as it is appended.
+.Sp
+Since the point of this operation is speed, implementations of
+\&\fBar\fR have the option of not updating the archive's symbol
+table if one exists.  Too many different systems however assume that
+symbol tables are always up-to-date, so GNU \fBar\fR will
+rebuild the table even with a quick append.
+.Sp
+Note \- GNU \fBar\fR treats the command \fBqs\fR as a
+synonym for \fBr\fR \- replacing already existing files in the
+archive and appending new ones at the end.
+.IP \fBr\fR 4
+.IX Item "r"
+Insert the files \fImember\fR... into \fIarchive\fR (with
+\&\fIreplacement\fR). This operation differs from \fBq\fR in that any
+previously existing members are deleted if their names match those being
+added.
+.Sp
+If one of the files named in \fImember\fR... does not exist, \fBar\fR
+displays an error message, and leaves undisturbed any existing members
+of the archive matching that name.
+.Sp
+By default, new members are added at the end of the file; but you may
+use one of the modifiers \fBa\fR, \fBb\fR, or \fBi\fR to request
+placement relative to some existing member.
+.Sp
+The modifier \fBv\fR used with this operation elicits a line of
+output for each file inserted, along with one of the letters \fBa\fR or
+\&\fBr\fR to indicate whether the file was appended (no old member
+deleted) or replaced.
+.IP \fBs\fR 4
+.IX Item "s"
+Add an index to the archive, or update it if it already exists.  Note
+this command is an exception to the rule that there can only be one
+command letter, as it is possible to use it as either a command or a
+modifier.  In either case it does the same thing.
+.IP \fBt\fR 4
+.IX Item "t"
+Display a \fItable\fR listing the contents of \fIarchive\fR, or those
+of the files listed in \fImember\fR... that are present in the
+archive.  Normally only the member name is shown, but if the modifier
+\&\fBO\fR is specified, then the corresponding offset of the member is also
+displayed.  Finally, in order to see the modes (permissions), timestamp,
+owner, group, and size the \fBv\fR modifier should be included.
+.Sp
+If you do not specify a \fImember\fR, all files in the archive
+are listed.
+.Sp
+If there is more than one file with the same name (say, \fBfie\fR) in
+an archive (say \fBb.a\fR), \fBar t b.a fie\fR lists only the
+first instance; to see them all, you must ask for a complete
+listing\-\-\-in our example, \fBar t b.a\fR.
+.IP \fBx\fR 4
+.IX Item "x"
+\&\fIExtract\fR members (named \fImember\fR) from the archive.  You can
+use the \fBv\fR modifier with this operation, to request that
+\&\fBar\fR list each name as it extracts it.
+.Sp
+If you do not specify a \fImember\fR, all files in the archive
+are extracted.
+.Sp
+Files cannot be extracted from a thin archive, and there are
+restrictions on extracting from archives created with \fBP\fR: The
+paths must not be absolute, may not contain \f(CW\*(C`..\*(C'\fR, and any
+subdirectories in the paths must exist.  If it is desired to avoid
+these restrictions then used the \fB\-\-output\fR option to specify
+an output directory.
+.PP
+A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR
+keyletter, to specify variations on an operation's behavior:
+.IP \fBa\fR 4
+.IX Item "a"
+Add new files \fIafter\fR an existing member of the
+archive.  If you use the modifier \fBa\fR, the name of an existing archive
+member must be present as the \fIrelpos\fR argument, before the
+\&\fIarchive\fR specification.
+.IP \fBb\fR 4
+.IX Item "b"
+Add new files \fIbefore\fR an existing member of the
+archive.  If you use the modifier \fBb\fR, the name of an existing archive
+member must be present as the \fIrelpos\fR argument, before the
+\&\fIarchive\fR specification.  (same as \fBi\fR).
+.IP \fBc\fR 4
+.IX Item "c"
+\&\fICreate\fR the archive.  The specified \fIarchive\fR is always
+created if it did not exist, when you request an update.  But a warning is
+issued unless you specify in advance that you expect to create it, by
+using this modifier.
+.IP \fBD\fR 4
+.IX Item "D"
+Operate in \fIdeterministic\fR 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 \fBar\fR 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.
+.Sp
+If \fIbinutils\fR was configured with
+\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default.
+It can be disabled with the \fBU\fR modifier, below.
+.IP \fBf\fR 4
+.IX Item "f"
+Truncate names in the archive.  GNU \fBar\fR will normally permit file
+names of any length.  This will cause it to create archives which are
+not compatible with the native \fBar\fR program on some systems.  If
+this is a concern, the \fBf\fR modifier may be used to truncate file
+names when putting them in the archive.
+.IP \fBi\fR 4
+.IX Item "i"
+Insert new files \fIbefore\fR an existing member of the
+archive.  If you use the modifier \fBi\fR, the name of an existing archive
+member must be present as the \fIrelpos\fR argument, before the
+\&\fIarchive\fR specification.  (same as \fBb\fR).
+.IP \fBl\fR 4
+.IX Item "l"
+Specify dependencies of this library.  The dependencies must immediately
+follow this option character, must use the same syntax as the linker
+command line, and must be specified within a single argument.  I.e., if
+multiple items are needed, they must be quoted to form a single command
+line argument.  For example \fBL "\-L/usr/local/lib \-lmydep1 \-lmydep2"\fR
+.IP \fBN\fR 4
+.IX Item "N"
+Uses the \fIcount\fR parameter.  This is used if there are multiple
+entries in the archive with the same name.  Extract or delete instance
+\&\fIcount\fR of the given name from the archive.
+.IP \fBo\fR 4
+.IX Item "o"
+Preserve the \fIoriginal\fR dates of members when extracting them.  If
+you do not specify this modifier, files extracted from the archive
+are stamped with the time of extraction.
+.IP \fBO\fR 4
+.IX Item "O"
+Display member offsets inside the archive. Use together with the \fBt\fR
+option.
+.IP \fBP\fR 4
+.IX Item "P"
+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 GNU tools.
+Modifying such archives with GNU \fBar\fR without using
+\&\fBP\fR will remove the full path names unless the archive is a
+thin archive.  Note that \fBP\fR may be useful when adding files to
+a thin archive since \fBr\fR without \fBP\fR ignores the path
+when choosing which element to replace.  Thus
+.Sp
+.Vb 1
+\&        ar rcST archive.a subdir/file1 subdir/file2 file1
+.Ve
+.Sp
+will result in the first \f(CW\*(C`subdir/file1\*(C'\fR being replaced with
+\&\f(CW\*(C`file1\*(C'\fR from the current directory.  Adding \fBP\fR will
+prevent this replacement.
+.IP \fBs\fR 4
+.IX Item "s"
+Write an object-file index into the archive, or update an existing one,
+even if no other change is made to the archive.  You may use this modifier
+flag either with any operation, or alone.  Running \fBar s\fR on an
+archive is equivalent to running \fBranlib\fR on it.
+.IP \fBS\fR 4
+.IX Item "S"
+Do not generate an archive symbol table.  This can speed up building a
+large library in several steps.  The resulting archive can not be used
+with the linker.  In order to build a symbol table, you must omit the
+\&\fBS\fR modifier on the last execution of \fBar\fR, or you must run
+\&\fBranlib\fR on the archive.
+.IP \fBT\fR 4
+.IX Item "T"
+Deprecated alias for \fB\-\-thin\fR.  \fBT\fR is not recommended because in
+many ar implementations \fBT\fR has a different meaning, as specified by
+X/Open System Interface.
+.IP \fBu\fR 4
+.IX Item "u"
+Normally, \fBar r\fR... inserts all files
+listed into the archive.  If you would like to insert \fIonly\fR those
+of the files you list that are newer than existing members of the same
+names, use this modifier.  The \fBu\fR modifier is allowed only for the
+operation \fBr\fR (replace).  In particular, the combination \fBqu\fR is
+not allowed, since checking the timestamps would lose any speed
+advantage from the operation \fBq\fR.
+.Sp
+Note \- if an archive has been created in a deterministic manner, eg
+via the use of the \fBD\fR modifier, then replacement will always
+happen and the \fBu\fR modifier will be ineffective.
+.IP \fBU\fR 4
+.IX Item "U"
+Do \fInot\fR operate in \fIdeterministic\fR mode.  This is the inverse
+of the \fBD\fR modifier, above: added files and the archive index will
+get their actual UID, GID, timestamp, and file mode values.
+.Sp
+This is the default unless \fIbinutils\fR was configured with
+\&\fB\-\-enable\-deterministic\-archives\fR.
+.IP \fBv\fR 4
+.IX Item "v"
+This modifier requests the \fIverbose\fR version of an operation.  Many
+operations display additional information, such as filenames processed,
+when the modifier \fBv\fR is appended.
+.IP \fBV\fR 4
+.IX Item "V"
+This modifier shows the version number of \fBar\fR.
+.PP
+The \fBar\fR program also supports some command-line options which
+are neither modifiers nor actions, but which do change its behaviour
+in specific ways:
+.IP \fB\-\-help\fR 4
+.IX Item "--help"
+Displays the list of command-line options supported by \fBar\fR
+and then exits.
+.IP \fB\-\-version\fR 4
+.IX Item "--version"
+Displays the version information of \fBar\fR and then exits.
+.IP \fB\-X32_64\fR 4
+.IX Item "-X32_64"
+\&\fBar\fR ignores an initial option spelled \fB\-X32_64\fR, for
+compatibility with AIX.  The behaviour produced by this option is the
+default for GNU \fBar\fR.  \fBar\fR does not support any
+of the other \fB\-X\fR options; in particular, it does not support
+\&\fB\-X32\fR which is the default for AIX \fBar\fR.
+.IP "\fB\-\-plugin\fR \fIname\fR" 4
+.IX Item "--plugin name"
+The optional command-line switch \fB\-\-plugin\fR \fIname\fR causes
+\&\fBar\fR to load the plugin called \fIname\fR which adds support
+for more file formats, including object files with link-time
+optimization information.
+.Sp
+This option is only available if the toolchain has been built with
+plugin support enabled.
+.Sp
+If \fB\-\-plugin\fR is not provided, but plugin support has been
+enabled then \fBar\fR iterates over the files in
+\&\fI${libdir}/bfd\-plugins\fR in alphabetic order and the first
+plugin that claims the object in question is used.
+.Sp
+Please note that this plugin search directory is \fInot\fR the one
+used by \fBld\fR's \fB\-plugin\fR option.  In order to make
+\&\fBar\fR use the  linker plugin it must be copied into the
+\&\fI${libdir}/bfd\-plugins\fR directory.  For GCC based compilations
+the linker plugin is called \fIliblto_plugin.so.0.0.0\fR.  For Clang
+based compilations it is called \fILLVMgold.so\fR.  The GCC plugin
+is always backwards compatible with earlier versions, so it is
+sufficient to just copy the newest one.
+.IP "\fB\-\-target\fR \fItarget\fR" 4
+.IX Item "--target target"
+The optional command-line switch \fB\-\-target\fR \fIbfdname\fR
+specifies that the archive members are in an object code format
+different from your system's default format.  See
+.IP "\fB\-\-output\fR \fIdirname\fR" 4
+.IX Item "--output dirname"
+The \fB\-\-output\fR 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.
+.Sp
+Note \- although the presence of this option does imply a \fBx\fR 
+extraction operation that option must still be included on the command
+line.
+.IP "\fB\-\-record\-libdeps\fR \fIlibdeps\fR" 4
+.IX Item "--record-libdeps libdeps"
+The \fB\-\-record\-libdeps\fR option is identical to the \fBl\fR modifier,
+just handled in long form.
+.IP \fB\-\-thin\fR 4
+.IX Item "--thin"
+Make the specified \fIarchive\fR a \fIthin\fR archive.  If it already
+exists and is a regular archive, the existing members must be present
+in the same directory as \fIarchive\fR.
+.IP \fB@\fR\fIfile\fR 4
+.IX Item "@file"
+Read command-line options from \fIfile\fR.  The options read are
+inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
+does not exist, or cannot be read, then the option will be treated
+literally, and not removed.
+.Sp
+Options in \fIfile\fR are separated by whitespace.  A whitespace
+character may be included in an option by surrounding the entire
+option in either single or double quotes.  Any character (including a
+backslash) may be included by prefixing the character to be included
+with a backslash.  The \fIfile\fR may itself contain additional
+@\fIfile\fR options; any such options will be processed recursively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBnm\fR\|(1), \fBranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (c) 1991\-2024 Free Software Foundation, Inc.
+.PP
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled "GNU Free Documentation License".