.\" Copyright (c) 1991 Free Software Foundation
.\" See section COPYING for conditions for redistribution
.TH ar 1 "5 November 1991" "cygnus support" "GNU Development Tools"
.\" jpman %Id: ar.1,v 1.3 1998/12/21 23:20:51 jsakai Stab %
.\"
.\" WORD: truncate	(小数で)切り捨てる[POSIX],切り詰める
.\"
.de BP
.sp
.ti \-.2i
\(**
..

.SH 名称
ar \- アーカイブの作成、更新、および、アーカイブからの抽出

.SH 書式
.hy 0
.na
.BR ar " [\|" "-" "\|]"\c
.I {dmpqrtx}[abcilosSuvV] \c
[\|\c
.I membername\c
\&\|] \c
.I archive\c
\& \c
.I files\c
\&.\|.\|.

.ad b
.hy 1
.SH 解説
GNU \c
.B ar\c
プログラムは、アーカイブの作成、更新、および、アーカイブからの抽出を
おこないます。
.I アーカイブ\c
\& とは、オリジナルのファイル(アーカイブの
.I メンバ\c
と呼びます)を復元できるような構造で、他のファイル群の集合を保持する
ような一つのファイルです。

元のファイルの内容、モード(パーミッション)、タイムスタンプ、所有者、
グループの情報はアーカイブ内でも保存され、ファイル抽出時には復元
されます。

GNU \c
.B ar\c
では、メンバファイルのファイル名の長さには制限はありませんが、システム
の設定によっては(他のツールで管理されるアーカイブファイルの形式との
互換性のために)メンバファイルのファイル名の長さに制限がある場合があります。
制限がある場合は、多くの場合 15 文字(a.out 関連のファイル形式が代表的)か、
16 文字(coff 関連のファイル形式が代表的)に制限されます。

この種類のアーカイブは、共有のサブルーチンを保持するライブラリとして
利用されることが多いため、\c
.B ar\c
\& はバイナリユーティリティと考えられます。

`\|\c
.B s\c
\|'修飾子を指定した場合、\c
.B ar\c
\& はアーカイブ内のリロケータブルオブジェクトで定義されたシンボル
のインデックスを作成します。
一度作成されたインデックスは、\c
.B ar\c
\& がアーカイブの内容を変更するときには必ず更新されます。(ただし`\|\c
.B q\c
\|' オプション指定時は更新されません)。このようなインデックスを持つ
アーカイブを用いることによって、ライブラリのリンクが高速化されたり、
ライブラリ内のルーチンがアーカイブ内の配置にかかわらず、互いを呼び出す
ことができるようになります。

`\|\c
.B nm \-s\c
\|' または `\|\c
.B nm \-\-print\-armap\c
\|' によって、このインデックステーブルを表示することができます。
もし、アーカイブにインデックステーブルが含まれていない場合は、\c
.B ranlib\c
と呼ばれる、もう一つの形式の \c
.B ar\c
\& を用いてテーブルだけを追加することができます。

\c
.B ar\c
\& を実行する時は、少なくとも二つの引数を指定する必要があります。
.I オペレーション\c
\& (動作)を指定する一つのキー文字と、処理するアーカイブ名です。
(キー文字には\c
.I 修飾子\c
\& として複数の文字をつけることもできます。)

ほとんどのオペレーションは、処理する個々のファイル名を指定するための \c
.I files\c
\& 引数を受け付けます。

.SH オプション
GNU \c
.B ar\c
\& は最初のコマンドラインオプションとして、オペレーションコード \c
.I p\c
\& と、修飾子 \c
.I mod\c
\& を任意の順序で組み合わせたものを受け付けます。

最初のオプションの先頭にダッシュ(ハイフン)をつけることもできます。

キー文字 \c
.I p\c
\& は、どのオペレーションを実行するかを指定します。キー文字としては
以下のいずれか一つだけを指定することができます。

.TP
.B d
アーカイブからモジュールを\c
.I 削除\c
\& します。削除するモジュール名を \c
.I files\c
\& として指定して下さい。
ファイル名を指定しなければアーカイブは変更されません。

`\|\c
.B v\c
\|'修飾子を指定した時には、\c
.B ar\c
\& は削除する際にそのモジュール名を表示します。

.TP
.B m
メンバをアーカイブ内で移動します。

あるシンボルが複数のメンバで定義されている場合は、アーカイブ内でのメンバの
順序によって、プログラムがライブラリをリンクした結果が異なることが
あります。

.B m\c
\& に修飾子が指定されなかった場合は \c
.I files\c
\& 引数で指定したメンバはアーカイブの\c
.I 最後\c
\& に移動されます。
`\|\c
.B a\c
\|'、`\|\c
.B b\c
\|'、または`\|\c
.B i\c
\|' 修飾子を指定することによって、修飾子に応じた場所に移動します。

.TP
.B p
アーカイブ内の指定されたメンバを標準出力に\c
.I 出力\c
\& します。`\|\c
.B v\c
\|' 修飾子が指定されたときは、メンバの内容を出力する前にメンバ名を出力
します。

.I files\c
を指定しなければ、アーカイブ内のすべてのファイルが出力されます。

.TP
.B q
\c
.I クイックアペンド\c
\&。\c
.I files\c
\& で指定されたファイルを、重複をチェックせずに\c
.I アーカイブ\c
\&の末尾に追加します。

`\|\c
.B a\c
\|'、`\|\c
.B b\c
\|'、`\|\c
.B i\c
\|'修飾子はこのオペレーションには\c
.I 影響しません\c
\&。新たなメンバは常にアーカイブの末尾に置かれます。

`\|\c
.B v\c
\|'修飾子を指定すると、\c
.B ar\c
\& は追加の際にそのファイル名を出力します。

このオペレーションの特徴は動作速度ですので、たとえ
シンボルテーブルのインデックスが存在したとしても、それを更新しません。
シンボルテーブルのインデックスを更新するには、明示的に`\|\c
.B ar s\c
\|'か
\c
.B ranlib\c
\& を使って下さい。

しかしながら、多くの異なるシステムにおいてクイックアペンドが
インデックスを再構築することが仮定されていますので、GNU
.B ar
は`\|\c
.B q\c
\|'は`\|\c
.B r\c
\|'と同じ動作をするように実装しています。

.TP
.B r
\c
files\c
\& をアーカイブに挿入(重複の際は\c
.I 置換\c
\&)します。
このオペレーションは`\|\c
.B q\c
\|'とは異なり、追加するファイルと同名のメンバがすでに存在する
場合は削除されます。

もし \c
.I files\c
\& で指定したファイルの中に存在しないものが一つでも含まれている場合は\c
.B ar\c
\& はエラーメッセージを出力し、そのファイル名と同名のメンバは変更
されずに保存されます。

デフォルトでは新しいメンバはファイルの末尾に追加されますが、`\|\c
.B a\c
\|'、`\|\c
.B b\c
\|'、または、`\|\c
.B i\c
\|' 修飾子を指定することにより、既存のメンバに対する相対的な位置関係を
指定することができます。

このオペレーションに `\|\c
.B v\c
\|' 修飾子を指定すると、挿入された各ファイルに対して、ファイルが追加
された(削除された古いメンバがない)か、置換されたかを示す `\|\c
.B a\c
\|' または
`\|\c
.B r\c
\|' のどちらかを含んだ一行が出力されます。

.TP
.B t
\c
.I アーカイブ\c
\& の内容、または \c
.I files\c
\& に列挙されたファイルのうち、アーカイブ内に存在するものの一覧を出力
します。通常はメンバ名だけを表示しますが、`\|\c
.B v\c
\|'修飾子を指定することにより、モード(パーミッション)、タイムスタンプ、
所有者、グループ、サイズも表示します。

\c
.I files\c
\& の指定がない場合はアーカイブ内のすべてのファイルの一覧を表示します。

あるアーカイブ(`\|\c
.B b.a\c
\|'とします)の中に同じ名前(`\|\c
.B fie\c
\|'とします)の複数のファイルが存在する場合は、`\|\c
.B ar t b.a fie\c
\|'は最初のファイルだけを表示します。同名のファイルをすべて見たい場合
はすべてのファイルの一覧を表示して下さい。(この例では`\|\c
.B ar t b.a\c
\|')

.TP
.B x
アーカイブから \c
.I files\c
\& で指定されたメンバを\c
.I 抽出\c
します。
`\|\c
.B v\c
\|'修飾子を指定すると、\c
.B ar\c
\& は抽出の際にそのファイル名を出力します。

\c
.I files\c
\& の指定がない場合はアーカイブ内のすべてのファイルを抽出します。

.PP

いくつかの修飾子(\c
.I mod\c
\&)をキー文字 \c
.I p\c
\& の直後に付けることによって、オペレーションの動作を変更する
ことができます。

.TP
.B a
新しいファイルを既存のメンバの\c
.I 後\c
\& に追加します。
\c
.B a\c
\& 修飾子を用いるときは、\c
.I archive\c
\& 引数の前に\c
.I membername\c
\& 引数として既存のメンバ名を指定する必要があります。

.TP
.B b
新しいファイルを既存のメンバの\c
.I 前\c
\& に追加します。
\c
.B b\c
\& 修飾子を用いるときは、\c
.I archive\c
\& 引数の前に\c
.I membername\c
\& 引数として既存のメンバの名前を指定する必要があります。(`\|\c
.B i\c
\|'と同じ。)

.TP
.B c
アーカイブの\c
.I 作成\c
\&。
存在しない\c
.I アーカイブ\
\& を更新するように指定した場合、そのアーカイブは必ず作成されますが、
その際、この修飾子を指定することによって、アーカイブを作成することを
明示していなければ、警告を出力します。

.TP
.B f
アーカイブ内の名前を切り詰める。
通常
.B ar
は任意の長さのファイル名を受け付けますが、このため、いくつかのシステム
で使われている従来の
.B ar
と互換性のないアーカイブが作成されることになります。これが問題になる
場合は、
.B f
修飾子を指定して、ファイルをアーカイブに追加する際にそのファイル名を
切り詰めることができます。

.TP
.B i
新しいファイルを既存のメンバの\c
.I 前\c
\& に挿入します。
\c
.B i\c
\& 修飾子を用いる時は、\c
.I archive\c
\& 引数の前に\c
.I membername\c
\& 引数として既存のメンバ名を指定する必要があります。(`\|\c
.B b\c
\|'と同じ。)

.TP
.B l
この修飾子は指定可能ですが、使用されません。

.TP
.B o
メンバを抽出する際に\c
.I オリジナル\c
\& の時刻を保存します。この修飾子を指定しないと、アーカイブから抽出
されたファイルのタイムスタンプは抽出時の時刻になります。

.TP
.B s
アーカイブに他の変更がない場合でも、アーカイブにオブジェクトファイルの
インデックスを書き込んだり、既存のインデックスを更新します。この修飾子
はほかのオペレーションと併用することも、単独で使用することも可能です。
あるアーカイブに対して`\|\c
.B ar s\c
\|'を実行することは、そのアーカイブに対して`\|\c
.B ranlib\c
\|'を実行することと等価です。

.TP
.B S
アーカイブのシンボルテーブルを作成しません。これを用いると大きな
ライブラリを何回かに分けて作成する際に時間を短縮することができます。
この結果得られるアーカイブはリンカで使用することはできません。
シンボルテーブルを作成するためには最後に `\|\c
.B ar\c
\|' を実行する時に `\|\c
.B S\c
\|' 修飾子を外すか、そのアーカイブに対して `\|\c
.B ranlib\c
\|' を実行する必要があります。

.TP
.B u
通常 \c
.B ar r\c
\&.\|.\|. は列挙されたファイルをすべてアーカイブに挿入します。
この修飾子を指定すると、指定したファイルが既存の同名のメンバより
新しい場合\c
.I のみ\c
\&ファイルを挿入します。
`\|\c
.B u\c
\|'修飾子は`\|\c
.B r\c
\|'(置換)オペレーションだけに付けることができます。
特に、タイムスタンプの確認は `\|\c
.B q\c
\|' オペレーションの利点である速度を低下させるので、`\|\c
.B qu\c
\|' の組み合わせは認められません。

.TP
.B v
オペレーションに対して
.I 冗長\c
\&な表示を要求します。
多くのオペレーションにおいて `\|\c
.B v\c
\|' 修飾子が指定されると、
処理されたファイル名などの付加的な情報が表示されます。

.TP
.B V
この修飾子は
.BR ar\c
\& のバージョン番号を表示します。

.PP

.SH 関連項目
.B
info\c
\&の
.RB "`\|" binutils "\|'"
の項; 
.I
The GNU Binary Utilities\c
, Roland H. Pesch (October 1991).
.BR nm ( 1 )\c
\&,
.BR ranlib ( 1 )\c
\&.

.SH COPYING
Copyright (c) 1991 Free Software Foundation, Inc.
.PP
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
.PP
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
.PP
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be included in
translations approved by the Free Software Foundation instead of in
the original English.