DUMPKEYMAP(1)

名前
dumpkeymap - .keymapping ファイルを診断用にダンプする

書式
dumpkeymap [options] [-] [file...]

説明
dumpkeymap は、コマンド行で指定された Apple/NeXT の .keymapping ファイルの内容をテキスト表現で出力する。 ファイルが指定されておらず、かつローカルマシンで Apple または NeXT が動作している場合には、WindowServer や AppKit が現在使用している キー割り当てが出力される。

オプション

-h --help
    プログラムの概要とオプションのまとめを表示する。

-k --help-keymapping
    .keymapping ファイルが初期状態で持っている配置の詳しい説明を表示する。 これと同じ内容は、このマニュアルページの「キー割り当てについての説明」 の節に載っている。

-o --help-output
    .keymapping ファイルを分割したときに dumpkeymap が生成する出力の説明を表示する。 これと同じ内容は、このマニュアルページの「出力についての説明」 の節に載っている。

-f --help-files
    キー割り当てに関係する各種ファイルおよびディレクトリのまとめを表示する。 これと同じ内容は、このマニュアルページの「ファイル」の節に載っている。

-d --help-diagnostics
    dumpkeymap が出力するエラーメッセージの一覧を表示する。 これと同じ内容は、このマニュアルページの「診断」の節に載っている。

-v --version
    dumpkeymap のバージョン番号と保証に関する情報を表示する。

- --
    引き数リストのオプション処理をその時点で止める。 引き数リストに `-' や `--' が現われると、それ以降の引き数は たとえ `-' で始まっていてもファイル名として扱われる。

キー割り当てについての説明
以降の節では、キー割り当てリソースの生のフォーマットと ひとつ以上の生の割り当てを内包する .keymapping ファイルのフォーマットを詳細に説明する。

型とデータ
ここでの説明では、次の型定義をずっと使用する:

これに加えて、一般的な数値を表すために型定義 `number' を使う。 `number' 型の実際の大きさは 1 バイトまたは 2 バイトであり、この大きさは キー割り当てへのデータの格納のしかたによって変わる。 ほとんどのキー割り当てでは byte サイズの数値を使うが、word サイズの 値も利用できる。

キー割り当てファイルにマルチバイトの値が格納される場合、 バイト順はビッグエンディアンである。

キー割り当てファイルとデバイス割り当て
キー割り当てファイルはマジックナンバーで始まり、その後に デバイス固有のキー割り当てを示す変数が続く。

`interface' の値はキーボードデバイスの種類を表す( Intel PC, ADB, NeXT, Sun Type5 等)。これらは普通、 NX_EVS_DEVICE_INTERFACE_ADB, NX_EVS_DEVICE_INTERFACE_ACE, などの定数から選んで指定される。これらの定数は、MacOS/X と Darwin では IOHIDTypes.h で定義されており、MacOS/X Server や OpenStep, NextStep では ev_types.h で定義されている。

`handler_id' の値は、`interface' が含む範囲の中から特定の キーボード配置を示す。 例えば、Intel PC 用の 101 キーボード( NX_EVS_DEVICE_INTERFACE_ACE 型)は、`handler_id' は `0' である。 102 キーボードの場合には、この値は `1' である。

`interface' と `handler_id' の組合せにより、この割り当てが適用される キーボードのハードウェアを厳密に指定できる。 キーボード配置をビジュアル的に表示するプログラムでは、 .keymapping ファイルに書かれている `interface' および `handler_id' と、 各々の .keyboard ファイルに書かれている `interface' および `handler_id' の値を 比べてキーボードを特定すること。

キー割り当てについての説明
キー割り当ては、全てのスキャンコードとそれに割り当てられる機能を 完全に定義する。 KeyMapping 構造体は、 KeyMappingFile の中の DeviceMapping 構造体に持たされる。 WindowServer と AppKit が使用中のキー割り当ては、 KeyMapping 構造体によっても示される。 また、直接 NXGetKeyMapping() を呼び、この関数が返す NXKeyMapping 構造体の `mapping' メンバとしても参照できる。

`number_size' は，残りのすべての数値(キー割り当て内の `number' 型定義で示される)の大きさをバイト単位で示す。 この値が 0 の場合は、残りの数値は各 1 バイトずつで表される。 0 でない場合は、残りの数値はそれぞれ 1 ワード(2 バイト)ずつで表される。

修飾子グループ
修飾子グループは、スキャンコードは修飾子の型( shift, control など)にマップされる全ての スキャンコードを定義する。

配列 scan_codes[] には、指定された修飾子にマップされる全ての スキャンコードの一覧が格納される。 shift, command, alternate などの修飾子は、ふたつの異なるスキャンコードに別々にマップされる ことが多い。 なぜなら、これらの修飾子はキーボードの右側と左側の両方にあることが 多いからである。

スキャングループ
指定されたキーボードが生成する各々のスキャンコードに対してひとつの ScanGroup が存在する。 この個数は KeyMapping::num_scan_codes で得られる。 最初のスキャングループはハードウェアのスキャンコード 0 を表し、 次のスキャングループはスキャンコード 1 を表す。以降も同様である。

各スキャンコードについて、どの修飾子との組合せで文字が生成されるのかが `mask' によって定義される。 `mask' が NOT_BOUND (0xff)ならば、このスキャンコードは文字をまったく生成せず、 characters[] 配列の長さは 0 となる。 それ以外の場合には、それぞれの修飾子との組合せに対してひとつの Character レコードが characters[] 配列に格納される。

characters[] に格納されているレコードの数は (1 << bits_set_in_mask) の計算で求められる。 つまり、mask が 0 ならば 0 個のビットが設定され、したがって characters[] にはレコードがひとつしか含まれない。 `mask' が (SHIFT_MASK | CONTROL_MASK), ならばふたつのビットが設定されるので、characters[] には 4 つの レコードが含まれる。

最初のレコードは常に、どの修飾子も有効でない時にそのキーが生成する 文字を表す。 残りのレコードは、各種の修飾子と組み合わせた際に生成される文字を 表す。 shift マスクと control マスクが設定されている例を用いると、レコード 2 は shift 修飾子が有効な場合の文字を表し、レコード 3 は control 修飾子が有効な場合の文字を表し、レコード 4 は shift 修飾子と control 修飾子の両方が有効な場合の文字を表す。

特殊な場合として、 ALPHALOCK_MASK は SHIFT_MASK を表す。 ただし、 ALPHALOCK_MASK は `mask' にしか現われない。 この場合には、 shift 修飾子と alpha-lock 修飾子では同じ文字が生成されるが、characters[] 配列には一回だけ出てく ればよい。

CARRIAGE_RETURN_MASK は実際には修飾キーを表していない。 このマスクは、 キャッリッジリターン(復帰) キーの特殊な仮想記号で与えられるスキャンコードを示すために使われる。 普通、このマスクは ScanGroup レコード中に単独で現われ、その後には Character レコードとして Ctrl-M と Ctrl-C のふたつだけが置かれる。 このフラグは時間的に前の状態を持っていたり、低レベルのキーボードドライバ が特殊な扱いをしたりすることがあるが、それ以外の用途は謎である。

文字
それぞれの Character レコードは、このキーが押されたときに生成される文字を示す。 また、その文字を含む文字集合を示す。 よく知られた文字集合としては `ASCII' や `Symbol' がある。 文字集合は、 FUNCTION_KEY や KEY_SEQUENCE といったメタ値を取ることもある。 FUNCTION_KEY の場合、普通 `char_code' は FunctionKey として番号が付いている、おなじみのファンクションキーを表す。 文字集合が KEY_SEQUENCE の場合、`char_code' は KeyMapping::sequence_lists[] のインデックス を表す。インデックスは 0 から始まる。

シーケンス
Character::set がメタ値 KEY_SEQUENCE を含む場合、そのスキャンコードにはひとつの文字でなく、キーの列が割り当てられる。 この列は、割り当てられたキーが離されたときに自動的に生成される修飾子と 文字が並べたものである。

生成されるそれぞれの文字については前に説明した通りであるが、 KEY_SEQUENCE の代わりに MODIFIER_KEY が使われることがある点が例外である。 Character::set の値が MODIFIER_KEY の時は、Character::char_code は実際の文字ではなく修飾キーを表す。 `char_code' が表す修飾子が 0 でない場合は、対応する修飾キーが 押されていることを示す。この場合、値は Modifier に挙げられている定数 (SHIFT, CONTROL, ALTERNATE, 等)のどれかになる。 この値が 0 の場合は、修飾キーが離されていることを表す。

特殊キー
特殊キーは、WindowServer でなく Mach カーネルが直接スキャンするキーで ある。 特殊キーに対するイベントは普通は生成されない。

出力
この章では、 dumpkeymap が出力する各種情報について説明する。

ここで説明する個々の情報に関する詳細な説明については、 前述の「キー割り当てについての説明」の章で述べられている、 キー割り当ての内部レイアウトに詳しい説明を参照すること。

表記に関する約束ごと
状況によって、数値表示は 10 進表記になることもあるし、16 進表記に なることもある。 16 進の数値の前には `0x' が書かれる(例: `0x7b')。 ただし、そうでないと明示的に書かれている場合は除く。

キー割り当てのソース
あるキー割り当てについて最初に表示される情報は、データの取り込み元となった ソースについてである。 .keymapping ファイルの場合には、タイトルは `KEYMAP FILE' となり、同時に対象ファイルのパスおよび名前が出力される。 WindowServer や AppKit が現在使用中のキー割り当ての場合には、 タイトルは `ACTIVE KEYMAP' となる。

デバイス情報
各々の .keymapping にはひとつ以上の生のキー割り当てが書かれている。 例えば、キー割り当てを Dvorak 配列にするファイルには、Intel PC, ADB, NeXT, Sun Type5 キーボードの生の割り当てが書かれていることがある。

生の割り当てのそれぞれに対して、次の情報が出力される: タイトル `KEYMAP' および、 .keymapping ファイル内における割り当ての相対位置。 `interface' 識別子。 `handler_id' 副識別子。 生の割り当てリソースのバイト単位での大きさ。 `interface' と `handler_id' は対になり、特定のキーボードデバイスを 定義する。 .keyboard ファイル(キーボードの見ためでの配列を定義する)にも `interface' 識別子 と `handler_id' 副識別子が書かれている。 特定のキー割り当てに対応する .keyboard ファイルは、それぞれのリソースから `interface' と `handler_id' の値が 一致するものを探すことで見つけられる。

修飾子
それぞれの割り当ては 0 個以上の修飾子レコードを持つことができる。 この修飾子レコードは、ハードウェアのスキャンコードと修飾子の内容( shift, control, alternate 等)を対応付ける。 それぞれの修飾子レコードについて、修飾子の名前とともに 修飾子の値を生成するスキャンコードの一覧(16 進形式)が表示される。 例を以下に挙げる:

    MODIFIERS [4]
    alternate: 0x1d 0x60
    control: 0x3a
    keypad: 0x52 0x53 ... 0x63 0x62
    shift: 0x2a 0x36

文字
それぞれの割り当ては 0 個以上の文字レコードを持つことができる。 この文字レコードはハードウェアのスキャンコードと、各種修飾キーとの 組合せがある場合やない場合にそのスキャンコードから実際に生成される 実際の文字を対応付ける。 タイトル `CHARACTERS' の後には、その後に続く文字レコードの数が表示される。 以下に大幅に省略した形の例を挙げる:

    CHARACTERS [9]
    scan 0x00: -AC-L  "a" "A" "^A" "^A" ca c7 "^A" "^A"
    scan 0x07: -AC-L  "x" "X" "^X" "^X" 01/b4 01/ce "^X" "^X"
    scan 0x0a: ---S-  "<" ">"
    scan 0x13: -ACS-  "2" "@" "^@" "^@" b2 b3 "^@" "^@"
    scan 0x24: R----  "^M" "^C"
    scan 0x3e: -----  [F4]
    scan 0x4a: -----  [page up]
    scan 0x60: -----  {seq#3}
    scan 0x68: not-bound

それぞれのレコードについて、まずハードウェアのスキャンコードの値が 16 進形式で表示され、その後に修飾フラグの組合せの一覧が表示され、最後に このスキャンコードと修飾子の各種組み合わせで生成される実際の文字が 表示される。

修飾フラグのフィールドは、各種の修飾子を一文字で表したものを組み合わせ て作られている。 それぞれの文字は以下のような意味を持つ:

    L - alpha-lock
    S - shift
    C - control
    A - alternate
    R - carriage-return

特別な場合として、 alpha-lock フラグが立っている場合は shift も立っていると見なされる。したがって、ひとつのレコードで両方のフラグが 同時に立つことはない。

修飾フラグの組み合わせにより、その後に続くフィールドの意味と数が決まる。 修飾フラグのすぐ後のフィールドは、修飾キーがどれも押されていない場合に 生成される文字を必ず表す。 残りのフィールドは、各種修飾キーと組み合わせたときに生成される文字を 表す。 フィールドの順序は、以下に示すパターンに従う: 修飾キーの影響がないときにこのスキャンコードが生成する文字は、 最初に示される。 `L' フラグまたは `S' フラグが有効ならば、このスキャンコードが生成する shift 修飾された文字が次に示される。 `C' フラグが有効ならば、このスキャンコードが生成する control 修飾された文字が次に示される。 さらに `L' フラグまたは `S' フラグも同時に有効ならば、shift と control の両方で修飾された文字がその次に示される。 `A' フラグが有効ならば、このスキャンコードが生成する alternate 修飾された文字が次に示される。 さらに `L' フラグまたは `S' フラグも同時に有効ならば、shift と alternate の両方で修飾された文字がその次に示される。 さらに `C' フラグも有効ならば、shift と control の両方で修飾された文字 がその次に示される。 最後に、`C' フラグと `L' フラグも同時に有効か、または `C' フラグと `S' フラグも同時に有効な場合には、shift, alternate, control で修飾された 文字が示される。 `R' フラグは実際には修飾キーを表していない。 このフラグは、特別な仮想記号 キャッリッジリターン(復帰) で与えられるスキャンコードを識別するために使われる。 普通は、このマスクは単独で現われ、その後には control-M と control-C の ふたつのフィールドしか続かない。 このフラグは時間的に前の状態を持っていたり、低レベルのキーボードドライバ が特殊な扱いをしたりすることがあるが、それ以外の用途は謎である。

前述の例について、各フィールドを次のように識別できる:

    scan 0x00: -AC-L  "a" "A" "^A" "^A" ca c7 "^A" "^A"
小文字の `a' は、修飾キーがどれもアクティブでないときに生成される。 大文字の `A' は shift または alpha-lock が有効なときに生成される。 Control-A は control が有効なときに生成される。 Control-A は control かつ shift が有効なときに生成される。 16 進コード 0xca で表される文字は、 alternate が有効なときに生成される。 0xc7 が表す文字は、 alternate と shift (または alpha-lock) が有効なときに生成される。 Control-A は、 alternate と control が有効なときに生成される。 Control-A は、 alternate, control と shift (または alpha-lock) が有効なときに生成される。 生成される特定の文字を表すために使う記法はいろいろある。 印字可能な ASCII 文字は二重引用符で括られる(例: "x" や "X")。 制御文字は二重引用符で括られ、前に "^" が付けられる(例: "^X")。 127 (0x7f) よりも大きい文字は、頭に `0x' を付けない 16 進数値として 表示される。 ASCII でない文字集合(`Symbol' など)に含まれる文字は、ふたつの 16 進数値を スラッシュ区切りで並べて表示される(例: `01/4a')。 前の数値はその文字集合の識別コード(例: `01' は `Symbol' 文字集合を表 す)であり、後ろの数値は生成される文字の値である。 印字可能でない特殊機能文字は、機能の一般名称をブラケットで括って表示さ れる(例: `[page up]' や `[F4]')。 割り当てがひとつの文字でなく、キーシーケンスを表している場合は、 そのシーケンスの識別番号をブレースで括って表示される(例: `{seq#3}')。 前述の例のいくつかについて、以下のように解釈を行える:

    scan 0x07: -AC-L  "x" "X" "^X" "^X" 01/b4 01/ce "^X" "^X"
    scan 0x3e: -----  [F4]
    scan 0x4a: -----  [page up]
    scan 0x60: -----  {seq#3}
"x" と "X" は印字可能な ASCII 文字である。 "^X" は制御文字である。 `01/b4' と `01/ce' は、`Symbol' 文字集合に含まれる文字コード 0xb4 と 0xce の文字を表す。 スキャンコード 0x3e はファンクションキー `F4' を生成する。 スキャンコード 0x4a はファンクションキー `page up' を生成する。 スキャンコード 0x60 はキーシーケンス #3 に割り当てられている。 最後に、あるスキャンコードがどの文字にも割り当てられていない場合には、 そのコードには `not-bound (割り当てなし)' という注釈が付けられる。 上記の例においてはスキャンコード 0x68 がそうなっている。

シーケンス
スキャンコード(修飾されているものもそうでないものも)には、 ひとつの文字の生成や修飾キーとしての動作だけでなく、キーシーケンスに 割り当てることができる。 キーシーケンスに割り当てた場合は、ひとつのキーストロークでなく、 文字の並びの呼び出しと修飾キーの動作が自動的に生成される。

それぞれの割り当てにおいては、0 個以上のキーシーケンスレコードを設定で きる。 タイトル `SEQUENCES' には、後に続くシーケンスレコードの個数が一緒に表示される。 例:

    SEQUENCES [3]
    sequence 0: "f" "o" "o"
    sequence 1: {alternate} "b" "a" "r" {unmodify}
    sequence 2: [home] "b" "a" "z"

生成される文字の並びを表すために使われる記法は、前述の「 文字 」の章で説明した記法と同じである。ただし、生成される文字と文字の間に 修飾キーの動作を挟んでもよい点が異なる。 このような修飾キーの動作は、修飾キーの名前をブレースで括って表す。 特殊な名前「{unmodify}」は、修飾キーが離されたことを表す。

上記の例のシーケンスは、次のように解釈できる: シーケンス #0 は `foo' を生成する。 シーケンス #1 は、まず alternate 修飾子を生成し、次に `bar' を生成し、それから alternate を離す。 シーケンス #2 は home まずキーを呼び出し、次に `baz' を生成する。 テキストエディタでは大抵、このシーケンスはカーソルのある行の先頭に `baz' を書き込む。

特殊キー
キーボードによっては、文字を生成したり、修飾キーとして動作するのでは なく、何か特殊な目的の機能を果たすキーが付いている。 例えば Apple のキーボードには、 power キーが付いていることが多いし、歴史的には NeXT のキーボードには画面の明るさや音量制御のキーが付いていた。

各々の割り当ては 0 個以上の特殊キーのレコードを持つことできる。 この特殊キーのレコードは、そういった特殊な目的の機能とハードウェア のスキャンコードを結びつける。 タイトル `SPECIALS' の表示の後ろには、後に続くレコードの数が表示される。 それぞれのレコードについて、特殊機能の名前と、その機能に割り当てられて いるスキャンコード(16進表記)の一覧が順に表示される。 例を以下に示す:

    SPECIALS [6]
    alpha-lock: 0x39
    brightness-down: 0x79
    brightness-up: 0x74
    power: 0x7f
    sound-down: 0x77
    sound-up: 0x73

ファイル

*.keymapping
    キー割り当てファイル。 このファイルは、ハードウェア固有の全てのスキャンコードとそれに 割り当てられた機能の対応を厳密に定義する。

*.keyboard
    ある型のキーボードのキーの物理的なレイアウトを記述するファイル。 このファイルに書かれたそれぞれの `key' トークンは、そのキーの キーボード上における位置と形状を定義する。また、そのキーが 生成するものとして割り当てられたスキャンコードも定義する。 一方、 .keymapping ファイルは、特定のスキャンコードが生成する文字を定義する。 この文字は各種修飾キー( shift, control 等)の状態によって変化する。 .keymapping ファイルから取り出した `interface' の値と `handler_id' の値は .keyboard ファイルから取り出した `interface' の値と `handler_id' の値と一致するかどうか調べられ、 その結果により特定の .keyboard ファイルとキー割り当てが対応付けられる。 各種 GUI プログラムが .keyboard ファイルを使い、ユーザにキーボードを視覚的に見せている。 .keyboard ファイルは単なるプレーンテキストなので、特殊なプログラムが なくても簡単に読んだり理解できる。したがって、 dumpkeymap はこれらのファイルをそのままにしている。

/System/Library/Keyboards
/Network/Library/Keyboards
/Local/Library/Keyboards
/Library/Keyboards
    MacOS/X, Darwin, MacOS/X Server における .keymapping ファイルと .keyboard ファイルの置き場所。

/NextLibrary/Keyboards
/LocalLibrary/Keyboards
    OpenStep と NextStep における .keymapping ファイルと .keyboard ファイルの置き場所。

$(HOME)/Library/Keyboards
    個人用の .keymapping ファイルと .keyboard ファイルの置き場所。

診断
以下に示す診断メッセージは標準エラー出力に出力される。 解釈できないオプションがコマンド行で指定された。 指定可能なオプションの一覧を見るには、 --help オプションを指定して dumpkeymap を実行すること。 キー割り当てファイルまたはデータストリームが壊れている。 ファイルが不正に途切れているか、あるフィールド(例えば後に続く可変 レコードの数を示すフィールド)の値が壊れている。

以下に示す診断メッセージは、 コマンド行で指定された .keymapping ファイルを表示しようとしているときにしか意味を持たない。 指定されたファイルが .keymapping ファイルでない。 ファイルの中身が文字列 `KYM1' で始まっていない。 fopen() の呼び出しに失敗した。 この場合の原因はおそらく、指定されたパスが間違っているか、 ファイルを読む権限を dumpkeymap が持っていないかである。 fstat() の呼び出しに失敗した。 したがって、ファイルをロードするためのメモリも割り当てることができない。 fread() の呼び出しに失敗した。

以下の診断メッセージは、 .keymapping ファイルがコマンド行では指定されず、現在有効なキー割り当て を出力しようとしているときにしか意味を持たない。 NXOpenEventStatus() の呼び出しに失敗した。 NXKeyMappingLength() の呼び出しによって返された値がおかしい。 NXGetKeyMapping() の呼び出しに失敗した。

以下の診断メッセージは、Apple 以外のプラットフォーム/NeXT プラットフォーム上で dumpkeymap を実行したときにしか意味を持たない。 .keymapping がコマンド行で指定されていない。 Apple 以外のプラットフォーム/NeXT プラットフォームには「現在有効な .keymapping ファイル」という概念がないので、コマンド行では 少なくともひとつのファイルを指定しなければならない。

作者
Eric Sunshine <sunshine@sunshineco.com> が dumpkeymap とこの文書( dumpkeymap user's manual. )を書いた。 dumpkeymap とこの文書は Eric Sunshine <sunshine@sunshineco.com> の 著作物である(©1999,2000 by Eric Sunshine)。 全ての権利は留保されている。

dumpkeymap の実装は、1997 年 9 月 3 日に Eric Sunshine <sunshine@sunshineco.com> と Paul S. McCarthy <zarnuk@zarnuk.com> が NeXT の .keymapping ファイルを解析して得た情報を基に行われた。

Version --