.\"    This file documents the GNU utilities for finding files that match
.\" certain criteria and performing various operations on them.
.\"
.\"    Copyright (C) 1994 Free Software Foundation, Inc.
.\"
.\"    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.
.\"
.\"    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.
.\"
.\"    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 stated in a
.\" translation approved by the Foundation.
.\"
.\" Japanese Version Copyright (c) 1997 NAKANO Takeo
.\"   and 2011 Chonan Yoichi,
.\"         all rights reserved.
.\" Translated Thu May 11 1997 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
.\" Modified Fri 14 Aug 1998 by NAKANO Takeo -- bug fixes.
.\" Updated and modified (findutils-4.4.2) Fri Jan 28 12:28:44 JST 2011
.\"         by Chonan Yoichi <cyoichi@maple.ocn.ne.jp>
.\"
.\"WORD    end of file string    ファイル終端文字列
.\"
.TH XARGS 1 \" -*- nroff -*-
.SH 名前
xargs \- 標準入力を読み込んでコマンドラインを作成し、それを実行する
.SH 書式
.B xargs
.nh
[\fB\-0prtx\fR] 
[\fB\-E \fIeof-str\fR] 
[\fB\-e\fR[\fIeof-str\fR]]
[\fB\-\-eof\fR[=\fIeof-str\fR]] 
[\fB\-\-null\fR] 
[\fB\-d \fIdelimiter\fR] 
[\fB\-\-delimiter \fIdelimiter\fR] 
[\fB\-I \fIreplace-str\fR] 
[\fB\-i\fR[\fIreplace-str\fR]] 
[\fB\-\-replace\fR[=\fIreplace-str\fR]] 
[\fB\-l\fR[\fImax-lines\fR]] 
[\fB\-L \fImax-lines\fR] 
[\fB\-\-max\-lines\fR[=\fImax-lines\fR]] 
[\fB\-n \fImax-args\fR] 
[\fB\-\-max\-args\fR=\fImax-args\fR] 
[\fB\-s \fImax-chars\fR] 
[\fB\-\-max\-chars\fR=\fImax-chars\fR] 
[\fB\-P \fImax-procs\fR] 
[\fB\-\-max\-procs\fR=\fImax-procs\fR]
[\fB\-\-interactive\fR] 
[\fB\-\-verbose\fR] 
[\fB\-\-exit\fR] 
[\fB\-\-no\-run\-if\-empty\fR] 
[\fB\-\-arg\-file\fR=\fIfile\fR] 
[\fB\-\-show\-limits\fR] 
[\fB\-\-version\fR] 
[\fB\-\-help\fR] 
[\fIcommand\fR [\fIinitial-arguments\fR]]
.hy
.SH 説明
このマニュアルページは GNU 版
.B xargs
の使用法を説明している。
.B xargs
は、標準入力から空白や改行で区切られた一連の項目を読み込み
(空白はダブルクォート、シングルクォート、バックスラッシュによって
保護できる)、それを引き数にして、指定した
.I command
を実行する (デフォルトのコマンドは
.I /bin/echo
である)。
このとき、ユーザが
.I command
に対して指定した引き数 (上記書式の
.IR initial-arguments )
があれば、
.B xargs
は標準入力から読み込んだ一連の項目をその後ろに
追加していく (訳注: 作成されたコマンドラインが、コマンドライン長の上限を
越える場合や、オプションによる特別な指定がある場合は、入力を適宜分割して、
.I command
を複数回実行することになる)。標準入力における空行は無視する。
.P
Unix ではファイル名に空白や改行を含むことが可能なので、この
デフォルトの動作は、しばしば問題を引き起こす。空白や改行を含む
ファイル名は、
.B xargs
によって適切に処理されないからだ。そうした状況では、
.B \-0
オプションを使用した方がよい。そうすれば、その手の問題を回避することができる。
なお、
.B \-0
オプションを使う場合は、
.B xargs
の入力を生成するプログラムの方も、区切りの記号として必ずヌル文字を
使うようにする必要がある。たとえば、そのプログラムが GNU
.B find
ならば、
.B \-print0
オプションでそれが可能だ。
.P
指定したコマンドの実行が終了ステータス 255 で終了することがあれば、
.B xargs
は即座に停止して、それ以上入力を読み込まない。また、このとき、
エラーメッセージを標準エラーに表示する。
.SH オプション
.TP
.PD 0
.BI "\-\-arg\-file=" file
.TP
.PD 0
.BI "\-a " file
一連の項目を標準入力からではなく、
.I file
から読み込む。なお、デフォルトでは、指定したコマンドを実行する際に、
標準入力が
.I /dev/null
に付け換えられるが、このオプションを使用した場合は、
標準入力の付け換えが起こらない
(訳注: 別の言い方をすると、指定したコマンドの実行中、デフォルトでは
標準入力が使えなくなるが、このオプションを指定した場合は、
標準入力が使えるということである)。

.TP
.PD 0
.B \-\-null
.TP
.PD
.B \-0
入力される一連の項目が、ホワイトスペース (空白や改行) ではなく、
ヌル文字によって区切られる。また、引用符やバックスラッシュが
特別な意味を持たなくなる (すなわち、あらゆる文字が文字通りに解釈される)。
後述のファイル終端文字列も無効になり、他の引き数と同じように扱われる。
このオプションは、入力される項目にホワイトスペース、引用符、
バックスラッシュなどが含まれる可能性がある場合に、役に立つ。
GNU
.B find
の 
.B \-print0
オプションが生成する出力は、このモードに対応した入力になる。

.TP
.PD 0
.BI "\-\-delimiter=" delim
.TP
.PD 
.BI \-d " delim"
入力される一連の項目が、指定された文字によって区切られる。引用符や
バックスラッシュは特別な意味を持たない。すなわち、入力中の
あらゆる文字が文字通りに解釈される。ファイル終端文字列も無効になり、
他の引き数と同じように扱われる。入力が、項目を区切るのが改行のみ
であるような単純な構成の場合なら、このオプションを利用してもよいが、
ほとんどたいていの場合、なるべくなら、
.B xargs
の
.B \-\-null
を使うように、出力側のプログラムを設計する方が望ましい。
指定する区切り記号は、単一の文字でもよく、
.B \en
のような C 言語式のエスケープした文字でも、8 進数や 16 進数の
エスケープコードでもよい。8 進数や 16 進数のエスケープコードは、
.B printf
コマンドの場合と同様に解釈される。マルチバイト文字には対応していない。

.TP
.BI \-E " eof-str"
\fIeof-str\fR をファイル終端文字列として設定する。ファイル終端文字列が
入力行の中に現れると、それ以後の入力は無視される。
.B \-E
も
.B \-e
も指定しない場合、ファイル終端文字列は使用されない。
.TP 
.PD 0
.BR "\-\-eof" [\fI=eof-str\fR]
.TP 
.PD
.BR \-e [ \fIeof-str\fR]
このオプションは
.B \-E
オプションの同義語である。
.B \-E
の方を使ってほしい。理由は、そちらが POSIX に準拠しているのに対して、
こちらは準拠していないからだ。\fIeof-str\fR の部分が省略されると、
ファイル終端文字列が存在しないことになる。
.B \-E
も
.B \-e
も指定しない場合、ファイル終端文字列は使用されない。
.TP
.B "\-\-help"
.B xargs
のオプションについて簡単に説明し終了する。
.TP
.BI \-I " replace-str"
.B xargs
が実行するコマンドにに対してユーザが引き数 (すなわち
\fIinitial\-arguments\fR) を指定したとき、その \fIinitial\-arguments\fR
中にある \fIreplace-str\fR の部分すべてを、標準入力から読み込んだ名前で
置き換える。
なお、空白は、クォートされていない場合も、入力される項目の区切りには
ならない。区切り記号は改行文字だけになるのだ。
.B \-x
と
.BR \-L " 1"
が自動的に設定される。
.TP
.PD 0
.BR "\-\-replace" [\fI=replace-str\fR]
.TP
.PD
.BR  \-i "[\fIreplace-str\fR]"
このオプションは、
.I replace-str
が指定されていれば、
.BI \-I replace-str
の同義語であり、指定されていなければ、
.BR \-I {}
の同義語である。このオプションは非推奨になっている。
.B \-I
を使った方がよい。
.TP
.BI \-L " max-lines"
1 コマンドラインにつき最大 \fImax-lines\fR 行の (空行ではない) 入力行を
使用する。入力行の行末に空白文字が付いていると、その行は
次の入力行に論理的に続いていることになる。自動的に
.B \-x
が指定される。
.TP
.PD 0
.BR \-\-max-lines "[=\fImax-lines\fR]"
.TP
.PD
.BR \-l "[\fImax-lines\fR]"
.B \-L
オプションの同義語である。
.B \-L
とは違って、
.I max-lines
という引き数を指定するかどうかは任意である。引き数
.I max-lines
を指定しなかった場合は、デフォルトの 1 が使用される。
POSIX 標準では
.B \-L
の方を使うことになっているので、
.B \-l
オプションの使用はお勧めできない。
.TP
.PD 0
.BR "\-\-max\-args" =\fImax-args\fR
.TP
.PD
.BI \-n " max-args"
1 コマンドラインにつき最大 \fImax-args\fR 個の引き数を使用する。
作成されたコマンドラインが、コマンドライン長の上限を
超過する場合は
.RB ( \-s
オプション参照)、
.I max-args
より少ない引き数が使用されることになる。ただし、
.B \-x
オプションが指定されているときは別で、その場合は
.B xargs
が終了する。
.TP
.PD 0
.B \-\-interactive
.TP
.PD
.B \-p
コマンドライン一行ごとに、実行するかどうかをユーザに尋ねるプロンプトを出し、
端末から一行読み込む。コマンドラインを実行するのは、返答が `y' または `Y' で
始まるときだけである。自動的に
.BR -t
が指定される。
.TP
.PD 0
.B \-\-no\-run\-if\-empty
.TP
.PD
.B \-r
標準入力に空白しか含まれていない場合は、指定したコマンドを実行しない。
通常では、入力が全くない場合でも、コマンドが一回は実行されるのだ。
このオプションは GNU の拡張である。
.TP
.PD 0
.BR \-\-max\-chars "=\fImax-chars\fR"
.TP
.PD
.BI \-s " max-chars"
1 コマンドラインにつき最大 \fImax-chars\fR の文字を使用する。
この文字数には、指定したコマンドと \fIinitial\-arguments\fR、それに
各引き数文字列の終端を示すヌル文字も含まれる。指定できる値の上限は
システム次第であり、exec に対する引き数の最大長から、
現在の環境のサイズと 2048 バイトの余裕領域を引いたものである。
もしその値が 128KiB 以上だったときは、デフォルトの値として 128KiB が
使用される。128KiB 未満だったときは、算出された上限がデフォルトの値になる。
1KiB は 1024 バイトである。
.TP
.PD 0
.B \-\-verbose
.TP
.PD
.B \-t
実行する前に、コマンドラインを標準エラー出力に表示する。
.TP
.B "\-\-version"
.B xargs
のバージョン番号を表示して、終了する。
.TP
.B "\-\-show\\-limits"
コマンドライン長の上限を表示する。コマンドライン長の上限は、
オペレーティングシステム、
.B xargs
が設定したバッファサイズ、
.B \-s
オプションによって決まる。
.B xargs
にコマンドライン長の上限の表示以外をさせたくなかったら、
入力を
.I /dev/null
からパイプで
.B xargs
に渡すとよい (さらに
.B --no-run-if-empty
を指定した方がよいかもしれない)。
.TP
.PD 0
.B \-\-exit
.TP
.PD
.B \-x
作成されたコマンドラインがコマンドライン長の上限を超過していたら
.RB ( \-s
オプションを参照)、終了する。
.TP
.PD 0
.BR \-\-max\-procs "=\fImax-procs\fR" 
.TP
.PD
.BI \-P " max-procs"
同時に最多で
.I max-procs
プロセスまで指定したコマンドを実行する。デフォルトは 1 である。もし
.I max-procs
が 0 だと、
.B xargs
はできるだけ多くのプロセスを同時に実行しようとする。
.B \-P
と一緒に
.B \-n
オプションを使うとよい。さもないと、exec がたった一回しか
行われないかもしれない。
.SH "用例"
.nf
.B find /tmp \-name core \-type f \-print | xargs /bin/rm \-f

.fi
.B /tmp
ディレクトリ以下に
.B core
という名前のファイルを捜して、それを消去する。改行や空白を含む
ファイル名があると、正しく動作しないので、注意すること。
.P
.B find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f

.fi
.B /tmp
ディレクトリ以下に
.B core
という名前のファイルを捜して、それを消去する。ファイル名の処理に
当たっては、ファイルやディレクトリの名前に空白や改行が含まれていても、
適切に扱われるようにする。

.P
.B find /tmp \-depth \-name core \-type f \-delete

.fi
.B /tmp
ディレクトリ以下に
.B core
という名前のファイルを捜して、それを消去する。上の例よりも
こちらの方が効率的である (なぜなら、
.B rm
を実行するために
.BR fork (2)
と
.BR exec (2)
を使わないですむし、そもそも、
.B xargs
のプロセスを必要としないから)。

.P
.nf
.B cut \-d: \-f1 < /etc/passwd | sort | xargs echo

.fi
システムの全ユーザを列挙した簡潔なリストを生成する (訳注: 要するに、
改行ではなく、空白で区切られたユーザ名のリストを作るということ)。

.P
.nf
.B xargs sh -c 'emacs \(dq$@\(dq < /dev/tty' emacs

.fi
.B xargs
の標準入力からファイルのリストを受け取り、Emacs を必要なだけ次々と
立ち上げて、それを編集する。この例は BSD の
.B -o
オプションと同じことを実現するが、こちらの方が柔軟性があり、
多くのシステムで利用できる。



.SH "終了ステータス"
.B xargs 
の終了ステータスは以下のとおりである。
.P
.nf
0 成功した。
123 指定したコマンドの実行が 1-125 のステータスで終了した。
124 指定したコマンドが 255 のステータスで終了した。
125 指定したコマンドがシグナルによって kill された。
126 指定したコマンドが実行できない。
127 指定したコマンドが見つからない。
1 上記以外のエラーが起きた。
.fi
.P
128 以上の終了ステータスは、致命的なシグナルのせいでプログラムが
止まったことを示すために、シェルが使用している。
.SH "標準への準拠"
GNU xargs version 4.2.9 以来、ファイルの論理的な終端を示す指標
(a logical end-of-file marker) を持たないのが、
.B xargs
のデフォルトになっている。このことは POSIX (IEEE Std 1003.1,
2004 Edition) で認められている。
.P
\-l や \-i オプションは 1997 年版の POSIX 標準には存在するが、
2004 年版の POSIX 標準には存在しない。従って、それぞれ
\-L や \-I の方を使うべきである。
.P
POSIX 標準は、実装に当たって、
.B exec
関数に対する引き数のサイズに上限を設けることを認めている。
そして、その上限は、環境のサイズも含めて、少なくとも 4096 バイトあれば
よいことになっている。移植性のあるスクリプトを書こうと思ったら、
これより大きいサイズを当てにしてはいけない。もっとも、実際の上限が
そんなに小さい実装など、筆者としては見たことも聞いたこともないけれど。
.B \-\-show\-limits
オプションを使えば、使用中のシステムで有効な実際の上限を知ることができる。


.SH "関連項目"
\fBfind\fP(1), \fBlocate\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1),
\fBfork\fP(2), \fBexecvp\fP(3), 
\fBFinding Files\fP (on-line in Info, or printed)
.SH "バグ"
.B \-L
オプションと
.B \-I
オプションを組み合わせても、うまく行かない。組み合わせて使えた方が
よいのかもしれないが。
.IP "[訳注]:" 8 
.B -I
オプションの説明にあるように、
.BI \-I " replace-str"
を指定すると、
.BR \-L " 1"
が自動的に設定される。ここで言っているのは、現状では
.BR \-L " 2"
や
.BR \-L " 3"
を
.B \-I
と一緒に使っても、期待する効果を得られないということである。
.P
.B xargs
を安全に使うことは不可能である。なぜなら、入力されるファイル名の
リストを生成する時間と
.B xargs
が実行するコマンドがそれを使用する時間との間には、必ず時間差が
あるからだ。もし、他のユーザがシステムにアクセスすることができれば、
そのユーザはこの隙間の時間にファイルシステムを操作して、
.B xargs
が実行するコマンドの動作を、こちらが意図していないファイルに
無理矢理向けることができる。この問題や、これに関連する問題については、
findutils に含まれる Texinfo 文書の「Security Considerations」という章で
もっと細かく論じているので、そちらを参照していただきたい。
なお、
.B find
の
.B \-execdir
オプションは、より安全な方法として
.B xargs
の代わりに使用できることが多い。

.B \-I
オプションを使うと、標準入力から読み込まれた各行は内部的にバッファされる。
これは、
.B \-I
オプションを付けて使ったとき、
.B xargs
が受け付ける入力行一行の長さに上限があるということだ。
この制限を回避するためには、
.B \-s
オプションを使って、
.B xargs
が使用するバッファ空間のサイズを増やしてやればよい。さらに、
.B xargs
をもう一つ実行すれば、
長すぎる行の出現を確実に避けることができる。
たとえば、
.P
.B somecommand | xargs \-s 50000 echo | xargs \-I '{}' \-s 100000 rm '{}'
.P
この例では、
.B xargs
の最初の実行には、入力行の長さの上限がない。
.B \-I
オプションを使っていないからである。
.B xargs
の二番目の実行には、そうした上限があるが、処理できる以上の長さの行に
絶対に出会わないようになっている。これが理想的な解決法だ
というのではない。むしろ、
.B \-I
オプションによって入力行の長さに上限ができない方がよいのであり、
だからこそ、この問題を「バグ」セクションで論じているのである。
なお、この問題は
.BR find (1)
の出力では起きない。
.B find
は 1 行に 1 ファイル名しか出力しないからだ。 
.P
バグ報告の最善の方法は、
http://savannah.gnu.org/bugs/?group=findutils
にある書式を使用することだ。そうすれば、問題解決の進行状態を
追うことができるからである。\fBxargs\fP(1) や
findutils パッケージ全般についてのその他のご意見は、
.I bug\-findutils
メーリングリストにお出しになればよい。メーリングリストに参加するには、
.I bug\-findutils\-request@gnu.org
宛てに E メールを送っていただきたい。