1 files changed, 35 insertions, 11 deletions
diff --git a/share/man/man1/ar.1 b/share/man/man1/ar.1
index 9409643..48a8086 100644
--- a/share/man/man1/ar.1
+++ b/share/man/man1/ar.1
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "AR 1"
-.TH AR 1 "2019-10-12" "binutils-2.33.1" "GNU Development Tools"
+.TH AR 1 "2020-09-19" "binutils-2.35.1" "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
@@ -142,7 +142,7 @@
 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] [\fIrelpos\fR] [\fIcount\fR] \fIarchive\fR [\fImember\fR...]
+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] [\fIrelpos\fR] [\fIcount\fR] \fIarchive\fR [\fImember\fR...]
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 The \s-1GNU\s0 \fBar\fR program creates, modifies, and extracts from
@@ -310,7 +310,12 @@ use the \fBv\fR modifier with this operation, to request that
 If you do not specify a \fImember\fR, all files in the archive
 are extracted.
 .Sp
-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 \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:
@@ -376,12 +381,22 @@ 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 names in the archive.  \s-1GNU\s0
-\&\fBar\fR can not create an archive with a full path name (such archives
-are not \s-1POSIX\s0 compliant), but other archive creators can.  This option
-will cause \s-1GNU\s0 \fBar\fR 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 \s-1POSIX\s0 compliant, and
+thus may not work with tools other than up to date \s-1GNU\s0 tools.
+Modifying such archives with \s-1GNU\s0 \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,
@@ -438,7 +453,7 @@ and then exits.
 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 spelt \fB\-X32_64\fR, for
+\&\fBar\fR ignores an initial option spelled \fB\-X32_64\fR, for
 compatibility with \s-1AIX.\s0  The behaviour produced by this option is the
 default for \s-1GNU\s0 \fBar\fR.  \fBar\fR does not support any
 of the other \fB\-X\fR options; in particular, it does not support
@@ -471,6 +486,15 @@ sufficient to just copy the newest one.
 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@\fR\fIfile\fR" 4
 .IX Item "@file"
 Read command-line options from \fIfile\fR.  The options read are
@@ -489,7 +513,7 @@ with a backslash.  The \fIfile\fR may itself contain additional
 \&\fBnm\fR\|(1), \fBranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
 .SH "COPYRIGHT"
 .IX Header "COPYRIGHT"
-Copyright (c) 1991\-2019 Free Software Foundation, Inc.
+Copyright (c) 1991\-2020 Free Software Foundation, Inc.
 .PP
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3