Imported binutils-2.20

[msp430-binutils.git] / binutils / doc / ar.1

diff --git a/binutils/doc/ar.1 b/binutils/doc/ar.1
index 4bd3ab2f579cfabbb8f43e8b77fa392225f63590..9fa94e1f248917adb7ca5189cf8fdcde7d96be09 100644 (file)
--- a/binutils/doc/ar.1
+++ b/binutils/doc/ar.1
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)

 .\"
 .\" Standard preamble:
 .\" ========================================================================
 .\"
 .\" Standard preamble:
 .\" ========================================================================


@@ -48,21 +48,25 @@
 .    ds R" ''
 'br\}
 .\"
 .    ds R" ''
 '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 turned on, we'll generate index entries on stderr for
 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
 .\" If the F register is turned on, we'll generate index entries on stderr for
 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.

-.if \nF \{\
+.ie \nF \{\

 .    de IX
 .    tm Index:\\$1\t\\n%\t"\\$2"
 ..
 .    nr % 0
 .    rr F
 .\}
 .    de IX
 .    tm Index:\\$1\t\\n%\t"\\$2"
 ..
 .    nr % 0
 .    rr F
 .\}

-.\"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
+.el \{\
+.    de IX
+..
+.\}

 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.


@@ -128,12 +132,16 @@
 .\" ========================================================================
 .\"
 .IX Title "AR 1"
 .\" ========================================================================
 .\"
 .IX Title "AR 1"

-.TH AR 1 "2007-08-06" "binutils-2.17.90" "GNU Development Tools"
+.TH AR 1 "2009-10-16" "binutils-2.20" "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"
 .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 [\fIrelpos\fR] [\fIcount\fR]] \fIarchive\fR [\fImember\fR...]
+ar [\fB\-\-plugin\fR \fIname\fR] [\fB\-X32_64\fR] [\fB\-\fR]\fIp\fR[\fImod\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
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 The \s-1GNU\s0 \fBar\fR program creates, modifies, and extracts from


@@ -168,6 +176,17 @@ 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
 table.  If an archive lacks the table, another form of \fBar\fR called
 \&\fBranlib\fR can be used to add just the table.
 .PP

+\&\s-1GNU\s0 \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 archives.  Such an archive is useful
+for building libraries for use within a local build, where the
+relocatable objects are expected to remain available, and copying the
+contents of each object would only waste time and space.  Thin archives
+are also \fIflattened\fR, so that adding one or more archives to a
+thin archive will add the elements of the nested archive individually.
+The paths to the elements of the archive are stored relative to the
+archive itself.
+.PP

 \&\s-1GNU\s0 \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
 \&\s-1GNU\s0 \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


@@ -270,6 +289,8 @@ use the \fBv\fR modifier with this operation, to request that
 .Sp
 If you do not specify a \fImember\fR, all files in the archive
 are extracted.
 .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.

 .PP
 A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR
 keyletter, to specify variations on an operation's behavior:
 .PP
 A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR
 keyletter, to specify variations on an operation's behavior:


@@ -291,6 +312,14 @@ member must be present as the \fIrelpos\fR argument, before the
 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.
 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.

 .IP "\fBf\fR" 4
 .IX Item "f"
 Truncate names in the archive.  \s-1GNU\s0 \fBar\fR will normally permit file
 .IP "\fBf\fR" 4
 .IX Item "f"
 Truncate names in the archive.  \s-1GNU\s0 \fBar\fR will normally permit file


@@ -338,6 +367,11 @@ 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.
 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"
+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 "\fBu\fR" 4
 .IX Item "u"
 Normally, \fBar r\fR... inserts all files
 .IP "\fBu\fR" 4
 .IX Item "u"
 Normally, \fBar r\fR... inserts all files


@@ -361,12 +395,17 @@ 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 \fB\-X32\fR
 which is the default for \s-1AIX\s0 \fBar\fR.
 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 \fB\-X32\fR
 which is the default for \s-1AIX\s0 \fBar\fR.

+.PP
+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.  This option is only available if the toolchain
+has been built with plugin support enabled.

 .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
 .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.  
+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
 .Sp
 Options in \fIfile\fR are separated by whitespace.  A whitespace
 character may be included in an option by surrounding the entire


@@ -380,10 +419,10 @@ with a backslash.  The \fIfile\fR may itself contain additional
 .SH "COPYRIGHT"
 .IX Header "COPYRIGHT"
 Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
 .SH "COPYRIGHT"
 .IX Header "COPYRIGHT"
 Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,

-2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.

 .PP
 Permission is granted to copy, distribute and/or modify this document
 .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.1
+under the terms of the \s-1GNU\s0 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
 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