diff --git a/ja_JP.eucJP/man/man1/rtld.1 b/ja_JP.eucJP/man/man1/rtld.1 index d6d0d8306a..4ae5371db8 100644 --- a/ja_JP.eucJP/man/man1/rtld.1 +++ b/ja_JP.eucJP/man/man1/rtld.1 @@ -1,155 +1,157 @@ -.\" %FreeBSD: src/libexec/rtld-elf/rtld.1,v 1.18.2.6 2001/08/16 10:44:20 ru Exp % +.\" %FreeBSD: src/libexec/rtld-elf/rtld.1,v 1.18.2.7 2002/01/10 17:51:28 ru Exp % .\" .\" Copyright (c) 1995 Paul Kranenburg .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgment: .\" This product includes software developed by Paul Kranenburg. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $FreeBSD: doc/ja_JP.eucJP/man/man1/rtld.1,v 1.6 2001/07/29 05:14:52 horikawa Exp $ +.\" $FreeBSD$ .Dd January 28, 2000 .Dt RTLD 1 .Os .Sh 名称 .Nm ld-elf.so.1 , .Nm rtld .Nd 実行時リンクエディタ .Sh 解説 .Nm は自己完結した共有オブジェクトで、 実行時にプロセスのアドレス空間に共有オブジェクトを読み込んで 編集する機能を提供します。 一般には動的リンカという名前でも知られています。 動的リンクされたプログラムに含まれるデータ構造を使って どの共有ライブラリが必要なのかを決定し、 .Xr mmap 2 システムコールを使ってそれらを読み込みます。 .Pp 全ての共有ライブラリを読み込むことに成功すると、次に .Nm はメインプログラムおよび読み込んだ 全てのオブジェクトからの外部参照を解決します。 プログラム本体の実行が始まる前になんらかの設定をする機会を 共有オブジェクトに与えるために、 オブジェクトごとに初期化ルーチンを呼ぶ機構があります。 これは静的コンストラクタを含むような C++ ライブラリにとって有用です。 .Pp 実行されるプログラムが動的にリンクされている場合には、そのプログラムと一緒に .Nm 自体がカーネルによって読み込まれます。 そしてカーネルは動的リンカに制御を移します。 動的リンカがプログラムとそれに必要な共有オブジェクトの 読み込み、再配置、初期化を終えると、 プログラムのエントリポイントに制御を移します。 .Pp ファイルシステム中にある必要な共有オブジェクトを探索するために、 .Nm は .Xr ldconfig 8 ユーティリティによって用意される .Dq hints ファイルを使います。 .Pp .Nm は以下に挙げるような、 自身の動作を変えるために使用されるいくつかの環境変数を認識します: .Pp -.Bl -tag -width LD_LIBRARY_PATH +.Bl -tag -width ".Ev LD_LIBRARY_PATH" .It Ev LD_LIBRARY_PATH コロンで区切られたディレクトリのリストで、 共有ライブラリのデフォルトサーチパスを上書きします。 この環境変数は、 set-user-ID 及び set-group-ID されたプログラムにおいては無視されます。 .It Ev LD_PRELOAD 他の共有ライブラリより前にリンクされるべき共有ライブラリのリストで、 コロンか空白で区切られています。 もしディレクトリが指定されていないならば、 -最初に LD_LIBRARY_PATH で指定されるディレクトリから、 +最初に +.Ev LD_LIBRARY_PATH +で指定されるディレクトリから、 続いて組み込みの標準ディレクトリ群から検索されます。 この環境変数は、 set-user-ID 及び set-group-ID されたプログラムにおいては無視されます。 .It Ev LD_BIND_NOW 空ではない文字列が設定されている場合には、 .Nm は、全ての外部関数呼び出しをプログラムの実行を始める前に再配置します。 通常、関数呼び出しの結合は遅延方式 (lazy binding) で行われます。 すなわち、関数呼び出しはそれぞれの関数が最初に呼ばれる時に結合されます。 .Ev LD_BIND_NOW はプログラムの起動時間を増加させますが、 実行時に思いもかけず関数が定義されていなかったという事件は避けられます。 .It Ev LD_TRACE_LOADED_OBJECTS 空ではない文字列が設定されている場合には、 .Nm は共有オブジェクトを読み込んで、全てのオブジェクトの絶対パス名を含む 概要を標準出力に表示した後に終了します。 .It Ev LD_TRACE_LOADED_OBJECTS_FMT1 .It Ev LD_TRACE_LOADED_OBJECTS_FMT2 設定されている場合には、 これらの変数は トレース出力をカスタマイズするための .Xr printf 3 流フォーマット文字列として解釈されます。 .Xr ldd 1 の .Fl f オプションがこれらを使用するので、 .Xr ldd 1 をより便利にフィルタとして使うことができます。 以下の変換を使うことができます: -.Bl -tag -width "xxxx" -.It \&%a +.Bl -tag -width 4n +.It Li %a メインプログラムの名前 (またの名を .Dq __progname ) 。 -.It \&%A +.It Li \&%A .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME 環境変数の値。 -.It \&%o +.It Li %o ライブラリの名前。 -.It \&%m +.It Li %m ライブラリのメジャーバージョン番号。 -.It \&%p +.It Li %p .Nm rtld のライブラリ検索ルールで決定されるフルパス名。 -.It \&%x +.It Li %x ライブラリのロードアドレス。 .El .Pp さらに、 -.Sy \en +.Ql \en と -.Sy \et +.Ql \et が認識され、通常の意味をもちます。 .El .Sh 関連ファイル .Bl -tag -width indent .It Pa /var/run/ld-elf.so.hints .El .Sh 関連項目 .Xr ld 1 , .Xr ldd 1 , .Xr elf 5 , .Xr ldconfig 8 diff --git a/ja_JP.eucJP/man/man7/groff_mdoc.7 b/ja_JP.eucJP/man/man7/groff_mdoc.7 index 8d170f9556..9f94ac46d2 100644 --- a/ja_JP.eucJP/man/man7/groff_mdoc.7 +++ b/ja_JP.eucJP/man/man7/groff_mdoc.7 @@ -1,4116 +1,4116 @@ .\" groff_mdoc.man .\" .\" A complete reference of the mdoc macro package for GNU troff. .\" .\" Based on NetBSD's mdoc.samples.7, version 1.21. .\" .\" .\" Warning: You can't format this file with the old mdoc macros! .\" .\" .\" Copyright (c) 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)mdoc.samples.7 8.2 (Berkeley) 12/30/93 .\" .\" This reference invokes every macro in the package several .\" times and is guaranteed to give a worst case performance .\" for an already extremely slow package. .\" .\" $FreeBSD$ .\" Copyright (c) 2001 FreeBSD jpman project .\" This is for Japanese translation done by FreeBSD jpman project. .\" WORD: epoch 基準時点 (協定世界時 1970年1月1日 00:00:00) .\" WORD: display ディスプレイ .\" WORD: bracket 角括弧 [] .\" WORD: brace 中括弧 () .\" WORD: angle bracket 山括弧 <> .\" WORD: acronym 頭字語 .\" WORD: keep キープ .\" WORD: literal リテラル .\" WORD: content macro コンテントマクロ .\" WORD: command modifier コマンド修飾子 .\" WORD: enclosure 囲い .\" WORD: quoting クォート .\" WORD: nest 入れ子 .\" WORD: block ragged 凹凸ブロック .\" WORD: constant width character 定幅文字 .\" WORD: scale indicator スケール指示子 .\" WORD: hanging tag ぶら下がりタグ .\" WORD: overhanging tag オーバハングタグ .\" WORD: parsed 構文解析される .\" WORD: callable 呼び出し可能 . .Dd July 20, 2001 .Os .Dt GROFF_MDOC 7 . . .Sh 名称 . .Nm groff_mdoc .Nd groff mdoc の実装に関するリファレンス . . .Sh 書式 . .Nm groff Fl m Ns Cm doc Ar . . .Sh 解説 . .Tn GNU .Xr troff 1 用の .Em コンテントベース でかつ .Em 領域ベース な整形用パッケージである .Nm \-mdoc マクロパッケージを使って .Ux マニュアルページを書くための完全なリファレンスです。 前身である .Xr \-man 7 パッケージは、フォントの操作や他の写植方法の詳細は個々の作者に任せ、 ページのレイアウトを取り扱ってきました。 .Nm \-mdoc では、ページレイアウトマクロは タイトル、セクションのヘッダ、ディスプレイ、リストのマクロからなる .Em "ページ構造領域" を形成しています。本質的にこれらの要素は整形されたページにおける テキストの物理的位置に影響を与えます。 ページ構造領域に加え、さらに .Em マニュアル 領域および .Em 一般 テキスト領域の 2 つの領域があります。 一般テキスト領域は、テキストの一部をクォートしたり強調したりと いったような作業を実行するマクロとして定義されています。 マニュアル領域はコマンドやルーチン、それに .Ux の関連ファイルを記述するための日常使用されるインフォーマルな言葉の サブセットであるマクロとして定義されています。 マニュアル領域のマクロはコマンド名、コマンド行の引数とオプション、 関数名、関数のパラメータ、パス名、変数名、他のマニュアルページへの クロスリファレンスなどを扱います。 これらの領域の項目は作者とマニュアルページの将来のユーザの両者に とって価値のあるものです。 マニュアル間で一貫性を高めることによって将来のドキュメントツールへの 移行が容易になることが期待されます。 .Pp .Ux マニュアルページ全体を通して、マニュアルのエントリは単純に マニュアルページ (a man page) とみなされます。 これは実際のページ数と関係ありませんし、性差別をする意図もありません。 .\" 訳注: a man page -- 1 ページ (a page) と男 (man) の意味 . . .Sh "さあ、始めよう" . このドキュメントの残りの部分で説明されている題材は以下のような構成に なっています。 . .Bl -enum -width 3n -offset indent . It . Tn "TROFF に特有な表現" . . Bl -tag -width 2n -compact . It "マクロの使用方法" . It "引数に空白文字を指定する" . It "行末の空白文字" . It "特殊文字のエスケープ" . It "その他の注意点" . El . . It . Tn "マニュアルページのテンプレート" . . It . Tn "使用法" . . It . Tn "タイトルマクロ" . . It . Tn "マニュアル領域および一般テキスト領域の紹介" . . Bl -tag -width 2n -compact . It "この名前には何が" Ns ... . It "一般的な構文" . El . . It . Tn "マニュアル領域" . . Bl -tag -width 2n -compact . It "アドレス" . It "作者名" . It "引数" . It "コンフィギュレーション宣言 (セクション 4 のみ)" . It "コマンド修飾子" . It "定義済みの変数" . It "errno (セクション 2 のみ)" . It "環境変数" . It "フラグ" . It "関数の宣言" . It "関数の型" . It "関数 (ライブラリルーチン)" . It "関数の引数" . It "戻り値" . It "終了ステータス" . \" .It "ヘッダファイル (ソースコードを含む)" . It "対話的なコマンド" . It "ライブラリ名" . It "リテラル" . It "名称" . It "オプション" . It "パス名" . It "標準" . It "変数の型" . It "変数" . It "マニュアルページのクロスリファレンス" . El . . It . Tn "一般テキスト領域" . . Bl -tag -width 2n -compact . It "AT&T マクロ" . It "BSD マクロ" . It "NetBSD マクロ" . It "FreeBSD マクロ" . It "OpenBSD マクロ" . It "BSD/OS マクロ" . It "UNIX マクロ" . It "強調マクロ" . It "フォントモード" . It "囲い/クォート マクロ" . It "無操作もしくは通常テキストマクロ" . It "空白なしマクロ" . It "セクションのクロスリファレンス" . It "記号" . It "数式記号" . It "参考文献と引用" . It "商標名 (頭字語とタイプ名)" . It "拡張引数" . El . . It . Tn "ページ構造領域" . . Bl -tag -width 2n -compact . It "セクションヘッダ" . It "サブセクションヘッダ" . It "段落と行スペース" . It "キープ" . It "例示とディスプレイ" . It "リストとカラム" . El . . It . Tn "その他のマクロ" . . It . Tn "定義済みの文字列" . . It . Tn "診断" . . It . Tn "GROFF, TROFF および NROFF を使用した整形" . . It . Tn "関連ファイル" . . It . Tn "関連項目" . . It . Tn "バグ" .El . .\" XXX .if t \ . ne 7 . . .Sh "TROFF に特有な表現" . .Nm \-mdoc パッケージは、マニュアルページを記述するプロセスを簡単にすることを 目的としています。 .Nm \-mdoc を使うために .Tn GNU .Xr troff 1 のゴタゴタした詳細を学ぶ必要がないのが理想ですが、 いくつか片付けるべき避けられない制限事項があります。 また、このパッケージは高速で .Em ない ということも予め警告しておきます。 . .Ss "マクロの使用方法" . .Tn GNU .Xr troff 1 のように、マクロは .Ql .\& (ドット) を行頭に置き、それに続けて 2 文字 (または 3 文字) からなる マクロの名称を指定することによって呼び出されます。 ドットとマクロの間にはスペースを置くことができます (ただし、タブを置くことは .Em できません )。 引数はマクロの後にスペースで区切って指定することができます (やはり、タブは使用できません)。 行頭にドットを指定することによって .Tn GNU .Xr troff 1 にそれに続く 2 文字 (あるいはそれより多い文字) を マクロ名として解釈するよう指示しています。 最初にドット 1 文字をとり、その後ろに何も来ない場合は 無視されます。 マクロを起動させたくないような文脈で、入力行の先頭に .Ql .\& (ドット) を置くためには、 .Ql .\& (ドット) の前にエスケープシーケンス .Ql \e& を指定します。 .Ql \e& は文字通りスペース幅が 0 として解釈され、出力には現れません。 .Pp 一般的に .Tn GNU .Xr troff 1 マクロは取り得る引数の数に制限はありません (9 つ以上の 引数を扱うことのできない他のバージョンの troff とは違います)。 限られた場合ではありますが、引数を次の行に続けたり、拡張したり することができます (後述の .Sx 拡張引数 のセクションを参照)。 ほとんどすべてのマクロで引用符に囲まれた引数を扱うことができます (後述の .Sx 引数に空白文字を指定する のセクションを参照)。 .Pp .Nm \-mdoc での一般テキスト領域とマニュアル領域のほとんどのマクロは、 呼び出し可能なマクロ名を決定するためにその引数のリストが .Em 構文解析 されるという点で特別なものです。 これはつまり、一般テキスト領域またはマニュアル領域のマクロ名に一致し、 かつ、呼び出し可能であると判断された引数リスト中の引数は、 処理される時に実行されるか、もしくは呼び出されるということです。 この場合、引数がマクロの名前であっても .Ql .\& (ドット) で前置されません。 このようにしてたくさんのマクロを入れ子にすることができます。 例えばオプションマクロ .Ql .Op はフラグマクロおよび引数マクロ .Ql \&Fl と .Ql \&Ar を .Em 呼び出し て、オプションのフラグを引数とともに指定することができます: . .Bl -tag -width ".Op Fl s Ar bytes" -offset indent .It Op Fl s Ar bytes は .Ql ".Op Fl s Ar bytes" で生成されます。 .El . .Pp 文字列がマクロ名と解釈されないようにするには、 その文字列の前にエスケープシーケンス .Ql \e& を指定します。 . .Bl -tag -width ".Op \&Fl s \&Ar bytes" -offset indent .It Op \&Fl s \&Ar bytes は .Ql ".Op \e&Fl s \e&Ar bytes" で生成されます。 .El . .Pp ここで文字列 .Ql \&Fl と .Ql \&Ar はマクロとして解釈されていません。 このドキュメントを通じて、 呼び出し可能な引数を調べるために引数リストが構文解析されるマクロは .Em 構文解析される マクロとして参照し、 引数リストから呼び出されることができるマクロは .Em 呼び出し可能 なマクロとして参照します。 .Nm \-mdoc のマクロはほとんどすべてが構文解析されるのですから、これは技術的には .Em 適当でない 表現ですが、常にマクロを「呼び出し可能である」とか「他のマクロを 呼び出すことができる」と表現するのは面倒なことであるため、 「構文解析される」という用語を使います。 . .Ss "引数に空白文字を指定する" . 1 つ以上の空白文字を含む文字列を引数として指定したい 場合があります。 引数リスト中の要素が特定の並びをしていることを 期待しているマクロに引数を指定する時に必要になることがあります。 さらに、こうすると .Nm \-mdoc が速く実行されるようになるのです。 例えば、関数マクロ .Ql .Fn では第 1 引数は関数名であり、残りの引数が関数のパラメータであると 想定されています。 .Tn ANSI\~C では、関数のパラメータ宣言を括弧で囲まれたパラメータリスト中に 明示することを規定しているので、 各パラメータは最低でも 2 語の文字列となります。 例えば、 .Fa int foo のようになります。 .Pp 空白を含む引数を指定するには 2 通りの方法があります。 1 つは、空白を含む文字列を渡すのに、固定の空白、 つまりパディングされない空白文字 .Ql \e\ を使う方法です。すなわち、空白の前にエスケープ文字 .Ql \e を指定します。 この方法はどのマクロでも使うことができますが、1 行が長くなり過ぎた テキストを調整するときの邪魔になるという副作用があります。 .Xr troff では、固定の空白は他の印刷可能な文字と同様に扱われ、通常期待されるように その箇所で文字列を空白や改行で分けることは行われなくなります。 この方法は文字列が行の境界にまたがることが好ましくない場合に有用です。 代替案としては、 パディング可能 (すなわち伸長可能) で分割不可能な空白 .Ql \e~ を使うことがあります (これは、 .Tn GNU .Xr troff 1 拡張です)。 2 つ目の方法は、文字列をダブルクォートで括ることです。 .Pp 例えば、次のようにします: . .Bl -tag -width ".Fn fetch char\ *str" -offset indent .It Fn fetch char\ *str は .Ql ".Fn fetch char\e *str" で生成されます。 .It Fn fetch "char *str" も .Ql ".Fn fetch \*[q]char *str\*[q]" で生成することができます。 .El . .Pp もし、空白およびダブルクォートの前の .Ql \e が省略されていた場合には .Ql .Fn は引数が 3 つであるとみなし、その結果は .Pp .Dl Fn fetch char *str .Pp となります。 .\" For an example of what happens when the parameter list overlaps a newline .\" boundary, see the .\" .Sx BUGS .\" section. . .Ss "行末の空白文字" . .Xr Troff は行末に空白文字があると混乱してしまうことがあります。 .Ao 空白 Ac Ns Ao 行末 Ac の文字の並びからすべての空白文字を取り除くのは良い予防策です。 どうしても行末に空白文字をおく必要性が出てきた場合は、 パディングされない空白とエスケープ文字 .Ql \e& を使用することによって対応できます。 例えば、 .Ql string\e\ \e& のようにします。 . .Ss "特殊文字のエスケープ" . 改行 .Ql \en のような特殊文字は、バックスラッシュを保存するために .Ql \e を .Ql \ee で置き換え (たとえば .Ql \een とする) て扱います。 . .Ss "その他の注意点" . 表示領域外で空の入力行が見つかった場合には警告が発生します (後述)。 代わりに .Ql .sp を使用してください ( .Nm \-mdoc マクロを使用して、低レベルコマンドを使用しないようにすると ずっと良いです)。 .Pp 先頭に空白を置くと行分割が生じ、そのまま出力されてしまいます。 可能ならばこうなることを避けてください。 同様に、通常のテキスト行において単語間に 2 つ以上の空白文字を 使用しないでください。これは、他のテキストフォーマッタとは 対照的です。空白文字を 2 つ以上置いても 1 つの空白文字に .Em 置き換わりません 。 .Pp 引数として .Ql \*[q] を直接渡すことはできません。 代わりに .Ql \e*[q] (あるいは .Ql \e*q ) を使用してください。 .Pp デフォルトでは、 .Xr troff 1 は文を終了させる句読点の後に空白文字を 2 つ挿入します。 つまり、 .Ql \&) あるいは .Ql \&' などの文字はそのまま扱われ、文の終了には影響を与えません。 この動作を変更するには、 ドットの前あるいは後に .Ql \e& を挿入してください。 . .Bd -literal -offset indent The \&.Ql . character. \&.Pp The \&.Ql \e&. character. \&.Pp \&.No test . test \&.Pp \&.No test. test .Ed .Pp . は、 . .Bd -filled -offset indent The .Ql . character. .Pp The .Ql \&. character. .Pp .No test . test .Pp .No test. test .Ed .Pp となります。 .Pp . 1 行目および 3 行目にみられるように、 .Nm \-mdoc はマクロ引数の中では句読点を特別に扱います。 これについては、後述の .Sx 一般的な構文 の節で述べます。 同様の方法で、幅 0 の空白を続けることで、 省略形の後に続いたピリオドを保護しなくてはなりません。 例えば .Ql e.g.\e& のようにします。 .Pp マニュアルページのソースファイル中のコメントは、 独立した行では .Ql .\e" 、何らかの入力があった後では .Ql \e" を、あるいはどのような場所でも使いたい場合は .Ql \e# を使うことができます (後者は .Tn GNU .Xr troff 1 拡張です)。このような行の残りの部分は無視されます。 . . .Sh "マニュアルページのテンプレート" . マニュアルページの中身は次のような基本的なテンプレートから 簡単に作成できます。 . .Bd -literal -offset indent \&.\e" 以下の項目はすべてのマニュアルページで必要な項目です。 \&.Dd 月 日, 年 \&.Os [オペレーティングシステム] [バージョン/リリース] \&.Dt ドキュメントタイトル [セクション番号] [アーキテクチャ/ボリューム] \&.Sh NAME \&.Nm 名称 \&.Nd 名称についての 1 行での説明 \&.\e" 次の項目はセクション 2, 3 でのみ必要なものです。 \&.\e" .Sh LIBRARY \&.Sh SYNOPSIS \&.Sh DESCRIPTION \&.\e" 以下の項目については、必要に応じてコメントをはずして使用してく \&.\e" ださい。 \&.\e" .Sh IMPLEMENTATION NOTES \&.\e" この次の項目はセクション 2, 3, 9 でのみ必要な、関数の \&.\e" 戻り値です。 \&.\e" .Sh RETURN VALUES \&.\e" 次の項目はセクション 1, 6, 7, 8, 9 でのみ必要なものです。 \&.\e" .Sh ENVIRONMENT \&.\e" .Sh FILES \&.\e" .Sh EXAMPLES \&.\e" 次の項目はセクション 1, 6, 7, 8, 9 でのみ必要なものです。 \&.\e" ((シェルへの)コマンドの戻り値と \&.\e" fprintf/stderr タイプの診断です) \&.\e" .Sh DIAGNOSTICS \&.\e" .Sh COMPATIBILITY \&.\e" 次の項目はセクション 2, 3, 9 でのみ必要な、 \&.\e" エラーハンドリングとシグナルハンドリングです。 \&.\e" .Sh ERRORS \&.\e" .Sh SEE ALSO \&.\e" .Sh STANDARDS \&.\e" .Sh HISTORY \&.\e" .Sh AUTHORS \&.\e" .Sh BUGS .Ed .Pp . このテンプレートにおける最初の項目はマクロ .Ql .Dd , .Ql .Os , および .Ql .Dt であり、それぞれドキュメントの日付、 マニュアルページもしくは題材となっているソースの開発や変更の 対象となったオペレーティングシステム、そして マニュアルページのタイトルを属するマニュアルのセクション番号と ともに ( .Em 大文字で ) 指定したもの、となっています。 これらのマクロはそのページを識別するものであり、後述の .Sx タイトルマクロ で解説されます。 .Pp テンプレート中の残りの項目はセクションのヘッダ .Pf ( Li .Sh ) であり、それらのうち .Sx NAME , .Sx SYNOPSIS , および .Sx DESCRIPTION は必須項目です。 これらのヘッダについては .Sx "マニュアル領域" を説明した後、 .Sx "ページ構造領域" で解説されます。 いくつかのコンテントマクロはページレイアウトマクロの説明に 使用されていますので、ページレイアウトマクロの前にコンテントマクロに ついて読むことを推奨します。 . . .Sh 使用法 . 次に説明するマクロはすべて、オプションの引数は 角括弧 ([]) で括られます。 省略符号 .Pf ( Sq ... ) はさらに 0 個以上の引数があることを表しています。 パラメータの代替値は .Ql | で区切って示します。 必須パラメータに代替値がある場合は、 ( .Ql | と一緒に) 中括弧 ({}) を用い、値の組を括ります。 メタ変数は山括弧 (<>) の中で指定されます。 .Pp 例: . .Bl -tag -width 6n -offset indent .It Li .Xx Xo .Aq foo .Brq bar1 | bar2 .Op \-test1 Op \-test2 | \-test3 .No ... .Xc .El . .Pp とくに明示しない限り、すべてのマクロは 構文解析され、呼び出し可能なものです。 .Pp 大部分のマクロはデフォルトの幅の値を持っており、これを .Ql .Bl および .Ql .Bd マクロ用にラベル width .Pf ( Fl width ) あるいは offset .Pf ( Fl offset ) を指定するのに使用することができます。 .Nm \-mdoc パッケージのローカルな変更に依存することのないように、 このとても曖昧な機能は使わないことを推奨します。 . . .Sh "タイトルマクロ" . タイトルマクロはページ構造領域の一部ですが、 マニュアルページを昨日書き始めようと思ったという人のために、 最初に、他のとは別に記述されています。 3 つのヘッダマクロでドキュメントまたはマニュアルページのタイトル、 オペレーティングシステム、および原著の日付を指定します。 これらのマクロはドキュメントの最初で一度だけ呼び出されるもので、 ヘッダとフッタを構成するためだけに使用されます。 . .Bl -tag -width 6n .It Li .Dt Xo .Op Aq ドキュメントタイトル .Op Aq セクション番号 .Op Aq ボリューム .Xc ドキュメントタイトルはマニュアルページの主題であり、 troff の制限により .Tn 大文字 でなければいけません。 省略された場合、 .Sq Tn UNTITLED が使われます。 セクション番号は .No 1,\~ Ns ... Ns ,\~9 の範囲の番号もしくは .Ql unass , .Ql draft , .Ql paper のいずれかを取ることができます。 セクション番号が指定されており、ボリューム名が与えられていない 場合には、デフォルトのボリューム名が使用されます。 . .Pp .Tn \*[operating-system] では、次のセクションが定義されています: .Pp .Bl -column LOCAL -offset indent -compact -.It Li 1 Ta "\*[volume-ds-1]" -.It Li 2 Ta "\*[volume-ds-2]" -.It Li 3 Ta "\*[volume-ds-3]" -.It Li 4 Ta "\*[volume-ds-4]" -.It Li 5 Ta "\*[volume-ds-5]" -.It Li 6 Ta "\*[volume-ds-6]" -.It Li 7 Ta "\*[volume-ds-7]" -.It Li 8 Ta "\*[volume-ds-8]" -.It Li 9 Ta "\*[volume-ds-9]" +.It Li 1 Ta "\*[volume-operating-system] \*[volume-ds-1]" +.It Li 2 Ta "\*[volume-operating-system] \*[volume-ds-2]" +.It Li 3 Ta "\*[volume-operating-system] \*[volume-ds-3]" +.It Li 4 Ta "\*[volume-operating-system] \*[volume-ds-4]" +.It Li 5 Ta "\*[volume-operating-system] \*[volume-ds-5]" +.It Li 6 Ta "\*[volume-operating-system] \*[volume-ds-6]" +.It Li 7 Ta "\*[volume-operating-system] \*[volume-ds-7]" +.It Li 8 Ta "\*[volume-operating-system] \*[volume-ds-8]" +.It Li 9 Ta "\*[volume-operating-system] \*[volume-ds-9]" .El .Pp . ボリューム名は任意であるか、もしくは次のものを 取ることができます: . .Pp .Bl -column LOCAL -offset indent -compact .It Li USD Ta "\*[volume-ds-USD]" .It Li PS1 Ta "\*[volume-ds-PS1]" .It Li AMD Ta "\*[volume-ds-AMD]" .It Li SMM Ta "\*[volume-ds-SMM]" .It Li URM Ta "\*[volume-ds-URM]" .It Li PRM Ta "\*[volume-ds-PRM]" .It Li KM Ta "\*[volume-ds-KM]" .It Li IND Ta "\*[volume-ds-IND]" .It Li LOCAL Ta "\*[volume-ds-LOCAL]" .It Li CON Ta "\*[volume-ds-CON]" .El .Pp . 互換性を保つため、 .Ql IND の代わりに .Ql MMI を使用することができ、 .Ql LOCAL の代わりに .Ql LOC を使用できます。 先の表の値は、新しいボリューム名を指定します。 第 3 パラメータがコンピュータアーキテクチャを表すキーワードで -ある場合、その値は第 2 パラメータで指定したようにボリューム名に -追加されます。デフォルトでは次のアーキテクチャに関するキーワードが -定義されています: +ある場合、その値は第 2 パラメータで指定したボリューム名の +前に追加されます。 +デフォルトでは次のアーキテクチャに関するキーワードが定義されています: . \# we use `No' to avoid hyphenation .Bd -ragged -offset indent .No alpha , amiga , arc , arm26 , arm32 , atari , bebox , cobalt , evbsh3 , .No hp300 , hpcmips , i386 , luna68k , m68k , mac68k , macppc , mips , .No mmeye , mvme68k , news68k , newsmips , next68k , ofppc , pc532 , pmax , .No powerpc , prep , sgimips , sh3 , sparc , sparc64 , sun3 , tahoe , vax , .No x68k .Ed .Pp . 次の例では、マニュアルページのヘッダの左側 (これは右側と同じものです) と 中央に書かれる文字列を示しています。 . .Bd -ragged -.Bl -tag -width ".Li .Dt\ FOO\ 2\ mac68k" -compact -offset indent +.Bl -tag -width ".Li .Dt\ FOO\ 2\ i386" -compact -offset indent .It Li ".Dt FOO 7" .Ql FOO(7) -.Ql System Reference Manual -.It Li ".Dt FOO 2 mac68k" +.Ql \*[volume-operating-system] \*[volume-ds-7] +.It Li ".Dt FOO 2 i386" .Ql FOO(2) -.Ql System Programmer's Manual (mac68k Architecture) +.Ql \*[volume-operating-system]/\*[volume-as-i386] \*[volume-ds-2] .It Li ".Dt FOO \*[q]\*[q] bar" .Ql FOO .Ql bar .El .Ed .Pp . ローカルな追加項目や OS に特化した追加項目が、ファイル .Pa mdoc.local にあるかもしれません。このファイル中で .Ql volume-ds-XXX (前者のタイプについて) および .Ql volume-as-XXX (後者のタイプについて) という名前の文字列を検索してください。ここで .Ql XXX は .Ql .Dt マクロで使用されるキーワードを表しています。 .Pp このマクロは呼び出し不可能であり、構文解析もされません。 . .It Li .Os Xo .Op Aq オペレーティングシステム .Op Aq リリース番号 .Xc 第 1 パラメータが空の場合、 デフォルト値 .Sq Tn "\*[operating-system]" が使用されます。 これは、ローカルの設定ファイル .Pa mdoc.local で上書きできます。一般的には、 オペレーティングシステムの名称には一般的な頭字語 (略称) を 使わなければなりません。 例えば .Tn BSD や .Tn ATT といったものです。 リリース番号は、各システムでの標準のリリースの命名法を使用します。 次の表では、いくつか事前に定義されているオペレーティングシステムに 対して取り得る第 2 引数をリストしています。 .Ql .Dt と同じように、ローカルな追加項目が .Pa mdoc.local に定義されているかもしれません。このファイル中で .Ql operating-system-XXX-YYY という名前の文字列を検索してください。ここで .Ql XXX はオペレーティングシステムの頭字語 (略称) そして .Ql YYY がリリース ID です。 . .Bd -ragged -compact .Bl -tag -width ".No FreeBSD" -offset indent .It ATT 7th, 7, III, 3, V, V.2, V.3, V.4 .It BSD 3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4 .It NetBSD 0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a, 1.2b, 1.2c, 1.2d, 1.2e, -1.3, 1.3a, 1.4, 1.5 +1.3, 1.3a, 1.4, 1.5, 1.6 .It FreeBSD 1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5, 2.1.6, 2.1.7, 2.2, 2.2.1, 2.2.2, 2.2.5, 2.2.6, 2.2.7, 2.2.8, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 4.0, 4.1, -4.2, 5.0 +4.2, 4.3, 4.4, 4.5, 5.0 .El .Ed .Pp . .Tn ATT に関しては、判別できない第 2 パラメータがある時には それを文字列 .Tn UNIX に置き換えます。事前に定義されているその他の頭字語 (略称) に ついては、そのようなパラメータは無視され、警告メッセージが 出力されます。 認識できない引数は、ページフッタ中に記述された通りに 表示されます。例えば、典型的なフッタは次のようになるでしょう: .Pp .Dl .Os BSD 4.3 .Pp は .Ql 4.3\~Berkeley Distribution となります。また、ローカルで作られたセットの例では、 .Pp .Dl .Os CS Department .Pp は .Ql CS\~Department となります。 .Pp .Ql .Os マクロがない場合、ページの左下隅は見苦しくなってしまうでしょう。 .Pp このマクロは呼び出し不可能であり、構文解析もされません。 . .It Li .Dd Oo .Aq 月 .Aq 日 , .Aq 年 .Oc .Ql Dd に引数がない場合は、日付には .Ql "基準時点 (協定世界時 1970年1月1日 00:00:00)" が使用されます。 ちょうど 3 つ引数がある場合には、それらは連結され、 分割できない空白で分けられたものになります。 .Pp .Dl .Dd January 25, 2001 .Pp それ以外の場合は現在の日付が使用され、パラメータは無視されます。 .Pp このマクロは呼び出し不可能であり、構文解析もされません。 .El . . .Sh "マニュアル領域および一般テキスト領域の紹介" . .Ss "この名前には何が" Ns ... . マニュアル領域のマクロ名はコマンドやサブルーチン、それに関連ファイルを 説明するために使われている日常のインフォーマルな言葉から取られています。 この言葉と少し違うバリエーションのものがマニュアルページを書く上での 3 つの異なった側面を記述するのに使われます。 最初のものは、 .Nm \-mdoc マクロ使用方法の説明です。2 番目は .Nm \-mdoc マクロを .Em 用いた .Ux コマンドの記述です。 3 番目はコマンドを通常の言葉の感覚でユーザに示したものです。 これはすなわち、マニュアルページのテキスト中でのコマンドの 説明となります。 .Pp 最初のケースでは、 .Xr troff 1 マクロはそれ自身、一種のコマンドとなっています。 troff コマンドは一般的に以下のような形式をとります。 . .Bd -filled -offset indent .Li ".Xx argument1 argument2" ... .Ed .Pp . .Ql .Xx はマクロコマンドもしくは要求を示しており、それに続くものは すべて処理されるべき引数として処理されます。 2 番目のケースでは、コンテントマクロを使用する .Ux コマンドの記述がもう少し含まれます。 典型的な .Sx SYNOPSIS コマンド行はこのように表示されます。 . .Bd -filled -offset indent .Nm filter .Op Fl flag .Ao Ar infile Ac Ao Ar outfile Ac .Ed .Pp . ここで .Nm filter はコマンド名であり、角括弧で囲まれた文字列 .Fl flag は .Em フラグ 引数で、これは角括弧で囲むことによってオプションであることを 示しています。 .Nm \-mdoc の用語では、 .Ao Ar infile Ac および .Ao Ar outfile Ac は .Em メタ引数 と称されています。 この例では、ユーザは山括弧 (<>) の中で与えられたメタ引数を 実際のファイル名に置き換えなくてはなりません。 このドキュメントでは、メタ引数は .Nm \-mdoc コマンドを記述するのに使用していることに注意してください。 多くのマニュアルページでは、メタ変数はわざわざ山括弧を使って 書かれていません。 上の例を整形したマクロは以下のものです。 . .Bd -literal -offset indent \&.Nm filter \&.Op Fl flag \&.Ao Ar infile Ac Ao Ar outfile Ac .Ed .Pp . 3 番目のケースでは、コマンドの説明や構文に上記の例の両方が使われ、 さらに細かい記述が追加されるでしょう。 上の例での引数 .Ao Ar infile Ac および .Ao Ar outfile Ac は .Em オペランド もしくは .Em ファイル引数 として参照されます。 コマンド行の引数のリストはかなり長くなる場合もあります。 . .Bd -ragged .Bl -tag -width ".Nm make" -offset indent -compact .It Nm make .Op Fl eiknqrstv .Op Fl D Ar variable .Op Fl d Ar flags .Op Fl f Ar makefile .Op Fl I Ar directory .Op Fl j Ar max_jobs .Op Ar variable Ns = Ns Ar value .Bk .Op Ar target ... .Ek .El .Ed .Pp . ここではコマンド .Nm make について記述しており、 .Ar makefile をフラグ .Fl f の引数としています。 またオプションのファイルオペランドである .Ar target についても言及しています。 言葉での説明では、こういった詳細な記述が混乱を防いでくれますが、 .Nm \-mdoc パッケージにはフラグ .Em への 引数のためのマクロがありません。 その代わりに .Ar target のようなオペランドやファイル引数に使われる引数マクロ .Ql \&Ar が .Ar variable のようなフラグへの引数と同様に使われます。 この make コマンド行は次の指定により生成されています。 . .Bd -literal -offset indent \&.Nm make \&.Op Fl eiknqrstv \&.Op Fl D Ar variable \&.Op Fl d Ar flags \&.Op Fl f Ar makefile \&.Op Fl I Ar directory \&.Op Fl j Ar max_jobs \&.Op Ar variable Ns = Ns Ar value \&.Bk \&.Op Ar target ... \&.Ek .Ed .Pp . マクロ .Ql .Bk および .Ql .Ek は .Sx キープ セクションにおいて解説されています。 . .Ss "一般的な構文" . マニュアル領域のマクロと一般テキスト領域のマクロとはいくつか 小さな違いがあるものの、同様な構文を使用しています。とりわけ、 .Ql .Ar , .Ql .Fl , .Ql .Nm , および .Ql .Pa は引数なしで呼び出された時の違いしかありません。また、 .Ql .Fn および .Ql .Xr は引数のリストの順番が異なります。 すべてのコンテントマクロが句読点を認識し、それを正しく扱うには、 各々の句読点文字が先行する空白で分離されている必要があります。 次のように指定されている場合、 .Pp .Dl \&.Ar sptr, ptr), .Pp その結果は以下のようになります。 .Pp .Dl Ar sptr, ptr), .Pp ここでは句読点は認識されず、すべての出力は .Ql .Ar で使用されるフォントで行われています。 句読点が空白文字で区切られている場合、 .Pp .Dl \&.Ar "sptr , ptr ) ," .Pp 結果は以下のようになります。 .Pp .Dl Ar sptr , ptr ) , .Pp 今度は句読点が認識され、出力はデフォルトのフォントで行われ 引数文字列とは区別されています。 句読点文字の特別な意味を取り除くには、 .Ql \e& でエスケープしてください。 .Pp .Xr troff はマクロ言語としての限界から、以下のような、数学、論理学、引用符の 集合のメンバを含んだ文字列を表現するのは困難です。 . .Bd -literal -offset indent-two {+,\-,/,*,%,<,>,<=,>=,=,==,&,`,',"} .Ed .Pp . 問題なのは、文字によって示唆されている操作もしくは評価が、 実行されるべきであると .Xr troff が仮定する場合があることです。 これらの文字が予期しない形で評価されないようにするには、 .Ql \e& でこれらをエスケープしてください。 最初のコンテントマクロは、以下の .Ql .Ad において、その典型的な構文が示されています。 . . .Sh "マニュアル領域" . .Ss "アドレス" . アドレスマクロはアドレスの構成を識別します。 .Pp .Dl 使い方: .Ad Ao アドレス Ac ... .Pp .Bl -tag -width ".Li .Ad\ f1\ ,\ f2\ ,\ f3\ :" -compact -offset 15n .It Li ".Ad addr1" .Ad addr1 .It Li ".Ad addr1 ." .Ad addr1 . .It Li ".Ad addr1 , file2" .Ad addr1 , file2 .It Li ".Ad f1 , f2 , f3 :" .Ad f1 , f2 , f3 : .It Li ".Ad addr ) ) ," .Ad addr ) ) , .El .Pp . デフォルトの文字幅は 12n です。 . .Ss "作者名" . .Ql .An マクロは文書化されている項目の作者の名前、もしくは実際の マニュアルページの作者の名前を指定するために使われます。 .Pp .Dl 使い方: .An Ao 作者名 Ac ... .Pp .Bl -tag -width ".Li .An\ \*[q]Joe\ Author\*[q]\ )\ )\ ," -offset 15n .It Li ".An \*[q]Joe Author\*[q]" .An "Joe Author" .It Li ".An \*[q]Joe Author\*[q] ," .An "Joe Author" , .It Li ".An \*[q]Joe Author\*[q] Aq nobody@FreeBSD.org" .An "Joe Author" Aq nobody@FreeBSD.org .It Li ".An \*[q]Joe Author\*[q] ) ) ," .An "Joe Author" ) ) , .El .Pp . デフォルトの文字幅は 12n です。 .Pp .Sx AUTHORS セクションでは、 .Ql .An リクエストは改行を引き起こし、新しい名前がそれぞれの行に表示されます。 この動作が望ましくない場合、 . .Bd -literal -offset indent \&.An -nosplit .Ed .Pp . を呼び出すことで無効にできます。 それぞれの行に表示させる動作に戻したい場合は、 . .Bd -literal -offset indent \&.An -split .Ed .Pp . と記述します。 . .Ss "引数" . 引数マクロ .Li .Ar はコマンド行の引数を参照する際にはいつでも使用することができます。 引数なしで呼ばれた場合、 .Sq Ar が出力になります。 .Pp .Dl 使い方: .Ar Oo Ao 引数 Ac Oc ... .Pp .Bl -tag -width ".Li .Ar\ file1\ file2" -compact -offset 15n .It Li .Ar .Ar .It Li ".Ar file1" .Ar file1 .It Li ".Ar file1 ." .Ar file1 . .It Li ".Ar file1 file2" .Ar file1 file2 .It Li ".Ar f1 f2 f3 :" .Ar f1 f2 f3 : .It Li ".Ar file ) ) ," .Ar file ) ) , .El .Pp . デフォルト幅は 12n です。 . .Ss "コンフィギュレーション宣言 (セクション 4 のみ)" . .Ql .Cd マクロはセクション 4 のマニュアルにおいて、デバイスインタフェースの .Xr config 8 による宣言の説明に使われます。 .Pp .Dl 使い方: .Cd Ao 引数 Ac ... .Pp .Bl -tag -width ".Li .Cd\ Xdevice\ le0\ at\ scode?X" -offset 15n .It Li ".Cd \*[q]device le0 at scode?\*[q]" .Cd "device le0 at scode?" .El .Pp .Sx SYNOPSIS セクションでは .Ql .Cd リクエストはその引数が表示される前後で改行を入れます。 .Pp . デフォルト幅は 12n です。 . .Ss "コマンド修飾子" . コマンド修飾子は .Ql .Cm マクロがすべての引数の前にダッシュ文字を付けないことを除いて、 .Ql .Fl (フラグ) コマンドと同じです。 伝統的にフラグはダッシュ文字に引き続いて指定されますが、 この方法を使わないコマンドやコマンドのサブセットもあります。 コマンド修飾子はエディタコマンドのような対話的なコマンドでも 指定されることがあります。 .Sx フラグ セクションを参照してください。 .Pp デフォルト幅は 10n です。 . .Ss "定義済みの変数" . インクルードファイルにおいて定義されている変数 (もしくは定数) は マクロ .Ql .Dv によって指定します。 .Pp .Dl 使い方: .Dv Ao 定義済みの変数 Ac ... .Pp .Bl -tag -width ".Li .Dv\ MAXHOSTNAMELEN" -compact -offset 15n .It Li ".Dv MAXHOSTNAMELEN" .Dv MAXHOSTNAMELEN .It Li ".Dv TIOCGPGRP )" .Dv TIOCGPGRP ) .El .Pp . デフォルト幅は 12n です。 . .Ss errno . .Ql .Er errno マクロは、セクション 2, 3, 9 のライブラリルーチンにおける エラーの戻り値を指定します。 下記の 2 番目の例では .Ql .Er は一般テキスト領域マクロである .Ql .Bq (これはセクション 2 のマニュアルページで使われています) と共に 使われています。 .Pp .Dl 使い方: .Er Ao errno のタイプ Ac ... .Pp .Bl -tag -width ".Li .Bq\ Er\ ENOTDIR" -compact -offset 15n .It Li ".Er ENOENT" .Er ENOENT .It Li ".Er ENOENT ) ;" .Er ENOENT ) ; .It Li ".Bq Er ENOTDIR" .Bq Er ENOTDIR .El .Pp . デフォルト幅は 17n です。 . .Ss "環境変数" . .Ql .Ev マクロは環境変数を指定します。 .Pp .Dl 使い方: .Ev Ao 引数 Ac ... .Pp .Bl -tag -width ".Li .Ev\ PRINTER\ )\ )\ ," -compact -offset 15n .It Li ".Ev DISPLAY" .Ev DISPLAY .It Li ".Ev PATH ." .Ev PATH . .It Li ".Ev PRINTER ) ) ," .Ev PRINTER ) ) , .El .Pp . デフォルト幅は 15n です。 . .Ss "フラグ" . .Ql .Fl マクロはコマンド行のフラグを扱います。 フラグの前にはダッシュ .Ql \- が挿入されます。 ダッシュがつかない対話的なコマンドのために .Ql .Cm (コマンド修飾子) マクロが用意されています。 これはダッシュを付けないことを除いて同じ働きをします。 .Pp .Dl 使い方: .Fl Ao 引数 Ac ... .Pp .Bl -tag -width ".Li .Fl\ xyz\ )\ ," -compact -offset 15n .It Li .Fl .Fl .It Li ".Fl cfv" .Fl cfv .It Li ".Fl cfv ." .Fl cfv . .It Li ".Cm cfv ." .Cm cfv . .It Li ".Fl s v t" .Fl s v t .It Li ".Fl \- ," .Fl \- , .It Li ".Fl xyz ) ," .Fl xyz ) , .It Li ".Fl |" .Fl | .El .Pp 引数なしで .Ql .Fl マクロを指定すると、標準入力/標準出力を意味するダッシュとなります。 .Ql .Fl マクロにダッシュを 1 つ与えると、2 つのダッシュとなることに 注意して下さい。 .Pp デフォルト幅は 12n です。 . .Ss "関数の宣言" . .Ql .Fd マクロは .Sx SYNOPSIS セクションにおいて、セクション 2 または 3 の関数の説明で使われます。 このマクロは呼び出し不可能であり、構文解析もされせん。 .Pp .Dl 使い方: .Fd Ao 引数 Ac ... .Pp .Bl -tag -width ".Li .Fd\ X#include\ X" -compact -offset 15n .It Li ".Fd \*[q]#include \*[q]" .Fd "#include " .El .Pp .Sx SYNOPSIS セクションでは、 関数がすでに示されており、改行がまだされていない場合には .Ql .Fd リクエストは改行を入れます。 これによって前の関数呼び出しと次の関数の宣言の間に 最適な行間が設定されます。 . .Pp .Ql .In .Li ( #include 文) マクロは、以上の例を短く記述したものです。 このマクロは C プログラム中でインクルードされる C ヘッダファイルを指定します。 このマクロも改行を挿入し、 呼び出し不可能であり、構文解析されることもありません。 .Pp .Dl 使い方: .In Ao ヘッダファイル Ac .Pp .Bl -tag -width ".Li .In\ stdio.h" -compact -offset 15n .It Li ".In stdio.h" .In stdio.h .El . .Ss "関数の型" . このマクロは .Sx SYNOPSIS セクションで使うものです。 マニュアルページ中の他の場所でも問題なく使うことができますが、 セクション 2 と 3 の .Sx SYNOPSIS セクションにおいてカーネルの通常の形式で関数の型を示すことが このマクロの目的です (このマクロは関数名が次の行に置かれるように改行を挿入します)。 .Pp .Dl 使い方: .Ft Ao 型 Ac ... .Pp .Bl -tag -width ".Li .Ft\ struct\ stat" -compact -offset 15n .It Li ".Ft struct stat" .Ft struct stat .El . .Ss "関数 (ライブラリルーチン)" . .Ql .Fn マクロは .Tn ANSI\~C の記法を規範としています。 .Pp .Dl 使い方: .Fn Ao 関数 Ac Oo Ao パラメータ Ac Oc ... .Pp .Bl -tag -width ".Li .Fn\ align\ Xchar\ *ptrX\ ," -compact -offset 15n .It Li ".Fn getchar" .Fn getchar .It Li ".Fn strlen ) ," .Fn strlen ) , .It Li ".Fn align \*[q]char *ptr\*[q] ," .Fn align "char *ptr" , .El .Pp 他のマクロを呼び出すと .Ql .Fn 呼び出しの終了を意味することに注意してください (閉じ括弧がその箇所に挿入されます)。 .Pp 多くのパラメータをとる関数 (これは滅多にないことですが) では、 .Ql .Fo マクロ (関数マクロの開始) と .Ql .Fc マクロ (関数マクロの終了) を .Ql .Fa (関数の引数) と共に使って、この制限を回避することができます。 .Pp 使用例: . .Bd -literal -offset indent \&.Ft int \&.Fo res_mkquery \&.Fa "int op" \&.Fa "char *dname" \&.Fa "int class" \&.Fa "int type" \&.Fa "char *data" \&.Fa "int datalen" \&.Fa "struct rrec *newrr" \&.Fa "char *buf" \&.Fa "int buflen" \&.Fc .Ed .Pp . 生成結果: . .Bd -ragged -offset indent .Ft int .Fo res_mkquery .Fa "int op" .Fa "char *dname" .Fa "int class" .Fa "int type" .Fa "char *data" .Fa "int datalen" .Fa "struct rrec *newrr" .Fa "char *buf" .Fa "int buflen" .Fc .Ed .Pp . .Sx SYNOPSIS セクションでは、関数は常に行の先頭から開始されます。 .Sx SYNOPSIS セクションにおいて複数の関数が示されており、関数の型が 示されない場合、改行が挿入され、現在の関数名とその前の 関数名の間に最適な改行量が設定されます。 .Pp .Ql .Fn および .Ql .Fo のデフォルト幅の値はそれぞれ 12n と 16n です。 . .Ss "関数の引数" . .Ql .Fa マクロは関数の引数 (パラメータ) を マニュアルの .Sx SYNOPSIS のセクション外で参照する場合、あるいは .Ql .Fn の代わりに .Ql .Fo および .Ql .Fc 囲いマクロを使用した場合には .Sx SYNOPSIS のセクション内で参照する場合にも使われます。 .Ql .Fa は構造体のメンバを参照する場合にも使われます。 .Pp .Dl 使い方: .Fa Ao 関数の引数 Ac ... .Pp .Bl -tag -width ".Li .Fa\ d_namlen\ )\ )\ ," -compact -offset 15n .It Li ".Fa d_namlen ) ) ," .Fa d_namlen ) ) , .It Li ".Fa iov_len" .Fa iov_len .El .Pp . デフォルト幅は 12n です。 . .Ss "戻り値" . .Ql .Rv マクロは .Sx RETURN VALUES のセクションで使うテキストを生成します。 .Pp .Dl 使い方: .Rv Oo -std Oc Op Ao 関数 Ac ... .Pp 例えば、 .Ql ".Rv -std atexit" は次のテキストを生成します。 . .Bd -ragged -offset -indent \# a small hack to suppress a warning message .ds section-old "\*[section] .ds section 3 .\" following part came from doc.tmac workaround the effect of .\" -dlang=ja_JP.eucJP .ds str-Rv-std-prefix "The .ds str-Rv-std-suffix "function returns the value\~0 if successful; .as str-Rv-std-suffix " otherwise the value\~-1 is returned and .as str-Rv-std-suffix " the global variable \*[Va-font]errno\f[P] .as str-Rv-std-suffix " is set to indicate the error. .ds str-Rv-stds-prefix "The .ds str-Rv-stds-and "and .ds str-Rv-stds-suffix "functions return the value\~0 if successful; .as str-Rv-stds-suffix " otherwise the value\~-1 is returned and .as str-Rv-stds-suffix " the global variable \*[Va-font]errno\f[P] .as str-Rv-stds-suffix " is set to indicate the error. .ds str-Rv-std0 "Upon successful completion, the value\~0 is returned; .as str-Rv-std0 " otherwise the value\~-1 is returned and .as str-Rv-std0 " the global variable \*[Va-font]errno\f[P] .as str-Rv-std0 " is set to indicate the error. .Rv -std atexit .ds section "\*[section-old] .Ed .Pp . .Fl std オプションはセクション 2 と 3 のマニュアルページでのみ有効です。 現在のところ、このマクロは .Fl std フラグなしで使用しても何も起こりません。 . .Ss "終了ステータス" . .Ql .Ex マクロは .Sx DIAGNOSTICS のセクションで使うテキストを生成します。 .Pp .Dl 使い方: .Ex Oo -std Oc Op Ao ユーティリティ Ac ... .Pp 例えば .Ql ".Ex -std cat" は次のテキストを生成します。 . .Bd -ragged -offset -indent \# a small hack to suppress a warning message .ds section-old "\*[section] .ds section 1 .\" following part came from doc.tmac workaround the effect of .\" -dlang=ja_JP.eucJP .ds str-Ex-std-prefix "The .ds str-Ex-std-suffix "utility exits\~0 on success, .as str-Ex-std-suffix " and\~>0 if an error occurs. .ds str-Ex-stds-prefix "The .als str-Ex-stds-and str-Rv-stds-and .ds str-Ex-stds-suffix "utilities exit\~0 on success, .as str-Ex-stds-suffix " and\~>0 if an error occurs. .Ex -std cat .ds section "\*[section-old] .Ed .Pp . .Fl std オプションはセクション 1 と 6 と 8 のマニュアルページでのみ有効です。 現在のところ、このマクロは .Fl std フラグなしで使用しても何も起こりません。 . .Ss "対話的なコマンド" . .Ql .Ic マクロは対話的なコマンド、もしくは内部コマンドを指定します。 .Pp .Dl 使い方: .Ic Ao 引数 Ac ... .Pp .Bl -tag -width ".Li .Ic\ setenv\ ,\ unsetenv" -compact -offset 15n .It Li ".Ic :wq" .Ic :wq .It Li ".Ic \*[q]do while {...}\*[q]" .Ic "do while {...}" .It Li ".Ic setenv , unsetenv" .Ic setenv , unsetenv .El .Pp . デフォルト幅は 12n です。 . .Ss "ライブラリ名" . .Ql .Lb マクロは、関数がどのライブラリに組み込まれるかを指定します。 .Pp .Dl 使い方: .Lb Ao 引数 Ac ... .Pp .Ql .Lb マクロに対して使用可能な引数と結果は次の通りです: . .Pp .Bl -tag -width ".Li libossaudio" -compact -offset indent .It Li libarm32 .Lb libarm32 .It Li libc .Lb libc .It Li libcompat .Lb libcompat .It Li libcrypt .Lb libcrypt .It Li libcurses .Lb libcurses .It Li libedit .Lb libedit .It Li libi386 .Lb libi386 .It Li libipsec .Lb libipsec .It Li libkvm .Lb libkvm .It Li libm .Lb libm .It Li libmenu .Lb libmenu .It Li libossaudio .Lb libossaudio .It Li libposix .Lb libposix .It Li libresolv .Lb libresolv .It Li libtermcap .Lb libtermcap .It Li libutil .Lb libutil .It Li libz .Lb libz .El .Pp . ローカルな追加項目や OS 特有の追加項目が、ファイル .Pa mdoc.local にあるかもしれません。 .Ql str-Lb-XXX という名前の文字列を検索してください。ここで .Ql XXX は .Ql .Lb マクロとともに使用されるキーワードを示しています。 . .Ss リテラル . リテラルマクロ .Ql .Li は特殊文字や変数定数、その他タイプされた通りに表示する必要があるものに 使用することができます。 .Pp .Dl 使い方: .Li Ao 引数 Ac ... .Pp .Bl -tag -width ".Li .Li\ cntrl-D\ )\ ," -compact -offset 15n .It Li ".Li \een" .Li \en .It Li ".Li M1 M2 M3 ;" .Li M1 M2 M3 ; .It Li ".Li cntrl-D ) ," .Li cntrl-D ) , .It Li ".Li 1024 ..." .Li 1024 ... .El .Pp . デフォルト幅は 16n です。 . .Ss 名称 . .Ql .Nm マクロは文書のタイトルやサブジェクト名を指定するために使われます。 このマクロは呼び出された時の第 1 引数を覚えておくという 変わった特性を持っており、 それは常にそのページのサブジェクト名であるべきです。 引数なしで呼び出されると .Ql .Nm は作者のために最低限の仕事をするという意味で、 この初期化された名称を出力します。 注: セクション 2 または 3 のドキュメントの関数名は .Sx NAME セクションにおいて .Ql .Nm で指定され、 .Sx SYNOPSIS セクションや残りのセクションでは .Ql .Fn で指定されます。 .Xr csh 1 での .Ql while コマンドのキーワードのような対話的なコマンドでは .Ql .Ic マクロを使う必要があります。 .Ql .Ic はほとんど .Ql .Nm と同一ですが、 それが使われたときの第 1 引数を記憶することはできません。 .Pp .Dl 使い方: .Nm Oo Ao 引数 Ac Oc ... .Pp .Bl -tag -width ".Li .Nm\ groff_mdoc" -compact -offset 15n .It Li ".Nm groff_mdoc" .Nm groff_mdoc .It Li ".Nm \e-mdoc" .Nm \-mdoc .It Li ".Nm foo ) ) ," .Nm foo ) ) , .It Li ".Nm :" .Nm : .El .Pp . デフォルト幅は 10n です。 . .Ss オプション . .Ql .Op マクロはコマンド行の残りのすべての引数を オプションであることを示す角括弧で囲み、 末尾の句読点は角括弧の外に置きます。 .Ql .Oo マクロと .Ql .Oc マクロ (それぞれ開き角括弧と閉じ角括弧を生成します) は 複数行に渡って使うことができ、また閉じ括弧の正確な位置を 指定するのに使うことができます。 .Pp .Dl 使い方: .Op Oo Ao オプション Ac Oc ... .Pp .Bl -tag -width ".Li .Op\ Fl\ c\ Ar\ objfil\ Op\ Ar\ corfil\ ," -compact -offset 15n .It Li .Op .Op .It Li ".Op Fl k" .Op Fl k .It Li ".Op Fl k ) ." .Op Fl k ) . .It Li ".Op Fl k Ar kookfile" .Op Fl k Ar kookfile .It Li ".Op Fl k Ar kookfile ," .Op Fl k Ar kookfile , .It Li ".Op Ar objfil Op Ar corfil" .Op Ar objfil Op Ar corfil .It Li ".Op Fl c Ar objfil Op Ar corfil ," .Op Fl c Ar objfil Op Ar corfil , .It Li ".Op word1 word2" .Op word1 word2 .It Li ".Li .Op Oo Ao option Ac Oc ..." .Li .Op Oo Ao options Ac Oc ... .El .Pp これは、 .Ql .Oo マクロと .Ql .Oc マクロを使った典型的な例です: . .Bd -literal -offset indent \&.Oo \&.Op Fl k Ar kilobytes \&.Op Fl i Ar interval \&.Op Fl c Ar count \&.Oc .Ed .Pp . 出力結果: . .Bd -filled -offset indent .Oo .Op Fl k Ar kilobytes .Op Fl i Ar interval .Op Fl c Ar count .Oc .Ed .Pp . .Ql .Op マクロおよび .Ql .Oo マクロのデフォルト幅はそれぞれ 14n と 10n です。 . .Ss パス名 . .Ql .Pa マクロはパス名もしくはファイル名を整形します。 引数なしで呼ばれた場合、 .Sq Pa 文字列が出力となり、これは現在のユーザのホームディレクトリを 表しています。 .Pp .Dl 使い方: .Pa Oo Ao パス名 Ac Oc ... .Pp .Bl -tag -width ".Li .Pa\ /tmp/fooXXXXX\ )\ ." -compact -offset 15n .It Li .Pa .Pa .It Li ".Pa /usr/share" .Pa /usr/share .It Li ".Pa /tmp/fooXXXXX ) ." .Pa /tmp/fooXXXXX ) . .El .Pp . デフォルト幅は 32n です。 . .Ss 規格 . .Ql .St マクロは、規格の短縮名称を正式名称に置換します。 .Pp .Dl 使い方: .St Ao 短縮名称 Ac ... .Pp 使用可能な .Dq 短縮名称/正式名称 の組は次の通りです: . .Pp .Tn ANSI/ISO C .Pp .Bl -tag -width ".Li -iso9945-1-90" -compact -offset indent .It Li -ansiC .St -ansiC .It Li -ansiC-89 .St -ansiC-89 .It Li -isoC .St -isoC .It Li -isoC-99 .St -isoC-99 .El .Pp . .Tn POSIX パート 1: System API .Pp .Bl -tag -width ".Li -p1003.1g-2000" -compact -offset indent .It Li -iso9945-1-90 .St -iso9945-1-90 .It Li -iso9945-1-96 .St -iso9945-1-96 .It Li -p1003.1 .St -p1003.1 .It Li -p1003.1-88 .St -p1003.1-88 .It Li -p1003.1-90 .St -p1003.1-90 .It Li -p1003.1-96 .St -p1003.1-96 .It Li -p1003.1b-93 .St -p1003.1b-93 .It Li -p1003.1c-95 .St -p1003.1c-95 .It Li -p1003.1g-2000 .St -p1003.1g-2000 .It Li -p1003.1i-95 .St -p1003.1i-95 .El .Pp . .Tn POSIX パート 2: シェルとユーティリティ .Pp .Bl -tag -width ".Li -p1003.1g-2000" -compact -offset indent .It Li -iso9945-2-93 .St -iso9945-2-93 .It Li -p1003.2 .St -p1003.2 .It Li -p1003.2-92 .St -p1003.2-92 .It Li -p1003.2a-92 .St -p1003.2a-92 .El .Pp . X/Open .Bl -tag -width ".Li -p1003.1g-2000" -compact -offset indent .Pp .It Li -susv2 .St -susv2 .It Li -svid4 .St -svid4 .It Li -xbd5 .St -xbd5 .It Li -xcu5 .St -xcu5 .It Li -xcurses4.2 .St -xcurses4.2 .It Li -xns5 .St -xns5 .It Li -xns5.2 .St -xns5.2 .It Li -xpg3 .St -xpg3 .It Li -xpg4 .St -xpg4 .It Li -xpg4.2 .St -xpg4.2 .It Li -xsh5 .St -xsh5 .El .Pp . その他 .Pp .Bl -tag -width ".Li -p1003.1g-2000" -compact -offset indent .It Li -ieee754 .St -ieee754 .It Li -iso8802-3 .St -iso8802-3 .El . .Ss "変数の型" . .Ql .Vt マクロは型を参照するときにはいつでも使用することができます。 .Sx SYNOPSIS セクションでは改行が挿入されます (古いスタイルの変数宣言では便利です)。 .Pp .Dl 使い方: .Vt Ao 型 Ac ... .Pp .Bl -tag -width ".Li .Vt\ extern\ char\ *optarg\ ;" -compact -offset 15n .It Li ".Vt extern char *optarg ;" .Vt extern char *optarg ; .It Li ".Vt FILE *" .Vt FILE * .El . .Ss 変数 . 一般的な変数への参照です。 .Pp .Dl 使い方: .Va Ao 変数 Ac ... .Pp .Bl -tag -width ".Li .Va\ Xchar\ sX\ ]\ )\ )\ ," -compact -offset 15n .It Li ".Va count" .Va count .It Li ".Va settimer ," .Va settimer , .It Li ".Va \*[q]int *prt\*[q] ) :" .Va "int *prt" ) : .It Li ".Va \*[q]char s\*[q] ] ) ) ," .Va "char s" ] ) ) , .El .Pp . デフォルト幅は 12n です。 . .Ss "マニュアルページのクロスリファレンス" . .Ql .Xr マクロは最初の引数にマニュアルページの名称をとります。 オプションである第 2 引数は、文字列 (マニュアルセクションを定義します) であれば 括弧で囲われます。 .Pp .Dl 使い方: .Xr Ao マニュアルページの名称 Ac Oo Ao セクション Ac Oc ... .Pp .Bl -tag -width ".Li .Xr\ xinit\ 1x\ ;" -compact -offset 15n .It Li ".Xr mdoc" .Xr mdoc .It Li ".Xr mdoc ," .Xr mdoc , .It Li ".Xr mdoc 7" .Xr mdoc 7 .It Li ".Xr xinit 1x ;" .Xr xinit 1x ; .El .Pp . デフォルト幅は 10n です。 . . .Sh "一般テキスト領域" . .Ss "AT&T マクロ" . .Pp .Dl 使い方: .At Oo Ao バージョン Ac Oc ... .Pp .Bl -tag -width ".Li .At\ v6\ ." -compact -offset 15n .It Li .At .At .It Li ".At v6 ." .At v6 . .El .Pp .Ao バージョン Ac には次の値をとることができます: .Pp .Dl 32v, v1, v2, v3, v4, v5, v6, v7, V, V.1, V.2, V.3, V.4 . .Ss "BSD マクロ" . .Pp .Dl "使い方: .Bx" Bro -alpha | -beta | -devel Brc ... .Dl " .Bx" Oo Ao バージョン Ac Oo Ao リリース Ac Oc Oc ... .Pp .Bl -tag -width ".Li .Bx\ -devel" -compact -offset 15n .It Li .Bx .Bx .It Li ".Bx 4.3 ." .Bx 4.3 . .It Li ".Bx \-devel" .Bx -devel .El .Pp .Ao バージョン Ac が文字列 .Sq Bx の前につきます。 .Ao リリース Ac には次の値をとることができます: .Pp .Dl Reno, reno, Tahoe, tahoe, Lite, lite, Lite2, lite2 . .Ss "NetBSD マクロ" . .Pp .Dl 使い方: .Nx Oo Ao バージョン Ac Oc ... .Pp .Bl -tag -width ".Li .Nx\ 1.4\ ." -compact -offset 15n .It Li .Nx .Nx .It Li ".Nx 1.4 ." .Nx 1.4 . .El .Pp .Ao バージョン Ac にとり得る値については前述の .Sx "タイトルマクロ" セクションの .Ql .Os リクエストの説明を参照してください。 . .Ss "FreeBSD マクロ" . .Pp .Dl 使い方: .Fx Oo Ao バージョン Ac Oc ... .Pp .Bl -tag -width ".Li .Fx\ 2.2\ ." -compact -offset 15n .It Li .Fx .Fx .It Li ".Fx 2.2 ." .Fx 2.2 . .El .Pp .Ao バージョン Ac にとり得る値については前述の .Sx "タイトルマクロ" セクションの .Ql .Os リクエストの説明を参照してください。 . .Ss "OpenBSD マクロ" . .Pp .Dl 使い方: .Ox Oo Ao バージョン Ac Oc ... .Pp .Bl -tag -width ".Li .Ox\ 1.0" -compact -offset 15n .It Li ".Ox 1.0" .Ox 1.0 .El . .Ss "BSD/OS マクロ" . .Pp .Dl 使い方: .Bsx Oo Ao バージョン Ac Oc ... .Pp .Bl -tag -width ".Li .Bsx\ 1.0" -compact -offset 15n .It Li ".Bsx 1.0" .Bsx 1.0 .El . .Ss "UNIX マクロ" . .Pp .Dl 使い方: .Ux ... .Pp .Bl -tag -width ".Li .Ux" -compact -offset 15n .It Li .Ux .Ux .El . .Ss "強調マクロ" . テキストは .Ql .Em マクロを用いて強調することができます。 通常強調に用いられるフォントはイタリック体です。 .Pp .Dl 使い方: .Em Ao 引数 Ac ... .Pp .Bl -tag -width ".Li .Em\ vide\ infra\ )\ )\ ," -compact -offset 15n .It Li ".Em does not" .Em does not .It Li ".Em exceed 1024 ." .Em exceed 1024 . .It Li ".Em vide infra ) ) ," .Em vide infra ) ) , .El .Pp . デフォルト幅は 10n です。 . .Ss "フォントモード" . .Ql .Bf フォントモードは .Ql .Ef マクロで終了しなくてはなりません (後者のマクロは引数をとりません)。 フォントモードは別のフォントモード内に入れ子にできます。 .Pp .Ql .Bf は次の文法をもっています: .Pp .Dl .Bf Ao フォントモード Ac .Pp .Ao フォントモード Ac は次の 3 種類のうちのいずれかでなくてはなりません。 .Pp .Bl -tag -width ".Sy \&Sy | Fl symbolic" -compact -offset indent .It Sy \&Em | Fl emphasis .Ql .Em マクロがテキストのブロック全体に対して使用された場合と 同じになります。 .It Sy \&Li | Fl literal .Ql .Li マクロがテキストのブロック全体に対して使用された場合と 同じになります。 .It Sy \&Sy | Fl symbolic .Ql .Sy マクロがテキストのブロック全体に対して使用された場合と 同じになります。 .El .Pp いずれのマクロも呼び出し不可能であり、構文解析もされません。 . .Ss "囲い/クォートマクロ" . 囲いの概念はクォートと似たものです。 1 つ以上の文字列が引用符や括弧のような文字のペアで囲まれている オブジェクトを指します。 クォートと囲いという用語はこの文書を通して同じ意味で使われます。 ほとんどの 1 行の囲いマクロはクォートであることをほのめかすために、 小文字の .Ql q で終了しますが、例外もいくつかあります。 各々の囲いマクロに対し、開始マクロと終了マクロのペアもあり、 それぞれ小文字の .Ql o と .Ql c で終了します。 .Pp \# XXX .if t \ . ne 10 . .Bd -filled -offset 4n .Bl -column "クォート" "終了" "開始" "クォートされたリテラル" "`string' もしくは string" .Em クォート Ta Em 開始 Ta Em 終了 Ta Em 機能 Ta Em 結果 .No .Aq Ta .Ao Ta .Ac Ta "山括弧による囲い" Ta Ao string Ac .No .Bq Ta .Bo Ta .Bc Ta "角括弧による囲い" Ta Bo string Bc .No .Brq Ta .Bro Ta .Brc Ta "中括弧による囲い" Ta Bro string Brc .No .Dq Ta .Do Ta .Dc Ta "2 重引用符" Ta Do string Dc .No .Eq Ta .Eo Ta .Ec Ta "囲い文字列 (XX による)" Ta XXstringXX .No .Pq Ta .Po Ta .Pc Ta "括弧による囲い" Ta Po string Pc .No .Ql Ta Ta Ta "クォートされたリテラル" Ta So string Sc もしくは Li string .No .Qq Ta .Qo Ta .Qc Ta "まっすぐな 2 重引用符" Ta Qo string Qc .No .Sq Ta .So Ta .Sc Ta "1 重引用符" Ta So string Sc .El .Ed .Pp .Sq q および .Sq o で終わるマクロはすべてデフォルト幅が 12n です。 . .Bl -tag -width ".Li .Ec , .Eo" .It Li .Eo , .Ec これらのマクロはそれぞれ第 1 引数に囲い始めに使う文字列と 囲い終わりに使う文字列をとります。 .It Li .Es , .En オリジナルの troff プログラムでは、引数の数が 9 つまでという 制限がありましたので、(Eo, Ec とは) 別の 2 つのマクロが 実装されています。現在は非推奨になっています。 .Ql .Es は第 1 引数と第 2 引数に左囲い文字列および右囲い文字列を とります。この文字列は、 .Ql .En の引数を囲うのに使用されます。 デフォルト幅は、どちらのマクロも 12n です。 .It Li .Eq このマクロの第 1、第 2 引数はそれぞれ囲い始めに使う文字列と 囲い終わりに使う文字列であり、この文字列の後に 囲われる引数が続きます。 .It Li .Ql クォートされたリテラルマクロは troff モードと nroff モードで 違った挙動をします。 .Xr nroff で整形された場合、 クォートされたリテラルは常にクォートされます。 troff で整形された場合、その要素の幅が固定幅文字 3 文字分の幅よりも 小さいときのみクォートされます。 これにより、リテラル (固定幅) フォントへフォントを変更すると 目立たなくなってしまうような短い文字列がより見やすくなります。 .Pp デフォルト幅は 16n です。 .It Li .Pf プレフィックスマクロは第 1 引数と第 2 引数の間の ホワイトスペースをなくします: . .Bl -tag -width ".Li .Pf\ (\ Fa\ name2" -offset indent .It Li ".Pf ( Fa name2" .Pf ( Fa name2 .El .Pp . デフォルト幅は 12n です。 .Pp .Ql .Ns マクロ (後述参照) は同じようにサフィックスに働きます。 .It Li .Ap .Ql .Ap マクロはアポストロフィを追加し、特別なテキストモードから 抜けます。そして .Ql .No モードで続けます。 .El .Pp . クォートの例: . .Pp .Bl -tag -width ".Li .Bq\ Em\ Greek\ ,\ French\ ." -compact -offset indent .It Li .Aq .Aq .It Li ".Aq Pa ctype.h ) ," .Aq Pa ctype.h ) , .It Li .Bq .Bq .It Li ".Bq Em Greek , French ." .Bq Em Greek , French . .It Li .Dq .Dq .It Li ".Dq string abc ." .Dq string abc . .It Li ".Dq \'^[A-Z]\'" .Dq \'^[A-Z]\' .It Li ".Ql man mdoc" .Ql man mdoc .It Li .Qq .Qq .It Li ".Qq string ) ," .Qq string ) , .It Li ".Qq string Ns )," .Qq string Ns ), .It Li .Sq .Sq .It Li ".Sq string" .Sq string .It Li ".Em or Ap ing" .Em or Ap ing .El .Pp . 囲いマクロの入れ子についての良い例については、 オプションマクロ .Ql .Op を参照してください。 このマクロは上でリストされているような囲いマクロと同じベースの上に 作られています。 .Ql .Xo と .Ql .Xc 拡張引数リストマクロについては後で述べます。 . .Ss "無操作もしくは通常テキストマクロ" . .Ql .No マクロは、マクロコマンド行において整形されては .Em ならない パラメータ用に使用できます。 この英単語 (マクロでなく) をパラメータとして 本当に使いたい場合は、この単語 .Ql \&No に .Ql \e& を足すように注意してください。 .Pp .Dl 使い方: .No Ao 引数 Ac ... .Pp .Bl -tag -width ".Li .No\ test\ Ta\ with\ Ta\ tabs" -compact -offset 15n .It Li ".No test Ta with Ta tabs" .No test Ta with Ta tabs .El .Pp . デフォルト幅は 12n です。 . .Ss "空白なしマクロ" . .Ql .Ns マクロは、現在の位置とマクロの第 1 パラメータとの間に 空白を挿入するのを抑止します。 例えば、フラグと引数の間に空白を含まない古いスタイルの 引数リストを使う場合に便利です: .Pp .Dl "使い方:" ... Ao 引数 Ac \&Ns Oo Ao 引数 Ac Oc ... .Dl " " .Ns Ao 引数 Ac ... .\" 訳注: 2 行目 Dl マクロの第 1 引数の空白の数は 1 行目と一致させる .Pp .Bl -tag -width ".Li .Op\ Fl\ I\ Ns\ Ar\ directory" -compact -offset 15n .It Li ".Op Fl I Ns Ar directory" .Op Fl I Ns Ar directory .El .Pp 注: .Ql .Ns マクロは他のマクロ名が続かなければ、スペースを除去したあとに .Ql .No マクロを常に起動します。 リクエストとして使用される場合 (つまり、 .Sq 使い方 の行での 2 番目の形式です)、 .Ql .Ns マクロは .Ql .No と同一です。 . .Ss "セクションのクロスリファレンス" . .Ql .Sx マクロは同一文書内でのセクションのヘッダへの参照を指定します。 .Pp .Dl 使い方: .Sx Ao セクションの参照 Ac ... .Pp .Bl -tag -width ".Li .Sx\ FILES" -offset 15n .It Li ".Sx FILES" .Sx FILES .El .Pp . デフォルト幅は 16n です。 . .Ss 記号 . 記号体強調マクロは、記号の意味でも伝統的な英語の 使い方においても通常はボールド体マクロとなっています。 .Pp .Dl 使い方: .Sy Ao 記号 Ac ... .Pp .Bl -tag -width ".Li .Sy\ Important\ Notice" -compact -offset 15n .It Li ".Sy Important Notice" .Sy Important Notice .El .Pp . デフォルト幅は 6n です。 . .Ss 数学記号 . 数学記号やそれに似たものについては、このマクロを使用して ください。 .Pp .Dl 使い方: .Ms Ao 数学記号 Ac ... .Pp .Bl -tag -width ".Li .Ms\ sigma" -compact -offset 15n .It Li ".Ms sigma" .Ms sigma .El .Pp . デフォルト幅は 6n です。 . .Ss "参考文献と引用" . 次のマクロは多少なりとも参考文献を扱えるようにと意図したものです。 これらのマクロは、せいぜい .Xr refer 1 スタイルの参考文献のサブセットを手動で 作成しやすくする程度です。 .Pp .Bl -tag -width 6n -offset indent -compact .It Li .Rs 参考文献の開始 (引数はとりません)。 .Sx "SEE ALSO" セクションでは改行を挿入し、参考文献の終了マクロが 読み込まれるまで参考文献の情報を収集します。 .It Li .Re 参考文献の終了 (引数はとりません)。 参考文献が表示されます。 .It Li .%A 参考文献の作者名。1 回の呼び出しにつき、作者名をひとつ指定します。 .It Li .%B 書籍のタイトル。 .It Li .%C 市 / 場所 (まだ実装されていません)。 .It Li .%D 日付。 .It Li .%I 発行者/出版社名。 .It Li .%J 定期刊行物の名称。 .It Li .%N 発行番号。 .It Li .%O 追加情報。 .It Li .%P ページ番号。 .It Li .%Q 組織内部、あるいは外部の著者。 .It Li .%R 報告書の名称。 .It Li .%T 記事のタイトル。 .It Li .%V 巻数。 .El .Pp .Ql % で始まるマクロは呼び出し不可能ですが、 通常の方法で複数の引数をとることができます。 パラメータとしては .Ql .Tn マクロのみ扱います。その他のマクロを使うと 奇妙な出力が得られてしまいます。 .Ql .%B および .Ql .%T を .Ql .Rs/.Re 環境の外側では使用することができます。 .Pp 使用例: . .Bd -literal -offset indent \&.Rs \&.%A "Matthew Bar" \&.%A "John Foo" \&.%T "Implementation Notes on foobar(1)" \&.%R "Technical Report ABC-DE-12-345" \&.%Q "Drofnats College, Nowhere" \&.%D "April 1991" \&.Re .Ed .Pp 出力結果 . .Bd -ragged -offset indent .Rs .%A "Matthew Bar" .%A "John Foo" .%T "Implementation Notes on foobar(1)" .%R "Technical Report ABC-DE-12-345" .%Q "Drofnats College, Nowhere" .%D "April 1991" .Re .Ed . .Ss "商標名 (頭字語とタイプ名)" . 商標名マクロは、引数をより小さなフォントで出力します。 意図される使い方は、大文字の頭字語用に小さな大文字フォントを 似せて作ることです。 .Pp .Dl 使い方: .Tn Ao シンボル Ac ... .Pp .Bl -tag -width ".Li .Tn\ ASCII" -compact -offset 15n .It Li ".Tn DEC" .Tn DEC .It Li ".Tn ASCII" .Tn ASCII .El .Pp . デフォルト幅は 10n です。 . .Ss "拡張引数" . .Li .Xo と .Li .Xc マクロによって、 .Ql .It マクロ (後述) についてマクロ境界での引数リストを 拡張することができます。 .Li .Xo と .Li .Xc マクロは囲いを開いたり閉じたりする他のすべてのマクロに 対して同じように実装されている (もちろん文字は挿入しません) ということに注意してください。 つまり、次の例もこれらのマクロには当てはまります。 .Pp 次は、スペーシングをオフにするために 空白モードマクロを使った .Ql .Xo の使用例です。 . .Bd -literal -offset indent \&.Sm off \&.It Xo Sy I Ar operation \&.No \een Ar count No \een \&.Xc \&.Sm on .Ed .Pp . これは以下のような結果になります。 .Bd -filled -offset indent .Bl -tag -compact .Sm off .It Xo Sy I Ar operation .No \en Ar count No \en .Xc .Sm on .El .Ed .Pp . 例をもうひとつ: . .Bd -literal -offset indent \&.Sm off \&.It Cm S No / Ar old_pattern Xo \&.No / Ar new_pattern \&.No / Op Cm g \&.Xc \&.Sm on .Ed .Pp . これは以下のような結果になります。 . .Bd -filled -offset indent .Bl -tag -compact .Sm off .It Cm S No \&/ Ar old_pattern Xo .No \&/ Ar new_pattern .No \&/ Op Cm g .Xc .Sm on .El .Ed .Pp . 囲いマクロを使った .Ql .Xo の他の例: 変数の値をテストして下さい。 . .Bd -literal -offset indent \&.It Xo \&.Ic .ifndef \&.Oo \e&! Oc Ns Ar variable Oo \&.Ar operator variable ... \&.Oc Xc .Ed .Pp . 結果は以下の通りです。 . .Bd -filled -offset indent .Bl -tag -width flag -compact .It Xo .Ic .ifndef .Oo \&! Oc Ns Ar variable Oo .Ar operator variable ... .Oc Xc .El .Ed .Pp . . .Sh "ページ構造領域" . .Ss "セクションヘッダ" . 次の .Ql .Sh セクションヘッダマクロは、すべてのマニュアルページで必須のものです。 残りのセクションヘッダはマニュアルページの作者の裁量において、 推奨されているものです。 .Ql .Sh マクロは構文解析されますが、一般的には呼び出し不可能です。 .Ql .Sh を呼び出すときだけは、このマクロは引数として使用することができます。 この場合、 .Ql .Sh 用のデフォルトフォントを再度有効にします。 .Pp デフォルト幅は 8n です。 . .Bl -tag -width ".Li .Sh\ RETURN\ VALUES" .It Li ".Sh NAME" .Ql ".Sh NAME" マクロは必須です。 これが指定されていないと、ヘッダとフッタ、それにデフォルトの ページレイアウトが設定されず、結果はかなり好ましくないものに なるでしょう。 .Sx NAME セクションは最低 3 つの項目からなります。 最初のものは名称マクロ .Ql .Nm であり、マニュアルページのサブジェクトとなります。 2 番目のものは名称説明マクロ .Ql .Nd であり、サブジェクト名を 3 つめの項目、 すなわちその名称の説明と分離します。 説明に割り当てられるスペースは小さいものですので、 できるだけ簡潔で分かりやすいものでなければなりません。 .Pp .Ql .Nd は全ての引数の頭に .Ql - , を印字します。 . .It Li ".Sh LIBRARY" このセクションは、セクション 2 および 3 の関数呼び出しの ためにあります。 このセクションには、 .Ql .Lb マクロ呼び出し 1 つのみが含まれている必要があります。 .Sx "ライブラリ名" を参照してください。 . .It Li ".Sh SYNOPSIS" .Sx SYNOPSIS セクションはそのマニュアルページのサブジェクトとなっている項目の 典型的な使用法を説明します。 .Ql .Nm , .Ql .Cd , あるいは .Ql .Fn です (他には .Ql .Fo , .Ql .Fc , .Ql .Fd , .Ql .Ft のマクロも必要な場合があります)。 関数名マクロ .Ql .Fn はセクション 2 と 3 のマニュアルページにおいて必須のもので、 コマンドと一般名称マクロ .Ql .Nm はセクション 1, 5, 6, 7, 8 で必須の項目です。 セクション 4 のマニュアルでは .Ql .Nm か .Ql .Fd 、もしくは設定デバイス使用法マクロ .Ql .Cd が必要です。 その他のいくつかのマクロが次に示すような書式行を生成するために 必要なことがあります: . .Bd -filled -offset indent .Nm cat .Op Fl benstuv .Op Fl .Ar .Ed .Pp . 次のマクロが使われています: .Pp .Dl ".Nm cat" .Dl ".Op Fl benstuv" .Dl ".Op Fl" .Dl .Ar . .It Li ".Sh DESCRIPTION" ほとんどの場合、 .Sx "DESCRIPTION" セクションでの最初のテキストはそのコマンド、関数もしくは ファイルについての短い段落で、オプションの構文リストと それぞれの説明がそれに続きます。 そのようなリストを作成するには .Ql .Bl (リスト開始マクロ)、 .Ql .It (リスト項目マクロ)、 .Ql .El (リスト終了マクロ) を使用します (後述の .Sx リストとカラム セクションを参照)。 . .It Li ".Sh IMPLEMENTATION NOTES" 特定の実装に関する情報はここに置く必要があります。 . .It Li ".Sh RETURN VALUES" セクション 2, 3, 9 の関数の戻り値はここに来る必要があります。 .Ql .Rv を使用して、セクション 2 および 3 のライブラリ関数の .Sx RETURN VALUES セクションを生成することができます。 .Sx "戻り値" の項を参照してください。 .El .Pp . 次の .Ql .Sh セクションヘッダはマニュアルページの好ましいレイアウトの一部であり、 一貫性を保つために適切に使われなければなりません。 これらは使われる順番にリストされています。 . .Bl -tag -width ".Li .Sh\ COMPATIBILITY" .It Li ".Sh ENVIRONMENT" .Sx ENVIRONMENT セクションでは関連する環境変数および それらの振るまいや使用方法に関する手がかりを明らかにする 必要があります。 . .It Li ".Sh FILES" マニュアルページのサブジェクトによって使用されるか生成されるファイルで、 .Sx FILES セクション中でマクロ .Ql .Pa によってリストする必要があります。 . .It Li ".Sh EXAMPLES" 使用例を生成するにはいくつか方法があります。 詳細は後述の .Sx 使用例 セクションを参照してください。 . .It Li ".Sh DIAGNOSTICS" コマンドからの診断メッセージはこのセクションに置く必要があります。 . .It Li ".Sh COMPATIBILITY" 知られている互換性の問題 (例えば、非推奨になったオプションや パラメータ) をここにリストする必要があります。 . .It Li ".Sh ERRORS" 特定のエラーハンドリング、特にライブラリ関数 (マニュアルページのセクション 2, 3, 9) でのエラーハンドリングは ここで説明する必要があります。 .Ql .Er マクロはエラー (errno) を指定するのに使用されます。 . .It Li ".Sh SEE ALSO" .Sx "SEE ALSO" セクションには、そのマニュアルページの題材に関する資料への参照と 他の関連するマニュアルページへのクロスリファレンスが記載されます。 クロスリファレンスは .Ql .Xr マクロによって指定されます。 現在、 .Xr refer 1 スタイルのリファレンスには適合していません。 .Pp クロスリファレンスはセクション番号順、同一セクションにあるものは アルファベット順に並べ、カンマで区切ることを推奨します。 以下に例を示します: .Pp .Xr ls 1 , .Xr ps 1 , .Xr group 5 , .Xr passwd 5 . .It Li ".Sh STANDARDS" コマンドやライブラリ関数やファイルが、 .St -p1003.2 や .St -ansiC のような特定の実装によるものであれば、ここで記述します。 もしコマンドがどの規格にも基づいていなければ、その歴史は .Sx HISTORY のセクションで説明されなければなりません。 . .It Li ".Sh HISTORY" 特定の規格に基づいていないコマンドは、 このセクションでその歴史の概要を説明する必要があります。 . .It Li ".Sh AUTHORS" クレジットはここに置く必要があります。 人物名を指定するには .Ql .An マクロを使用する必要があります。 . .It Li ".Sh BUGS" あきらかな問題はここで記述します。 .El .Pp . ユーザ指定の .Ql .Sh セクションを追加することができます。 例えば、このセクションは以下のように設定されています。 . .Bd -literal -offset 15n \&.Sh "ページ構造領域" .Ed . .Ss "サブセクションヘッダ" . サブセクションヘッダはセクションヘッダとまったく同じ文法を しています。 .Ql .Ss は構文解析されますが、一般的に呼び出し不可能です。 このマクロは、 .Ql .Ss の呼び出し時にのみ引数として使用できます。このとき、 .Ql .Ss のデフォルトフォントが再度有効になります。 .Pp デフォルト幅は 8n です。 . .Ss "段落と行スペース" . .Bl -tag -width ".Li .Pp" .It Li .Pp .Ql .Pp 段落コマンドは必要な場合に行スペースを指定するために使われます。 このマクロは .Ql .Sh マクロや .Ql .Ss マクロの後、ならびに .Ql .Bl マクロや .Ql .Bd マクロの前では必要ありません (いずれのマクロも .Fl compact フラグが指定されていなければ垂直方向の距離を宣言します)。 .Pp このマクロは呼び出し不可能であり、構文解析もされません。そして 引数をとりません。別名は .Ql .Lp です。 .El . .\" XXX . .\" This worked with version one, need to redo for version three .\" .Pp .\" .Ds I .\" .Cw (ax+bx+c) \ is\ produced\ by\ \& .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& .\" .Cl Cx \t\t .\" .Li \&.Cx\ ( .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Va ax .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Sy \+ .\" .Cx .\" .Cl Cx \&(\& .\" .Va ax .\" .Cx + .\" .Va by .\" .Cx + .\" .Va c ) .\" .Cx \t .\" .Em is produced by .\" .Cx \t .\" .Li \&.Va by .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Sy \+ .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Va c ) .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Cx .\" .Cx .\" .Cw .\" .De .\" .Pp .\" This example shows the same equation in a different format. .\" The spaces .\" around the .\" .Li \&+ .\" signs were forced with .\" .Li \e : .\" .Pp .\" .Ds I .\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \& .\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& .\" .Cl Cx \t\t .\" .Li \&.Cx\ ( .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Va a .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Sy x .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Cx \e\ +\e\ \e& .\" .Cx .\" .Cl Cx \&(\& .\" .Va a .\" .Sy x .\" .Cx \ +\ \& .\" .Va b .\" .Sy y .\" .Cx \ +\ \& .\" .Va c ) .\" .Cx \t .\" .Em is produced by .\" .Cl Cx \t\t .\" .Li \&.Va b .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Sy y .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Cx \e\ +\e\ \e& .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Va c ) .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Cx .\" .Cx .\" .Cw .\" .De .\" .Pp .\" The incantation below was .\" lifted from the .\" .Xr adb 1 .\" manual page: .\" .Pp .\" .Ds I .\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by .\" .Cl Cx \t\t .\" .Li \&.Cx Op Sy ?/ .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Nm m .\" .Cx .\" .Cl Cx Op Sy ?/ .\" .Nm m .\" .Ad \ b1 e1 f1 .\" .Op Sy ?/ .\" .Cx \t .\" .Em is produced by .\" .Cx \t .\" .Li \&.Ar \e\ b1 e1 f1 .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Op Sy ?/ .\" .Cx .\" .Cl Cx \t\t .\" .Li \&.Cx .\" .Cx .\" .Cw .\" .De .\" .Pp . .Ss キープ . 現在実装されているキープは単語に対するものだけです。 マクロは .Ql .Bk (キープ開始) と .Ql .Ek (キープ終了) です。 現在 .Ql .Bk が受け付けるオプションは .Fl words のみで (オプションを何も与えていなければこれがデフォルトでもあります) オプションの途中で改行が入らないようにするのに便利です。 make コマンド行の引数を生成する例 ( .Sx この名前には何が の項を参照) において、キープは .Xr nroff がフラグと引数を別の行に分けないように使われています。 .Pp いずれのマクロも呼び出し不可能であり、構文解析もされません。 .Pp キープマクロについてはもっと作業をする必要があります。 特に .Fl line オプションは追加する必要があるでしょう。 . .Ss "例示とディスプレイ" . ディスプレイには 7 つのタイプがあります。 .Pp .Bl -tag -width ".Li .D1" .It Li .D1 (D-いちです) インデントされたテキストを 1 行表示します。 このマクロは構文解析されますが、呼び出し不可能です。 .Pp .D1 Fl ldghfstru .Pp これは次の指定で生成されたものです: .Li ".D1 Fl ldghfstru" . .It Li .Dl (D-エルです) インデントされた .Em リテラル テキストを 1 行表示します。 .Ql .Dl マクロの例は本ファイル中にわたって使われています。 これによって 1 行のテキストのインデント (表示) が可能になります。 デフォルトフォントは固定幅 (リテラル) に設定されます。 .Ql .Dl は構文解析されますが、呼び出し不可能です。 .Pp .Dl % ls -ldg /usr/local/bin .Pp これは、次の指定で生成されたものです: .Li ".Dl % ls -ldg /usr/local/bin" . .It Li .Bd ディスプレイ開始。 .Ql .Bd ディスプレイは .Ql .Ed マクロで終了しなければなりません。 これは、次の書式をとります: .Pp .Bl -tag -width ".Li .Bd" -offset indent .It Li .Bd Xo .Bro \-literal | \-filled | \-unfilled | \-ragged | \-centered Brc .Oo \-offset Ao 文字列 Ac Oc Oo \-file Ao ファイル名 Ac Oc Oo \-compact Oc Xc .El .Pp . .Bl -tag -width ".Fl file Ao Ar ファイル名 Ac " -compact .It Fl ragged 行詰めされますが、右マージンは調整しません (左マージンのみです)。 .It Fl centered 現在の左マージンと右マージン間の中央線です。 線それぞれが中央揃えになるということに注意してください。 .It Fl unfilled 行詰めしません。テキストのブロックを入力されたままの状態で 表示します。改行もユーザが指定した通りに使われます。 このため、何の警告メッセージも出さずに長過ぎる行を 生成する可能性があります。 .It Fl filled 行詰めされたブロックを表示します。 テキストブロックが整形されます (つまり、 テキストは左右どちら側にも揃えられます)。 .It Fl literal リテラルフォント (通常固定幅) でブロックを表示します。 ソースコードや、単純にタブもしくは空白で整えられた テキストには便利です。 .It Fl file Ao Ar ファイル名 Ac .Fl file フラグに続いた名前を持ったファイルが読み込まれ、 指定されたディスプレイタイプで .Ql .Bd と .Ql .Ed マクロで囲まれたデータよりも前に表示されます。 ファイル中の .Xr troff/ Ns Nm \-mdoc コマンドはどんなものでも処理されます。 .It Fl offset Ao Ar 文字列 Ac .Fl offset が以下の文字列のいずれかとともに指定されていると、 その文字列は次のテキストのブロックのインデントのレベルを示すものとして 解釈されます。 . .Pp .Bl -tag -width ".Ar indent-two" -compact .It Ar left ブロックを現在の左マージンに揃えます。 これは .Ql .Bd のデフォルトのモードです。 .It Ar center ブロックを中央揃えにします。 残念ながら現時点では、 単にブロックの左側を仮想的な中央マージンに揃えるだけです。 .It Ar indent デフォルトのインデント値もしくはタブの分だけインデントします。 デフォルトのインデント値は .Ql .D1 および .Ql .Dl マクロでも使われていますので、この 2 つのディスプレイと 行が揃うことが保証されています。 インデント値は通常 6n つまり約 2/3 インチ (固定幅文字 6 つ分) です。 .It Ar indent-two デフォルトのインデント値の 2 倍分インデントします。 .It Ar right これはブロックをページの右端から約 2 インチ離して .Em 左 揃えします。 このマクロはちゃんと動作する必要があるのですが、 .Xr troff ではまったくちゃんと動作してくれていません。 .El .Pp . .Ao 文字列 Ac がそれ以外で正しい数値表現をしている場合 .Pf ( Sq Em u .Em 以外のスケール指示子を伴う)、 インデント用にその値を使用します。 スケール指示子のなかで最も役に立つものは .Sq m および .Sq n です。これらはいわゆる .Em \&Em と .Em "En square" を指定します。 これは、現在のフォントでの文字 .Sq m および文字 .Sq n の幅とほぼ同じです ( nroff の出力については、 どちらのスケール指示子でも同じ値が得られます )。 .Ao 文字列 Ac が数値表現をしていない場合、文字列は .Nm \-mdoc マクロ名であるかどうか検査され、このマクロに関連する デフォルトのオフセット値が使われます。 最終的にすべてのテストが失敗した場合 the width of .Ao 文字列 Ac の幅 (固定幅フォントでのタイプセット) がオフセットと見なされます。 .It Fl compact ディスプレイを開始するときに垂直方向の空白を挿入しないようにします。 .El . .It Li .Ed ディスプレイの終了 (引数はとりません)。 .El . .Ss "リストとカラム" . リスト開始マクロ .Ql .Bl で開始できるリストには何種類かあります。 リスト中の項目は項目マクロ .Ql .It で指定され、各リストは .Ql .El マクロで終了しなければなりません。 リストはリスト自身やディスプレイの中で入れ子にすることができます。 リスト中でカラムを使ったり、カラムの中でリストを使ったりすることに ついては検証されていません。 .Pp さらに、タグ幅、リストのオフセット、コンパクトの度合 (項目間の空白行が許されているかどうか) のような リストの属性をいくつか指定することができます。 本ドキュメントのほとんどはタグ .Pf ( Fl tag ) スタイルリストで整形されています。 .Pp このマクロは次の文法規則を持っています: . .Pp .Bl -tag -width ".Li .Bl" -offset indent -compact .It Li .Bl Xo .Bro \-hang | \-ohang | \-tag | \-diag | \-inset Brc .Oo \-width Ao 文字列 Ac Oc .Oo \-offset Ao 文字列 Ac Oc Oo \-compact Oc Xc .It Li .Bl Xo .No \-column Oo \-offset Ao 文字列 Ac Oc .Ao 文字列1 Ac Ao 文字列2 Ac ... Xc .It Li .Bl Xo .Bro \-item | \-enum Oo \-nested Oc | \-bullet | \-hyphen | \-dash Brc .Oo \-offset Ao 文字列 Ac Oc Oo \-compact Oc Xc .El .Pp . 次に、このリストタイプの詳細な解説を行います。 . .Pp .Bl -tag -width ".Fl column" -compact .It Fl bullet ビュレットリストです。 . .Bd -literal -offset indent \&.Bl -bullet -offset indent -compact \&.It 1 つ目のビュレットはここにきます。 \&.It 2 つ目のビュレットはここにきます。 \&.El .Ed .Pp . 生成結果は次の通りです: . .Pp .Bl -bullet -offset indent -compact .It 1 つ目のビュレットはここにきます。 .It 2 つ目のビュレットはここにきます。 .El .Pp . .It Fl dash No ( または Fl hyphen ) ダッシュ文字によるリストです。 . .Bd -literal -offset indent \&.Bl -dash -offset indent -compact \&.It 1 つ目のダッシュはここにきます。 \&.It 2 つ目のダッシュはここにきます。 \&.El .Ed .Pp . 生成結果は次の通りです: . .Pp .Bl -dash -offset indent -compact .It 1 つ目のダッシュはここにきます。 .It 2 つ目のダッシュはここにきます。 .El .Pp . .It Fl enum 箇条書きリストです。 . .Bd -literal -offset indent \&.Bl -enum -offset indent -compact \&.It 1 つ目の項目はここにきます。 \&.It 2 つ目の項目はここにきます。 \&.El .Ed .Pp . 生成結果は次の通りです: . .Pp .Bl -enum -offset indent -compact .It 1 つ目の項目はここにきます。 .It 2 つ目の項目はここにきます。 .El .Pp . 箇条書きリストを入れ子にしたい場合、 .Fl nested フラグを使用してください (第 2 レベルのリストが開始されます): . .Bd -literal -offset indent \&.Bl -enum -offset indent -compact \&.It 1 つ目の項目はここにきます。 \&.Bl -enum -nested -compact \&.It 2 つ目の項目はここにきます。 \&.It 3 つ目の項目はここにきます。 \&.It \&.El \&.It 4 つ目の項目はここにきます。 \&.El .Ed .Pp . 生成結果は次の通りです: . .Pp .Bl -enum -offset indent -compact .It 1 つ目の項目はここにきます。 .Bl -enum -nested -compact .It 2 つ目の項目はここにきます。 .It 3 つ目の項目はここにきます。 .El .It 4 つ目の項目はここにきます。 .El .Pp . .It Fl item リストの印をつけない .Fl item タイプのリストです。 . .Bd -literal -offset indent \&.Bl -item -offset indent \&.It 1 つ目の項目はここにきます。 1 つ目の項目はここにきます。 1 つ目の項目はここにきます。 \&.It 2 つ目の項目はここにきます。 2 つ目の項目はここにきます。 2 つ目の項目はここにきます。 \&.El .Ed .Pp . 生成結果は次の通りです: . .Pp .Bl -item -offset indent .It 1 つ目の項目はここにきます。 1 つ目の項目はここにきます。 1 つ目の項目はここにきます。 .It 2 つ目の項目はここにきます。 2 つ目の項目はここにきます。 2 つ目の項目はここにきます。 .El .Pp . .It Fl tag タグつきリストです。 タグ幅を指定するには .Fl width を使用してください。 . .Pp .Bl -tag -width "PPID" -compact -offset indent .It SL プロセスが sleep している時間 (ブロックされた秒数) .It PAGEIN そのプロセスによって、まだメモリにロードされていないページへの参照が 起こることにより生じたディスク .Tn I/O の回数 .It UID 数値表記によるプロセス所有者のユーザ ID .It PPID 数値表記による親プロセスの ID、プロセスの優先度 (割り込み不可の待機状態のときには、正でない値になる) .El .Pp . 元のテキストは次の通りです: . .Bd -literal -offset indent \&.Bl -tag -width "PPID" -compact -offset indent \&.It SL プロセスが sleep している時間 (ブロックされた秒数) \&.It PAGEIN そのプロセスによって、まだメモリにロードされていないページへの参照が 起こることにより生じたディスク \&.Tn I/O の回数 \&.It UID 数値表記によるプロセス所有者のユーザ ID \&.It PPID 数値表記による親プロセスの ID、プロセスの優先度 (割り込み不可の待機状態のときには、正でない値になる) \&.El .Ed .Pp . .It Fl diag 診断リストはセクション 4 の診断リストを生成するもので、 呼び出し可能なマクロが無視されることを除き、inset リストと似ています。 フラグ .Fl width は、この文脈では意味がありません。 .Pp 使用例: . .Bd -literal -offset indent \&.Bl -diag \&.It ここで Sy を使うことはできません。 このメッセージはすべて出力されます。 \&.El .Ed .Pp . 生成結果 . .Bl -diag .It ここで Sy を使うことはできません。 このメッセージはすべて出力されます。 .El .Pp . .It Fl hang ぶら下がりタグつきリストです。 . .Bl -hang -offset indent .It Em Hanged ラベル幅よりもラベルが小さい場合には ぶら下げられたラベルはタグつきリストと同じように見えます。 .It Em Longer hanged list labels ラベル幅より長いぶら下がりリストのラベルは、 タグつき段落ラベルとは違い、段落に溶け込みます。 .El .Pp 以上の文章を生成した、整形前のテキストは 次の通りです: . .Bd -literal -offset indent \&.Bl -hang -offset indent \&.It Em Hanged ラベル幅よりもラベルが小さい場合には ぶら下げられたラベルはタグつきリストと同じようにみえます。 \&.It Em Longer Hanged list labels ラベル幅より長いぶら下がりリストのラベルは、 タグつき段落ラベルとは違い、段落に溶け込みます。 \&.El .Ed .Pp . .It Fl ohang オーバハングタグ (overhanging tags) を用いたリストは 項目に対してインデントを使いません。 タグは別の行に出力されます。 .Pp .Bl -ohang -offset indent .It Sy SL プロセスが sleep している時間 (ブロックされた秒数) .It Sy PAGEIN そのプロセスによって、まだメモリにロードされていないページへの参照が 起こることで生じたディスク .Tn I/O の回数 .It Sy UID 数値表記によるプロセス所有者のユーザ ID .It Sy PPID 数値表記による親プロセスの ID、プロセスの優先度 (割り込み不可の待機状態のときには、正でない値になる) .El .Pp . 元のテキストは次の通りです: . .Bd -literal -offset indent \&.Bl -ohang -offset indent \&.It Sy SL プロセスが sleep している時間 (ブロックされた秒数) \&.It Sy PAGEIN そのプロセスによって、まだメモリにロードされていないページへの参照が 起こることで生じたディスク \&.Tn I/O の回数 \&.It Sy UID 数値表記によるプロセス所有者のユーザ ID \&.It Sy PPID 数値表記による親プロセスの ID、プロセスの優先度 (割り込み不可の待機状態のときには、正でない値になる) \&.El .Ed .Pp . .It Fl inset 次は、inset ラベルの例です: .Bl -inset -offset indent .It Em tag タグリスト (タグ段落とも呼びます) は バークレーのマニュアルで使われている最も一般的な 種類のリストです。 後で述べるように、 .Fl width 属性を使用してください。 .It Em diag 診断リストはセクション 4 の診断リストを生成し、 呼び出し可能なマクロを無視するという点を除けば inset リストと似ています。 .It Em hang ぶら下がりラベルは気分の問題です。 .It Em ohang オーバハングラベルは空白に制限がある場合には良いです。 .It Em inset inset ラベルは段落ブロックを制御するのに便利で、 .Nm \-mdoc マニュアルを別のフォーマットに変換するのに有用です。 .El .Pp 上の例を生成したソーステキストはこうなっています: . .Bd -literal -offset indent \&.Bl -inset -offset indent \&.It Em tag タグリスト (タグ段落とも呼びます) は バークレーのマニュアルで使われている最も一般的な 種類のリストです。 後で述べるように、 \&.Fl width 属性を使用してください。 \&.It Em diag 診断リストはセクション 4 の診断リストを生成し、 呼び出し可能なマクロを無視するという点を除けば inset リストと似ています。 \&.It Em hang ぶら下がりラベルは気分の問題です。 \&.It Em ohang オーバハングラベルは空白に制限がある場合には良いです。 \&.It Em inset inset ラベルは段落ブロックを制御するのに便利で、 \&.Nm \-mdoc マニュアルを別のフォーマットに変換するのに有用です。 \&.El .Ed .Pp . .It Fl column この種類のリストは複数カラムを生成します。 カラムの数および各カラムの幅は .Fl column リストへの引数、 .Aq Ar string1 , .Aq Ar string2 等によって決定されます。 .Aq Ar stringN が .Ql .\& (ドット) で開始し直後に有効な .Nm \-mdoc マクロ名が続く場合、 .Aq Ar stringN を解釈して結果の幅を使用します。 そうでない場合、 .Aq Ar stringN (固定幅フォントでのタイプセット) は .Ar N 番目の桁の幅になります。 .Pp .Ql .It 引数はそれぞれ構文解析され行を生成します。 行中の各列はタブや .Ql .Ta マクロで分けられた引数です。 .Pp 次の表、 . .Bl -column -offset indent ".Sy 文字列" ".Sy nroff" ".Sy troff" .It Sy 文字列 Ta Sy nroff Ta Sy troff .It Li <= Ta <= Ta \*(<= .It Li >= Ta >= Ta \*(>= .El .Pp . は次のようにして生成されています: . .Bd -literal -offset indent \&.Bl -column -offset indent ".Sy 文字列" ".Sy nroff" ".Sy troff" \&.It Sy 文字列 Ta Sy nroff Ta Sy troff \&.It Li <= Ta <= Ta \e*(<= \&.It Li >= Ta >= Ta \e*(>= \&.El .Ed .El .Pp . その他のキーワード: . .Bl -tag -width ".Fl indent Ao Ar 文字列 Ac" .It Fl width Ao Ar 文字列 Ac .Aq Ar 文字列 が .Ql .\& (ドット) で開始し直後に有効な .Nm \-mdoc マクロ名が続く場合、 .Aq Ar 文字列 を解釈し、その結果の幅を使います。 本ドキュメントのほとんどすべてのリストは このオプションを使用しています。 .Pp 使用例: . .Bd -literal -offset indent \&.Bl -tag -width ".Fl test Ao Ar 文字列 Ac" \&.It Fl test Ao Ar 文字列 Ac これは、 \&.Fl width フラグをタグリストと一緒に使うとどのように 働くかを見るためのもっと長い文です。 \&.El .Ed .Pp . 生成結果: . .Bl -tag -width ".Fl test Ao Ar 文字列 Ac" .It Fl test Ao Ar 文字列 Ac これは、 .Fl width フラグをタグリストと一緒に使うとどのように 働くかを見るためのもっと長い文です。 .El .Pp . .Ao 文字列 Ac が解釈される前に現在の .Nm \-mdoc の状態が保存されることに注意してください。 文字列が解釈された後ですべての変数が再度復元されます。 しかし、ボックス (囲いに使用される) は .Tn GNU .Xr troff 1 では保存されません。結果としては、醜いエラーを防ぐためには 引数は常に .Em 平衡がとれて いなくてはなりません。 例えば、本当に開き山括弧だけが必要である場合には .Ql ".Ao Ar 文字列" と書いてはだめで、代わりに .Ql ".Ao Ar 文字列 Xc" と書かなくてはなりません。 .Pp そうでない場合、 .Aq Ar 文字列 が正当な数値表現である場合 .Sq ( Em u .Em 以外のスケール指示子を伴う)、 インデント用にその値を使用します。 最も有用なスケール指示子は .Sq m と .Sq n です。これらはいわゆる .Em \&Em および .Em "En square" を指定します。 これは、現在のフォントでの文字 .Sq m および文字 .Sq n の幅とほぼ同じです (nroff の出力については、 どちらのスケール指示子でも同じ値が得られます)。 .Aq Ar 文字列 が数値表現をしていない場合、文字列は .Nm \-mdoc マクロ名であるかどうか検査され、このマクロに関連する デフォルトのオフセット値が使われます。 最終的にすべてのテストが失敗した場合 .Aq Ar 文字列 の幅 (固定幅フォントでのタイプセット) がオフセットと見なされます。 .Pp タグリストタイプ用に幅が指定されていない場合、 .Ql .It が起動される度に適切な幅を決定しようと試みます。 .Ql .It の第 1 引数が呼び出し可能なマクロである場合、 そのマクロのデフォルト幅が使われます。 そうでなければ、 .Ql .No のデフォルト幅が使われます。 .Pp .It Fl offset Ao Ar 文字列 Ac .Aq Ar 文字列 が .Ar indent である場合、デフォルトのインデント値 (通常 6n に設定されており、 .Ql .Dl または .Ql .Bd で使われる値と似ています) が使われます。 .Aq Ar 文字列 が正当な数値表現である場合 .Pf ( Sq Em u 以外のスケール指示子を伴う )、 その値をインデントに使用します。 最も有用なスケール指示子は .Sq m と .Sq n であり、これらはいわゆる .Em \&Em および .Em "En square" です。 これは、それぞれ現在のフォントでの .Sq m と .Sq n の幅とほぼ同じです (nroff の出力については、 どちらのスケール指示子も同じ値をとります)。 .Ao 文字列 Ac が数値表現でない場合、その文字列が .Nm \-mdoc のマクロ名であるかどうか検査され、このマクロに関連する デフォルトのオフセット値が使われます。 最終的にすべてのテストが失敗した場合、 .Aq Ar 文字列 の幅 (固定幅フォントでのタイプセット) がオフセットとして とられます。 .It Fl compact リストの前およびリスト項目間に垂直方向の空白を挿入しないように します。 .El . . .Sh "その他のマクロ" . ここには、いままでのセクションにはうまく当てはまらなかった 残りのマクロのリストがあります。 次のマクロに対しては本物の使用例を見つけられませんでした。 それは .Ql .Me と .Ql .Ot です。この 2 つについても完璧を期するためにここに 文書化はしています。もしこの 2 つのマクロの 適切な使い方をご存知であれば .Mt bug-groff@gnu.org までメールを送ってください (例つきで)。 . .Bl -tag -width ".Li .Bt" .It Li .Bt は . .Bd -ragged -offset indent .Bt .Ed .Pp を表示します。 .Pp このマクロは呼び出し不可能であり、構文解析もされません。 また引数もとりません。 . .It Li .Fr .Pp .Dl 使い方: .Fr Ao 関数の戻り値 Ac ... .Pp このマクロは使わないでください。 このマクロは戻り値 (通常は数字 1 個) の直前での 改行を許してしまいます。 印刷時の振る舞いとしては悪いことです。 直前の単語と戻り値とを結合させるには .Ql \e~ を使用してください。 . .It Li .Hf (ヘッダ) ファイルをそのまま含めるにはこのマクロを 使ってください。 このマクロは、最初に .Ql File: とファイル名を表示し、その後で .Ao ファイル Ac の内容を表示します。 .Pp .Dl 使い方: .Hf Ao ファイル Ac .Pp このマクロは呼び出し不可能であり、構文解析もされません。 . .It Li .Lk 将来書かれる予定です。 . .It Li .Me 正確な使用方法は分かりません。 .Nm \-mdoc ソースファイル中の記述では .Dq "メニューエントリ" となっています。 .Pp デフォルト幅は 6n です。 . .It Li .Mt 将来書かれる予定です。 . .It Li .Ot 正確な使用方法は分かりません。 .Nm \-mdoc ソースファイル中の記述では .Dq "古い関数タイプ (fortran)" となっています。 . .It Li .Sm 空白モードを有効に (トグル) します。 .Pp .Dl 使い方: .Sm Oo on | off Oc ... .Pp 空白モードが off の場合、マクロ引数の間に空白は 挿入されません。引数なしで呼ばれた場合 (あるいは 次の引数が .Ql on でも .Ql off でもない場合) .Ql .Sm マクロは空白モードに入ります。 . .It Li .Ud マクロは . .Bd -ragged -offset indent .Ud .Ed .Pp を表示します。 .Pp このマクロは呼び出し不可能であり、構文解析もされません。 また引数もとりません。 .El . . .Sh "定義済み文字列" . 次の文字列が定義済みです: .Pp .Bl -column 文字列 infinity "troff " "まっすぐなダブルクォート" -offset indent .It Sy 文字列 Ta Sy nroff Ta Sy troff Ta Sy 意味 .It Li <= Ta <= Ta \*[<=] Ta "以下" .It Li >= Ta >= Ta \*[>=] Ta "以上" .It Li Rq Ta '' Ta \*[Rq] Ta "右側のダブルクォート" .It Li Lq Ta `` Ta \*[Lq] Ta "左側のダブルクォート" .It Li ua Ta ^ Ta \*[ua] Ta "上向き矢印" .It Li aa Ta \' Ta \*[aa] Ta "アキュートアクセント" .It Li ga Ta \` Ta \*[ga] Ta "グレーブアクセント" .It Li q Ta \&" Ta \*[q] Ta "まっすぐなダブルクォート" .It Li Pi Ta pi Ta \*[Pi] Ta "ギリシャ語のパイ" .It Li Ne Ta != Ta \*[Ne] Ta "不等号" .It Li Le Ta <= Ta \*[Le] Ta "以下" .It Li Ge Ta >= Ta \*[Ge] Ta "以上" .It Li Lt Ta < Ta \*[Lt] Ta "小なり" .It Li Gt Ta > Ta \*[Gt] Ta "大なり" .It Li Pm Ta +\- Ta \*[Pm] Ta "プラスマイナス" .It Li If Ta infinity Ta \*[If] Ta "無限" .It Li Na Ta \*[Na] Ta \*[Na] Ta "非数値" .It Li Ba Ta \*[Ba] Ta \*[Ba] Ta "垂直線" .El .Pp カラムの名前 .Sy nroff と .Sy troff は少々誤解を招くものです。 .Sy nroff は .Tn ASCII 文字を表示しますが、 .Sy troff では利用可能なもののうち一番良いグリフ形式を 表示します。 例えば、Unicode を使用可能にした .Tn TTY デバイスはすべての文字列に対して適切なグリフ表現を 持っていますが、それに対して Latin1 に対して機能を強化した .Tn TTY デバイスはプラスマイナス記号しか持っていません。 .Pp 文字を 2 つ含んだ文字列名は .Ql \e*(xx として表記できます。 文字を 1 文字だけ含んだ文字列名は .Ql \e*x と表記できます。 どのような長さの文字列名に対しても、一般的な文法は .Ql \e*[xxx] となります ( これは .Tn GNU .Xr troff 1 拡張です)。 . . \# \#===================================================================== \# .Sh 診断 . 以前のバージョンの .Nm \-mdoc パッケージでは利用可能だったデバッグ用マクロ .Ql .Db は取り除かれました。なぜなら、 .Tn GNU .Xr troff 1 ではパラメータをチェックするのにもっと良いファシリティを 提供しているからです。さらに、このマクロパッケージには エラーや警告メッセージが多数追加されており、よりロバストで 饒舌なものになっています。 .Pp 唯一残ったデバッグ用マクロは .Ql .Rd であり、これはすべてのグローバルレジスタならびに文字列の レジスタダンプを出力するものです。 通常のユーザが使う必要は決してないでしょう。 . . .Sh "GROFF, TROFF, および NROFF を使用した整形" . デフォルトでは、このパッケージでは .Sq latin1 や .Sq unicode のような .Tn TTY デバイスで表示する場合には改ページやヘッダ、フッタは 禁止されており、マニュアルをオンラインで効率良く 見ることができるようになっています。 この振る舞いは、 .Xr groff を呼んでいるときにレジスタ .Q1 cR に 0 を指定することで変更することができます (例えば、 .Tn TTY 出力のハードコピーを作成したいときなど)。 .Pp .Dl groff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt .Pp 両面印刷用には、レジスタ .Ql D を 1 に設定してください: .Pp .Dl groff -Tps -rD1 -mdoc foo.man > foo.ps .Pp ドキュメントのフォントサイズを 11pt や 12pt に変更したい 場合は、レジスタ .Ql S をそれに合わせて設定してください: .Pp .Dl groff -Tdvi -rS11 -mdoc foo.man > foo.dvi .Pp レジスタ .Ql S は .Tn TTY デバイスに対しては無視されます。 . . .Sh 関連ファイル . .Bl -tag -width mdoc/doc-ditroff -compact .It Pa doc.tmac 主なマニュアル用マクロパッケージです。 .It Pa mdoc.tmac .Pa doc.tmac を呼ぶラッパファイルです。 .It Pa mdoc/doc-common 共通する文字列、定義、および印刷出力に関連する項目です。 .It Pa mdoc/doc-nroff .Tn TTY 出力デバイス用に使用される定義です。 .It Pa mdoc/doc-ditroff その他すべてのデバイス用に使用される定義です。 .It Pa mdoc.local ローカルマシンでの追加項目およびカスタマイズ項目です。 .It Pa andoc.tmac このファイルは .Nm \-mdoc パッケージと .Nm \-man パッケージのどちらを使用すべきかをチェックします。 .El . . .Sh "関連項目" . .Xr groff 1 , .Xr man 1 , .Xr troff 1 , .Xr groff_man 7 . . .Sh バグ . セクション 3f はヘッダルーチンには追加されていません。 .Pp .Ql \&.Nm .Sx NAME セクションにおいては、フォントを変更するべきです。 .Pp 行の長さが短すぎる場合に行が分割されるのを防ぐために .Ql \&.Fn がチェックを行う必要があります。 ときどき、最後の括弧が分割されることがあり、 行詰めモードであるときにおかしな結果になることがあります。 .Pp リストマクロおよびディスプレイマクロは何のキープも 行いませんが、これはキープを行うべきです。 .\" Note what happens if the parameter list overlaps a newline .\" boundary. .\" to make sure a line boundary is crossed: .\" .Bd -literal .\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[] .\" .Ed .\" .Pp .\" produces, nudge nudge, .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , .\" nudge .\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] . .\" .Pp .\" If double quotes are used, for example: .\" .Bd -literal .\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q .\" .Ed .\" .Pp .\" produces, nudge nudge, .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , .\" nudge .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , .\" nudge .\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" . .\" .Pp .\" Not a pretty sight... .\" In a paragraph, a long parameter containing unpaddable spaces as .\" in the former example will cause .\" .Xr troff .\" to break the line and spread .\" the remaining words out. .\" The latter example will adjust nicely to .\" justified margins, but may break in between an argument and its .\" declaration. .\" In .\" .Xr nroff .\" the right margin adjustment is normally ragged and the problem is .\" not as severe. . .\" Local Variables: .\" mode: nroff .\" End: .\" .SH 履歴 .\" Yoshiteru Kageyama 2001/06/10 mdoc.samples.7 .\" を参考に翻訳 .\" MORI Kouji 2001/08/21 訳チェック diff --git a/ja_JP.eucJP/man/man7/tuning.7 b/ja_JP.eucJP/man/man7/tuning.7 index 7cecd04753..5a4418fa60 100644 --- a/ja_JP.eucJP/man/man7/tuning.7 +++ b/ja_JP.eucJP/man/man7/tuning.7 @@ -1,757 +1,756 @@ .\" Copyright (c) 2001, Matthew Dillon. Terms and conditions are those of .\" the BSD Copyright as specified in the file "/usr/src/COPYRIGHT" in .\" the source tree. .\" .\" %FreeBSD: src/share/man/man7/tuning.7,v 1.1.2.25 2001/12/26 15:21:42 rwatson Exp % .\" .\" $FreeBSD$ .Dd May 25, 2001 .Dt TUNING 7 .Os .Sh 名称 .Nm tuning .Nd FreeBSD における性能チューニング .Sh システム設定 - disklabel, newfs, tunefs, スワップ .Xr disklabel 8 を使ってハードディスク上にファイルシステムをレイアウトする場合、 ディスクの内周トラックよりも外周トラックのほうがずっと速くデータを 転送できることを意識することが重要です。この利点を生かすには、 小さいファイルシステムやスワップを外周トラックに近いほうから 詰めていくべきです。より大きいファイルシステムは内周へ近いほうへ詰めていき、 最も大きいファイルシステムを最後にします。 後でマシンを増強した時にシステム標準のファイルシステムの大きさを 変更しなくて済むような大きさに決めることが重要です。 私は大抵、順番にルートパーティションに 128M、スワップに 1G、 .Pa /var に 128M、 .Pa /var/tmp に 128M、 .Pa /usr に 3G、 そして残りを .Pa /home に割り当てます。 .Pp 典型的にはメインメモリの約 2 倍のスワップスペースを用意すべきです。 RAM がそれほど多くない場合は、一般にもっとスワップが必要でしょう。 256M より小さいスワップを設定するのは奨められません。スワップ パーティションの大きさを決めるときは将来のメモリ増設のことを 考えておくべきです。 カーネルの VM ページングアルゴリズムは、スワップの大きさが メインメモリの少なくとも 2 倍ある場合に最高の 性能が出るようにチューンされています。スワップを小さくしすぎると、 VM ページ走査コードが効率的に動かなくなります。 メモリをさらに追加した時も同様です。 最後に、複数の SCSI ディスク (あるいは異なるコントローラ上にある 複数の IDE ディスク) を備えた大規模なシステムにおいては、 それぞれのドライブ (最大 4 ドライブ) にスワップを置くことを強く推奨します。 各ドライブ上のスワップパーティションがほぼ同じ大きさになる ようにしてください。 カーネルは任意の大きさを扱うことができますが、内部のデータ構造は 最大のスワップパーティションのものの 4 倍の大きさになってしまいます。 スワップパーティションをだいたい同じ大きさにすることで、 カーネルは最適な方法でスワップ空間を N 台のディスクに対し ストライピングします。 少々のやりすぎを気にする必要はありません。スワップ空間は .Ux が優雅に動作するためのものです。 普段それほどスワップを使っていなくても、 プログラムの暴走で強制的にリブートしてしまう前に、 回復作業をするための時間稼ぎになります。 .Pp .Pa /var パーティションをどれだけの大きさにするかは、そのマシンを 何に使うかということに大きく依存します。 このパーティションは主にメールボックスやプリントスプール、 ログファイルの保存場所に使われます。 .Pa /var/log を別のパーティションにする人もいます (しかし、パーティション ID を 消費しないほうが良い極端な場合は例外です)。 メールサーバやプリントサーバ、あるいは 訪問数が非常に多い Web サーバとしてマシンが動作するなら、 極めて大きいパーティション \(en おそらく 1 ギガバイト以上 \(en を 作成することを考えるべきでしょう。 ログファイルの保存に必要な大きさは、小さく見積もられがちです。 .Pp .Pa /var/tmp の大きさは、テンポラリファイルの類が どれだけ使われる必要があるかで決まります。 最低でも 128M にすることを推奨します。 sysinstall は .Pa /tmp ディレクトリを作成しますが、 .Pa /tmp は後で .Pa /var/tmp へのソフトリンクにしておくのは大抵良い考えです。 テンポラリファイル領域専用に 1 つのパーティションを 割り当てることは重要で、2 つの理由があります: クラッシュ時のファイルシステムの破壊の可能性を 減らすのと、 .Oo Pa /var Oc Ns Pa /tmp を一杯にしてしまう ような暴走プロセスが、さらに重要なサブシステム (メールやログ等) に影響を与える可能性を減らすためです。 .Oo Pa /var Oc Ns Pa /tmp が一杯になってしまうのはよくある問題です。 .Pp かつては .Pa /tmp と .Pa /var/tmp の間には違いがありましたが、 .Pa /var (と .Pa /var/tmp ) の導入によってプログラマは大変混乱し、 今日では両方がでたらめに使われています。 つまりこの 2 つは実際には区別することができません。 したがって、1 つのテンポラリディレクトリだけにしてしまうことは 意味があります。 どのように .Pa /tmp を扱ったとしても、 それがルートパーティションにあるのは好ましくないでしょう。 一杯になったり、クラッシュやリブートにより破壊される 可能性があるからです。 .Pp .Pa /usr パーティションはシステムをサポートするために 必要なファイルの大部分を持っており、そのサブディレクトリ .Pa /usr/local は .Xr ports 7 階層からインストールされるファイルの大部分が置かれます。 ports をあまり使わず、システムのソース .Pq Pa /usr/src を保持するつもりがなければ .Pa /usr は 1 ギガバイトで十分でしょう。 しかし、大量の ports (特にウィンドウマネージャや Linux エミュレーションされるバイナリ) をインストールする場合は、 少なくとも 2 ギガバイトの .Pa /usr を推奨します。 さらに、システムのソースを保持するつもりであれば、3 ギガバイトの .Pa /usr を推奨します。 このパーティションに対して必要な領域の大きさを過小評価 しないでください。これは緩やかに成長し、驚かされることになります ! .Pp .Pa /home パーティションはユーザ固有のデータを保持するのに使われます。 私は大抵ディスクの残りを使います。 .Pp 何故 パーティションを切るのでしょう ? 1 つの大きな .Pa / パーティションを作るだけで良いのではないでしょうか ? そうすれば小さすぎないかどうか気にする必要はないのに ! はい、その考えが良くないのは、いくつか理由があります。 1 つめは、それぞれのパーティションは運用上の性格が 異なるのですが、それらを分離することでファイルシステムに対し その性格に適したチューンをすることが可能になるからです。 例えばルートパーティションや .Pa /usr パーティションはほとんど読み込みであり、ほとんど書き込みがありません。 一方で .Pa /var や .Pa /var/tmp に対しては大量の読み込みや書き込みがあるでしょう。 システムをうまく分割することで、書き込みが多いパーティションの破壊に よる被害が、ほとんど読み込みのみのパーティションに及ばないようします。 加えて、書き込みが多いパーティションをディスクの端 (すなわちパーティションテーブルにおいて、 本当に大きなパーティションの後ろではなく、前の方) の方に置くことで、そのパーティションについて性能が向上します。 より大きなパーティションについても入出力性能が必要なのも確かですが、 .Pa /var をディスクの端に置くと大きな改善が可能であるのに対し、 巨大なパーティションをディスクの端に置いてもそれほど性能の 改善にはつながりません。 最後は安全性に関わることです。 小さく、簡潔な、本質的に読み込みのみの ルートパーティションとすることで、クラッシュを生き延びるチャンスを 大きくすることができます。 .Pp システムを正しく分割することで、 .Xr newfs 8 や .Xr tunefs 8 に与えるパラメータをチューンすることも可能になります。 .Fn newfs のチューニングにはさらに経験が必要ですが、かなりの性能改善につながります。 比較的安全にチューンできる 3 つのパラメータがあります: .Em blocksize , .Em bytes/inode , .Em cylinders/group です。 .Pp .Fx は 8K または 16K のファイルシステムブロックサイズを使用した時に 最高の性能が得られます。 デフォルトは 16K であり、 ほとんどのアプリケーションで良い結果となりますが、 大きなファイルにランダムアクセスするアプリケーション (データベースサーバソフトウェア等) は例外です。 このようなアプリケーションでは、 小さなブロックサイズで良い結果となる傾向がありますが、 最近のディスクの特性においては、 小さなブロックサイズの使用は考慮に値しないでしょう。 16K より大きなブロックサイズを使用すると バッファキャッシュの断片化を招き、性能が低下します。 .Pp デフォルトは、 多大な inode を必要とするファイルシステムや、 多大な小ファイルを保持することを意図したファイルシステムには 向かないかもしれません。 このようなファイルシステムは、 8K または 4K のブロックサイズで作成されるべきです。 これはまた、小さなフラグメントサイズを指定する必要があります。 常にブロックサイズの 1/8 のフラグメントサイズにすることを推奨します (他のフラグメントサイズの割合ではあまりテストされていません)。 この場合の .Xr newfs 8 オプションは .Dq Li "newfs -f 1024 -b 8192 ..." となるでしょう。 .Pp 大きなパーティションに、データベースファイルのような 少数の大きなファイルを置くのであれば、 .Em bytes/inode の比率を増やすことができます。これは、そのパーティションの i ノードの数 (ファイルやディレクトリの最大の数) を減らします。 i ノードの数を減らすことで、クラッシュ後の .Xr fsck 8 による修復時間を大幅に減らすことができます。 本当にこのパーティションに大きなファイルを置くのでない限り、 このオプションを使わないでください。 空き領域が大量にあるのにファイルを収容できなくなるかもしれません。 bytes/inode は、32768 か 65536 か 262144 とすることが推奨されます。 もっと大きな値にすることができますが、 .Xr fsck 8 による修復時間を増やすだけでしょう。 例えば、 .Dq Li "newfs -i 32768 ..." のようにして値を与えます。 .Pp .Xr tunefs 8 はファイルシステムをさらにチューンするのに使えます。 このコマンドは、シングルユーザモードで実行することができ、 ファイルシステムの再フォーマットは不要です。 しかし、おそらく最も誤って使用されているプログラムでしょう。 多くの人はファイルシステムの利用可能な空き領域を増やそうとして、 min-free 比率を 0 に設定します。 これはファイルシステムの猛烈な断片化につながるので、推奨されません。 ここで、唯一本当に価値がある .Xr tunefs 8 のオプションは、 .Dq Li "tunefs -n enable /filesystem" として .Em softupdates を有効にすることです (注意: .Fx -5.x -では +4.5 以降では .Xr newfs 8 に .Fl U オプションを与えることで softupdates を有効に することができます)。 softupdates はメタデータの性能、 主にファイルの作成と削除の性能を劇的に改善します。 全てのファイルシステムで softupdates を有効にすることを推奨します。 softupdates に関して、2 つの欠点を意識すべきです。 1 つめは、softupdates はクラッシュ時における ファイルシステムの一貫性は保証しますが、 物理ディスクの更新が何秒か (1 分になることもあります!) 遅れる可能性が高いことです。 クラッシュした場合、より多くの成果が消えてしまうかもしれません。 2 つめは、softupdates はファイルシステムブロックを解放するのを遅らせる ということです。 あるファイルシステム (例えばルートファイルシステム) が満杯近くの時に それに対する大規模な更新、たとえば .Dq Li "make installworld" をすると、空き領域を使い果たして更新が失敗してしまうことがあります。 .Pp .Xr mount 8 実行時のいくつかのオプションはファイルシステムをチューンするのに役立ちます。 最も明らかで、しかも最も危険なのは .Cm async です。 これは決して使わないでください。 大変危険です。 比較的危険度が低く、より役に立つ .Xr mount 8 のオプションは .Cm noatime です。 通常 .Ux ファイルシステムは、ファイルやディレクトリにアクセスが あった場合は常に、その最終アクセス時刻を更新します。 .Fx では、この動作は遅延書き込みで行なわれ、 通常は大した負荷にはなりません。 しかし、大量のファイルが連続してアクセスされた場合、 バッファキャッシュがアクセス時刻の更新で汚染され 大きな負荷となります。 例えば、高負荷の web サイトや大量の読者を抱えるニューズサーバ では、この .Xr mount 8 のオプションで大きなパーティションにおける アクセス時刻の更新を停止することが考えられます。 根拠もなく、すべての場所でアクセス時刻の更新を停止しないでください。 例えば、 .Pa /var ファイルシステムは、慣習的にメールボックスを保持し、 新規メールのメールボックス中の有無判定に atime (および mtime) が使用されます。 読み込み専用パーティション、 .Pa / や .Pa /usr では、atime をオンにしておいた方が良いでしょう。 システムユーティリティには、atime フィールドを使用するものがあるので、 .Pa / では特に有用です。 .Sh ディスクのストライピング 大きなシステムでは、いくつかのドライブのパーティションを互いに ストライピングして、全体として巨大なパーティションを作ることもあります。 ストライピングは、入出力操作を複数のディスクに振り分けることで ファイルシステムの性能を向上させることができます。 .Xr vinum 8 および .Xr ccdconfig 8 ユーティリティは、シンプルなストライピングされたファイルシステムを 作るのに使われます。 一般に、ルートや .Pa /var/tmp のような小さなパーティション、 あるいは .Pa /usr のような本質的に読み込みのみのパーティションを ストライピングしても時間の無駄にしかなりません。 本当に入出力性能を必要とするパーティションのみをストライピングするべきです。 典型的には .Pa /var や .Pa /home あるいはデータベースや Web ページを 保持するカスタムパーティションです。 適切なストライプサイズを選ぶことも重要です。 ファイルシステムはメタデータを 2 の累乗の境界で格納する傾向にあり、 大抵はシークを増やすのではなく減らしたいでしょう。 これは、1152 セクタといったような、 シーケンシャルな I/O が両方のディスクをシークしないように、 かつメタデータが単一のディスクに集中するのではなく両方に分散するような、 中心を外れた (off-centered) 大きな ストライプサイズにしたい、ということを意味します。 本当に性能が必要なら、 .Fx がサポートする本物のハードウェア RAID コントローラを 使うことを勧めます。 .Sh sysctl によるチューニング .Xr sysctl 8 変数は、実行時に、システムの動作のモニタおよび制御を可能とします。 sysctl には、単にシステムの動作を報告するものもありますが、 システムの動作を変更するものもあります。 ブート時に .Xr rc.conf 5 を使用して設定可能なものもありますが、大部分は .Xr sysctl.conf 5 で設定可能です。 システムには数百の .Xr sysctl 8 変数が存在します。 そのなかには、チューニングの候補のように見えますが本当は そうでないものも多く含まれます。この文書では システムに最も大きな影響を与えるものだけを扱います。 .Pp .Va kern.ipc.shm_use_phys sysctl は、デフォルトが 0 (オフ) であり、 0 (オフ) または 1 (オン) にセットすることができます。 このパラメータを 1 にセットすると、全ての System V 共有メモリセグメントが ページング不可の物理メモリにマップされます。 これは、(A) 大量 (数百) のプロセス間で少量の共有メモリを マッピングしているか、(B) 任意個のプロセス間で大量の共有メモリを マッピングしている、のいずれかの場合に効果があります。 この機能は、共有メモリをスワップ不可にすることで、 共有メモリをコアに結び付ける時に生じる、 カーネルにおける内部のメモリ管理によるページ追跡 オーバヘッドをかなり減らします。 .Pp .Va vfs.vmiodirenable sysctl は、デフォルトは 0 (オフ) であり (しかし近いうちにデフォルトが 1 に なるでしょう)、0 (オフ) または 1 (オン) にセットすることができます。 このパラメータは、ディレクトリがシステムによってどのように キャッシュされるかを制御します。 ほとんどのディレクトリは小さく、 ファイルシステムにおいては単一フラグメント (典型的には 1K) であり、バッファキャッシュではさらに小さくなっています (典型的には 512 バイト)。 しかし、デフォルトモードで動作している時は、 大量のメモリを搭載していても バッファキャッシュは固定数のディレクトリしかキャッシュしません。 この sysctl をオンにすると、バッファキャッシュが VM ページキャッシュを、ディレクトリをキャッシュするために使うことを可能に します。 これによる利点は、全てのメモリがディレクトリを キャッシュするのに使えるようになるということです。 欠点は、キャッシュに使われる最小のメモリの大きさが 512 バイトではなく 物理ページサイズ (大抵は 4K) になることです。 メモリに制約があるシステムでは、 このオプションをオフにすることを推奨します。 一方、オンにすると、多数のファイルを操作するサービスの性能が向上します。 そのようなサービスには、web キャッシュや、大規模なメールシステム、 ニューズシステムなどが含まれます。このオプションは一般に メモリを消費しますが、性能を削減することはありません。 ただし実験して調べてみるべきでしょう。 .Pp バッファキャッシュと VM ページキャッシュに関連した、様々な sysctl が 存在します。 これらを変更することは推奨されません。 .Fx 4.3 について言えば、VM システムは自分自身のチューニングに関して大変良い 仕事をしています。 .Pp .Va net.inet.tcp.sendspace sysctl と .Va net.inet.tcp.recvspace sysctl は、ネットワークに関連するアプリケーションを 稼動している場合は特に重要です。これは、TCP コネクションの 送信および受信バッファ領域の大きさを調節します。 デフォルトでは、送信バッファは 32K で、受信バッファは 64K です。 このデフォルトを増やすことで 各コネクションについてカーネルメモリがさらに消費されますが、 帯域幅の利用率が改善することがあります。 同時に数百とか数千のコネクションを扱っている場合、 このデフォルトを増やすことは推奨されません。 失速してしまったコネクションが蓄積することで、 システムがメモリをすぐに使い果たしてしまうからです。 しかし、少ない数のコネクションについて広い帯域幅が必要ならば、 特にギガビットイーサネットの場合、このデフォルトを大幅に増やす ことができます。 入力データと出力データのバッファを個別に調整することができます。 たとえば、主に web サービスをしているマシンならば recvspace を 減らすことで、それほど大量にカーネルメモリを消費せずに sendspace を増やすことができます。 経路表 ( .Xr route 8 を参照 ) に対しては、経路に特化した送受信バッファを導入することが できるということに注意してください。 .Pp 付加的な管理ツールとして、ファイアウォールルールにおいて パイプ (pipe) を使うことで ( .Xr ipfw 8 を参照)、特定の IP ブロックやポートへ行く、あるいはそこから 来る帯域幅を制限することができます。 例えば T1 回線を持っている場合、 web トラフィックは回線の 70% に制限し、残りをメールと インタラクティブな用途に使いたいと思うでしょう。 通常高い負荷の web サーバは、ネットワーク回線が 使い切られていても、他のサービスに大きな遅延を与えることは ありませんが、制限をかけることは物事を円滑にし長期的な安定につながります。 また、多くの人が、帯域超過による課金をされないように 意図的な帯域制限をかけています。 .Pp .Va net.inet.tcp.rfc1323 sysctl で制御可能な TCP プロトコルのウィンドウスケーリング拡張を 両方のホストがサポートしない限り、 TCP の送信あるいは受信バッファサイズを 65535 を超えて指定しても ほとんど性能の改善はありません。 ある種のネットワークリンクから良い性能を引き出すために、 これらの拡張を有効にし、 TCP バッファサイズを 65536 より大きく設定すべきです。 特に、ギガビット WAN リンクや、高レイテンシの衛星リンクが対象となります。 RFC1323 サポートは、デフォルトでオンになっています。 .Pp .Va net.inet.tcp.always_keepalive sysctl はオン (1 にセット) にしてそのままにしておいてください。 デフォルトは大抵オフです。少量のネットワーク帯域を消費しますが、 偶然死んでしまった TCP コネクションを認識し除去することを保証します。 死んでしまった TCP コネクションは、特にダイアルアップのユーザによりアクセス されるシステムで発生する問題です。 ユーザは、しばしば正しくアクティブコネクションを閉じずにモデムを切断 するからです。 .Pp .Va kern.ipc.somaxconn sysctl は、新しい TCP コネクションを受け付けるための listen キューの サイズを制限します。高負荷の web サーバ環境では、 デフォルト値の 128 は新しいコネクションを余裕をもって扱うには低すぎます。 そのような環境では、この値を 1024 以上に増やすことが推奨されます。 サービスデーモン (例えば .Xr sendmail 8 や apache) は自分自身の listen キューのサイズを制限しているかもしれませんが、設定ファイルで キューのサイズを増やすディレクティブを持つようになるでしょう。 listen キューを大きくすることは、サービス拒否攻撃を防ぐのにも役立ちます。 .Pp .Va kern.maxfiles sysctl は、システムがどれだけの数のファイルをオープンできるかを 決めます。デフォルトは典型的には数千ですが、データベースや記述子を 大量に使うデーモンを稼働している場合は 10000 や 20000 に引き上げる必要 があるかもしれません。 読み込み専用の .Va kern.openfiles sysctl を検査することで、システム上で開かれているファイル数を判定可能です。 .Pp .Va vm.swap_idle_enabled sysctl は、多数のユーザがシステムに出入りして大量のアイドルプロセスが ある大きなマルチユーザシステムで便利です。 そのようなシステムでは、フリーメモリの予約に対し、 継続して重大な負担をかける傾向にあります。これをオンにして .Va vm.swap_idle_threshold1 sysctl と .Va vm.swap_idle_threshold2 sysctl でスワップアウトヒステリシス (アイドルの秒数) を調整することで アイドルプロセスに与えられているページの優先度を通常のページアウト アルゴリズムよりも速やかに下げることができます。 これはページアウトデーモンを手助けします。必要がないかぎり、 このオプションはオンにしないでください。 これによって起こるトレードオフは、本質的に、 スワップとディスク帯域幅をより多く消費してメモリのプリページングを より早いうちに行うことだからです。 小さなシステムではこのオプションは有害となるでしょうが、 すでにある程度ページングが発生している大きなシステムでは、 このオプションによって、全体のプロセスがより容易にメモリへ入ったり 出たりするようにできるでしょう。 .Sh ローダのチューナブル システムの動作の一部は、 そのためのメモリ割り当てをブート処理の初期に行う必要があるために、 実行時には調整不可能です。 ローダのチューナブルを変更するには、これらの値を .Xr loader.conf 5 に設定し、システムをリブートする必要があります。 .Pp .Va kern.maxusers は、静的なシステムテーブルの大きさを制御します。 これには、 オープンファイルの最大数、ネットワークメモリ資源の大きさ等が含まれます。 .Fx 4.5 の時点では、 .Va kern.maxusers は、ブート時に、システムで利用可能なメモリ量に応じて、 大きさが自動的に決定されます。 また、実行時に、読み取り専用の .Va kern.maxusers sysctl 値を見て決定することも可能です。 サイトによっては、 .Va kern.maxusers を大きくしたり小さくしたりする必要があり、 これはローダチューナブルで設定可能です。 64, 128, 256 は、変な値ではありません。 膨大なファイル記述子が必要なのでない限り、 256 より大きくすることは勧められません。 .Va kern.maxusers によってデフォルト値が決定される多くのチューナブル値は、 本文書の別の場所に記述した方法で、 個々にブート時または実行時に上書き可能です。 .Fx 4.4 より古いシステムでは、 カーネルの .Xr config 8 オプションの .Cd maxusers を設定する必要があります。 .Pp .Va kern.ipc.nmbclusters を調整することで、システムが割り当てようとしている ネットワーク mbuf の数を増やすことができます。 それぞれのクラスタは約 2K のメモリに相当するので、 1024 は 2M のカーネルメモリをネットワークバッファに 予約することを示します。 簡単な計算でどれだけ必要なのかがわかります。 web サーバが同時に最大 1000 本のコネクションを扱い、 各コネクションが 16K の受信バッファと 16K の送信バッファを消費する場合、 約 32MB に相当するネットワークバッファを扱う必要があります。 経験から得た方法によると、2 倍すると良いとされています。 つまり 32MBx2 = 64MB/2K = 32768 です。 したがって、この場合は .Va kern.ipc.nmbclusters を 32768 に設定します。 中くらいの量のメモリが搭載されたマシンでは 1024 から 4096、 さらに大量のメモリが搭載されているなら 4096 から 32768 の値を 推奨します。 決して大きい値を指定すべきではありません。 ブート時にクラッシュを引き起こす可能性があります。 .Xr netstat 1 に .Fl m オプションを与えることで、ネットワーククラスタの使用状況が分かります。 古い .Fx ではこのチューナブルを持ちませんので、 代りにカーネルの .Xr config 8 オプションの .Dv NMBCLUSTERS を設定する必要があります。 .Pp ますます多くのプログラムが .Xr sendfile 2 システムコールを使ってネットワークを通じてファイルを 転送しています。 .Va kern.ipc.nsfbufs sysctl は .Xr sendfile 2 の実行時にファイルシステムバッファをどれだけの数だけ 使えるかを制御します。 通常このパラメータは .Va kern.maxusers に比例しているので、極端な場合を除いては このパラメータに手を出す必要はありません。 .Sh カーネル構成におけるチューニング 大規模なシステムでは、いくつかのカーネルオプションを操作しなければ ならないかもしれません。これらのオプションを変更する場合、あなたは ソースから新しいカーネルをコンパイルできなければなりません。 .Xr config 8 マニュアルページやハンドブックが良い入門となるでしょう。 あなただけのカスタムカーネルを作るときに一般に最初にすることは、 使用しないドライバやサービスをすべて削ることです。 .Dv INET6 や使わないドライバを削除することで、カーネルのサイズを時に 1 メガバイト以上減らすことができ、アプリケーションにさらに メモリを与えることができます。 .Pp .Dv SCSI_DELAY と .Dv IDE_DELAY は、システムの起動時間を減らすために使うことができます。 このデフォルト値はかなり大きく、ブート処理の中で 15 秒以上を占めるでしょう。 .Dv SCSI_DELAY を 5 秒に減らしても大抵はうまく動きます (特に最近のドライブでは)。 .Dv IDE_DELAY を減らしてもうまくいきますが、少々慎重になる必要があります。 .Pp .Dv *_CPU オプションの多くはコメントアウトできます。 そのカーネルを Pentium クラスの CPU だけで動かすなら、 .Dv I386_CPU と .Dv I486_CPU は削除することができます。ただし、 .Dv I586_CPU は、CPU が Pentium II 以上として認識されることを確認してから 削除してください。Pentium や 486 としてさえ認識されるクローンが存在し、 その場合はこれらのオプションがないと起動することができません。 もし動いたらすごいことです ! オペレーティングシステムは、MMU や タスク切り替え、タイムベース、デバイス操作に至る、より高度な機能を より利用することができるようになります。 加えてより高度な CPU は、カーネルがカーネル自身をメモリにマップする 4MB の MMU ページをサポートします。これは高いシステムコール負荷の 下での効率を上げます。 .Sh IDE ライトキャッシュ .Fx 4.3 では IDE のライトキャッシュがオフになりました。これは IDE ディスクへの書き込み帯域幅を減らしてしまうことになりますが、 ハードドライブベンダに起因するデータの一貫性に関する重大な問題のために、 必要なことだと考えられました。 基本的には、書き込み完了時期について IDE ドライブが嘘をつくという問題です。 IDE ライトキャッシュがオンであると、 IDE ハードドライブはデータを順番に書きこまないばかりか、 ディスクの負荷が高い時にはいくつかのブロックの書き込みを 無期限に延期してしまいます。 クラッシュや電源故障の場合、ファイルシステムの重大な破壊を もたらします。したがって私たちはデフォルトを安全側に変更しました。 残念ながら、これは大変な性能の低下をもたらし、私たちはあきらめて このリリース後にオンに戻しました。 .Va hw.ata.wc sysctl 変数を見て、デフォルトをチェックしてみるべきです。 もし IDE ライトキャッシュがオフになっていたら、 .Va hw.ata.wc ローダチューナブルを 1 に設定することでオンに戻すことができます。 ATA ドライバシステムのチューニングに関する更なる情報は、 .Xr ata 4 を参照してください。 .Pp IDE ハードドライブの実験的な新機能として、 .Va hw.ata.tags と呼ばれるものがあり (これもブートローダで設定します)、 ライトキャッシュを安全にオンにすることができます。 これは SCSI のタギング機能を IDE ドライブに持ち込んだものです。 これを書いている時点では、IBM DPLA と DTLA ドライブだけがこの機能を サポートしています。 警告! これらのドライブは品質管理に問題 があるようなので、私は現時点ではこれらの製品を買うことはおすすめしません。 性能が必要なら SCSI を使いましょう。 .Sh CPU、メモリ、ディスク、ネットワーク 負荷が上がるとシステムのどの部分がボトルネックになりはじめているかによって、 チューニングの種類が違ってきます。 CPU を使い果たしている (アイドル時間が常に 0%) ならば、CPU を アップグレードしたり SMP マザーボード (CPU を複数にする) に移行 したり、あるいは負荷の原因となっているプログラムを見直して最適化する ことを考える必要があるでしょう。 スワップに対して大量のページングがあるなら メモリをもっと増やす必要があるでしょう。 ディスク性能が飽和している場合、CPU アイドル時間は高く、全般的に ディスクが飽和状態になっています。 .Xr systat 1 でこれらをモニタすることができます。 ディスク性能の飽和を解決するにはいろいろな方法があります: キャッシュのためのメモリを増やす、ディスクをミラーリングする、 複数のマシンに操作を分散させる等です。 ディスク性能が問題で、IDE ドライブを使っている場合、 SCSI に切り替えることでずいぶんよくなります。 生のシーケンシャルな帯域幅については、最近の IDE ドライブは SCSI のものに 匹敵していますが、調べると大抵 SCSI ドライブが勝っています。 .Pp 最後に、ネットワーク性能を使い果たしているかもしれません。 ネットワーク性能を改善するために最初に確認すべきことは、 ハブではなくスイッチを使っているか、ということです。 特に最近はスイッチは安くなっています。 ハブが高負荷になると、コリジョンバックオフのために深刻な問題が発生します。 また、1 台のホストに問題があると、LAN 全体の性能を大幅に低下させます。 次に、できるだけネットワーク経路を最適化することです。 例えば .Xr firewall 7 で説明した内部ホストを守るファイアウォールでは、 外部から見えるホストはファイアウォールを通さないトポロジです。 必要に応じて 10BaseT ではなく 100Base-T を、あるいは 100BaseT ではなく 1000BaseT を使いましょう。 最大のボトルネックは WAN 回線です (モデム、T1、DSL 等)。 回線を増強できないのであれば、 .Xr dummynet 4 機能を使ってピーク削減やその他のトラフィックシェイピングを 行い過負荷のサービス (web サービス等) が他のサービス (電子メール等) に影響を与えるのを防いでください。逆もまた同様です。 これは、家庭環境において、外部に公開しているサービス (web サービスや電子メール) よりも インタラクティブなトラフィック (ブラウザや .Xr ssh 1 ログイン) を 優先するために使うことができるでしょう。 .Sh 関連項目 .Xr netstat 1 , .Xr systat 1 , .Xr ata 4 , .Xr dummynet 4 , .Xr login.conf 5 , .Xr rc.conf 5 , .Xr sysctl.conf 5 , .Xr firewall 7 , .Xr hier 7 , .Xr ports 7 , .Xr boot 8 , .Xr ccdconfig 8 , .Xr config 8 , .Xr disklabel 8 , .Xr fsck 8 , .Xr ifconfig 8 , .Xr ipfw 8 , .Xr loader 8 , .Xr mount 8 , .Xr newfs 8 , .Xr route 8 , .Xr sysctl 8 , .Xr tunefs 8 , .Xr vinum 8 .Sh 歴史 .Nm マニュアルページは、もともと .An Matthew Dillon によって書かれました。最初に登場したのは .Fx 4.3 で、2001 年 5 月のことです。 diff --git a/ja_JP.eucJP/man/man9/at_fork.9 b/ja_JP.eucJP/man/man9/at_fork.9 index fe07ff4acd..fade5f5cfd 100644 --- a/ja_JP.eucJP/man/man9/at_fork.9 +++ b/ja_JP.eucJP/man/man9/at_fork.9 @@ -1,79 +1,79 @@ .\" .\" Copyright (c) 1996 Julian Elischer .\" .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" %FreeBSD: src/share/man/man9/at_fork.9,v 1.9.2.6 2001/12/17 11:30:18 ru Exp % +.\" %FreeBSD: src/share/man/man9/at_fork.9,v 1.9.2.7 2002/01/10 09:36:27 ru Exp % .\" " .\" $FreeBSD$ .Dd August 15, 1996 .Os .Dt AT_FORK 9 .Sh 名称 .Nm at_fork , .Nm rm_at_fork .Nd fork 時に実行される関数の問合せ .Sh 書式 .In sys/types.h .In sys/systm.h -.Ft "typedef void" ( *forklist_fn ) -.Fa ( "struct proc*" , "struct proc*" , int ) ; +.Ft "typedef void" +.Fn \*[lp]*forklist_fn\*[rp] "struct proc *" "struct proc *" int .Pp .Ft int .Fn at_fork "forklist_fn func" .Ft int .Fn rm_at_fork "forklist_fn func" .Sh 解説 .Nm の仕組みは、あらゆるプロセスの fork 時に、 そのことがカーネルモジュールに通知されることを保証します。 関数 .Fa func は、fork しようとしているプロセスの proc 構造体へのポインタ、 子プロセスの構造体へのポインタおよび .Xr rfork 2 で使用される fork の型を示すフラグを引数として呼び出されます。 .Pp 通知に対する必要条件が取り除かれた場合、 .Fn at_fork の呼び出しと正確に一致引数 .Fa func をとって関数 .Fn rm_at_fork を呼び出さなければなりません。 .Sh 戻り値 .Fn at_fork は errno を返し、0 は成功を意味します。 .Fn rm_at_fork は関数は、削除された項目の個数 (0 または 1 であるべきです) を返します。 .Sh 関連項目 .Xr fork 2 .Sh 歴史 .Fn at_fork 関数は .Fx 2.2 で登場しました。 .Sh 作者 この関数は .An Julian Elischer Aq julian@FreeBSD.org が書きました。