manual/modutils/release/man8/insmod.8

   1 .\" Copyright (c) 1996 Free Software Foundation, Inc.
   2 .\" This program is distributed according to the Gnu General Public License.
   3 .\" See the file COPYING in the kernel source directory.
   4 .\" $Id: insmod.8,v 1.5 2004/07/30 13:11:13 nakano Exp $
   5 .\"
   6 .\" Translated Sun Aug 15 10:54:37 JST 1999
   7 .\"         by FUJIWARA Teruyoshi <fujiwara@linux.or.jp>
   8 .\" Updated Thu 12 Oct 2000 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
   9 .\" Updated Sun 28 Jan 2001 by Kentaro Shirakata <argrath@ub32.org>
  10 .\"
  11 .\" WORD: persistent data       永続データ
  12 .\" WORD: prefix                プレフィックス
  13 .\"
  14 .TH INSMOD 8 "October 2, 2001" Linux "Linux Module Support"
  15 .SH 名前
  16 insmod \- ローダブルカーネルモジュールをインストールする
  17 .hy 0
  18 .SH 書式
  19 .B insmod
  20 [\-fhkLmnpqrsSvVxXyY] [\-e\ persist_name] [\-o\ module_name]
  21 [\-O\ blob_name] [\-P\ prefix] module [\ symbol=value\ ...\ ]
  22 .SH 説明
  23 .B insmod
  24 は実行中のカーネルにローダブルモジュールをインストールする。
  25 .PP
  26 .B insmod
  27 は実行中のカーネルにモジュールをリンクし、
  28 カーネルがエクスポートしているシンボルテーブルにある
  29 全てのシンボルを解決しようとする。
  30 .PP
  31 ディレクトリや拡張子なしでモジュールファイル名を与えると、
  32 .B insmod
  33 は標準のデフォルトディレクトリ(複数)からモジュールを探す。環境変数
  34 MODPATH を使って、このデフォルト値を上書きすることができる。
  35 /etc/modules.conf のようなモジュール設定ファイルがあれば、
  36 こちらの内容が MODPATH での指定を上書きする。
  37 .PP
  38 環境変数 MODULECONF によって、 /etc/modules.conf
  39 (あるいは /etc/conf.modules (使わないほうが良い))
  40 以外の設定ファイルを指定することもできる。
  41 この環境変数は、上記の指定すべてより優先される。
  42 .SS オプション
  43 .TP
  44 .I "-f --force"
  45 実行中のカーネルのバージョンと、
  46 モジュールに組み込まれているカーネルの対象バージョンが異なっても、
  47 モジュールのロードを試みる。
  48 これはカーネルバージョンチェックだけを無効にし、
  49 シンボル名チェックには何の影響も与えない。
  50 モジュールのシンボル名がカーネルのものと一致しない場合、
  51 .I insmod
  52 に強制的にモジュールをロードさせる方法はない。
  53 .TP
  54 .I "-h --help"
  55 ヘルプ文章を表示する。
  56 .TP
  57 .I "-k --autoclean"
  58 モジュールの auto-clean フラグを設定する。このフラグは
  59 \fBkerneld\fP(8) が使用し、
  60 一定期間(普通は 1 分)使われなかったモジュールを削除する。
  61 .TP
  62 .I "-L --lock"
  63 同じモジュールを同時にロードすることを防ぐために、\fBflock\fR(2) を用いる。
  64 .TP
  65 .I "-m --map"
  66 ロード時のメモリマップを標準出力に出力する。これにより、
  67 カーネルパニックの際のモジュールのデバッグが容易になる。
  68 より詳細なデバッグを可能にする。
  69 デフォルトでは ksymoops シンボルを定義する。
  70 このオプションは \-X/\-x オプションとは独立である。
  71 .sp
  72 ksymoops シンボルは、各ローダブルモジュールごとに、
  73 約 260 バイトを余分に必要とする。カーネル空間がキツキツで、
  74 ksyms を最小にしたいような場合を除き、
  75 デフォルトのままにして詳しい Oops デバッグを有効にするほうが良い。
  76 .TP
  77 .I "-o \fRmodule_name\fI --name\fR=module_name\fI"
  78 モジュールに明示的に名前をつける。
  79 通常はロードするオブジェクトファイルの
  80 basename に基づいた名前が用いられる。
  81 .TP
  82 .I "-O \fRblob_name\fI --blob\fR=blob_name\fI"
  83 バイナリオブジェクトを
  84 .I blob_name
  85 のファイル名で保存する。
  86 このファイルは カーネルにロードされ、セクション操作と再配置が行われた後の
  87 状態を正確に表しているバイナリ blob (ELF ヘッダなし)である。
  88 オブジェクトのマッピング情報を得るためには
  89 .I -m
  90 オプションが推奨される。
  91 .TP
  92 .I "-P \fRprefix\fI --prefix\fR=prefix\fI"
  93 このオプションは SMP カーネルや bigmem カーネル向けの、
  94 バージョン付きモジュールを使うときに利用できる。
  95 これらのモジュールには、シンボル名に余分な prefix がつくからである。
  96 カーネルがシンボルバージョンつきでビルドされると、
  97 insmod は自動的に prefix を "get_module_symbol" か "inter_module_get" の定義から取得する
  98 (モジュールをサポートする全てのカーネルにはこのどちらかが存在しなければならない)。
  99 カーネルがシンボルバージョンを持たず、
 100 しかしモジュールがシンボルバージョン付きでビルドされた場合は、
 101 ユーザーは \-P を指定する必要がある。
 102 .TP
 103 .I "-e \fRpersist_name\fI --persist\fR=persist_name\fI"
 104 モジュールの永続データを保存するファイル名を指定する。
 105 これはモジュールがロードされた時に読み込まれ、
 106 モジュールの実体がアンロードされた時に書き込まれる。
 107 モジュールに永続データがない場合はこのオプションは暗黙に無視される。
 108 永続データは
 109 .I insmod
 110 にこのオプションが指定された場合にのみ読み込まれる。
 111 デフォルトでは
 112 .I insmod
 113 は永続データを処理しない。
 114 省略記法として
 115 .I -e
 116 "" (空文字列) が指定されると、
 117 .I insmod
 118 は
 119 .I persistdir
 120 の値(
 121 .BR modules.conf (5)
 122 参照)の後ろに、モジュールのファイル名から末尾の \'.gz', \'.o' and \'.mod' を
 123 取ったもの(そのモジュールが見つかったモジュール検索パスからの相対パス)が
 124 指定されたものと解釈する。
 125 .IR persistdir =
 126 (つまり persistdir に 空フィールド)が指定されていると、
 127 省略記法は暗黙に無視される。
 128 .SS モジュールのパラメータ
 129 一部のモジュールではロード時にパラメータを指定して、
 130 動作を変えることができる。
 131 このようなパラメータは I/O ポートや IRQ 番号であることが多い。
 132 これらの数値はマシンごとに異なり、
 133 しかもハードウェアから求めることができないからである。
 134 .PP
 135 2.0 系列のカーネル用に構築したモジュールでは、
 136 全ての整数と文字ポインタシンボルはパラメータとして扱われ、
 137 従ってその内容は変更されうる。
 138 2.1 系列のカーネルからは、特定の値だけが変更されるように、
 139 シンボルにはパラメータかどうかの印が明示的に付けられる。
 140 また、ロード時に与えられた値をチェックするために、
 141 追加の型情報が与えられる。
 142 .PP
 143 整数の場合には、全ての値は 10 進値、8 進値, 16 進値で
 144 C 言語と同じように指定できる (17, 021, 0x11 等)。
 145 配列の要素は、値をコンマで区切って並べることにより指定する。
 146 値を省略することにより、要素を飛ばすことができる。
 147 .PP
 148 2.0 系列のモジュールでは、数字で始まらない値は文字列と解釈される。2.1
 149 以降では、値を文字列と解釈するかどうかはパラメータの型情報によって判断する。
 150 値が二重引用符(\fI"\fP)で始まる場合は、
 151 エスケープシーケンスも含めて全て C 言語と同じように文字列として解釈される。
 152 シェルのプロンプトで使う場合にはクォート自体もシェルが解釈するため、
 153 保護しなければならない点に注意すること。
 154 .SS GPL ライセンスのモジュールとシンボル
 155 カーネル 2.4.10 からモジュールはライセンス文を含むことになり、
 156 MODULE_LICENSE() によって定義されることになった。
 157 いくつかの文字列は GPL 互換であると認識される。
 158 それ以外のライセンス文字列だったり、そもそもライセンスがない場合は、
 159 そのモジュールはプロプラエタリなものとして扱われる。
 160 GPL 互換とされるライセンス文字列については
 161 include/linux/module.h を参照すること。
 162 .PP
 163 カーネルが
 164 .I /proc/sys/kernel/tainted flag
 165 をサポートする場合は、
 166 .I insmod
 167 は GPL ライセンスを持たないモジュールのロード時に、
 168 tainted (汚染) フラグを '1' と OR する。
 169 カーネルが tainting をサポートしていると、
 170 ライセンスのないモジュールがロードされる際には警告が発せられる。
 171 警告は GPL 互換でない MODULE_LICENSE() を持つモジュールに対しては
 172 (tainting をサポートしていない古いカーネルでも)、
 173 常に警告が発せられる。
 174 これによって、新しいモジュールが古いカーネルで利用されるときも、
 175 警告は最小限になる。
 176 .PP
 177 .I insmod\ -f
 178 (強制) モードでは、tainting をサポートするカーネルなら
 179 tainted フラグが '2' と OR され、常に警告が発せられる。
 180 .PP
 181 カーネル開発者の中には、彼らのコードがエクスポートするシンボルは、
 182 GPL 互換なライセンスのモジュールからしか利用できないようにしたい、
 183 と考えている人たちがいる。これらのシンボルは
 184 EXPOET_SYMBOL の代わりに EXPORT_SYMBOL_GPL でエクスポートされる。
 185 カーネルや、別のモジュールによってエクスポートされた
 186 GPL オンリーのシンボルは、GPL 互換なライセンスのモジュールからしか見えない。
 187 これらのシンボルには、
 188 /proc/ksyms において 'GPLONLY_' というプレフィックスが付く。
 189 .I insmod
 190 は GPL ライセンスのモジュールをロードするときは、
 191 シンボルの 'GPLONLY_' プレフィックスを無視し、
 192 通常のシンボル名の部分だけを参照する。
 193 GPL オンリーのシンボルは
 194 GPL 互換なライセンスを持たないモジュールに対しては利用可能とならない。
 195 ライセンスを全く持たないモジュールに対しても同様である。
 196 .SS KSYMOOPS 支援
 197 モジュール利用時のカーネル Oops のデバッグを支援するため、
 198 insmod はデフォルトではいくつかのシンボルを ksyms に追加する
 199 .RB ( \-Y
 200 オプションの説明を見よ)。
 201 これらのシンボルの名前は
 202 .BI __insmod_ modulename _
 203 で始まる。
 204 .I modulename
 205 はシンボルを他と重ならないようにするために必要である。
 206 同じオブジェクトを、別のモジュール名で複数回ロードするのは許されている。
 207 現在定義されているシンボルは
 208 .sp
 209 .nf
 210 __insmod_\fImodulename\fP_O\fIobjectfile\fP_M\fImtime\fP_V\fIversion\fP
 211 .fi
 212 .sp
 213 .I objectfile
 214 は、オブジェクトのロード元のファイルの名前である。
 215 これによって
 216 ksymoops がコードを正しいオブジェクトにマッチさせることが可能となる。
 217 .I mtime
 218 はそのファイルの最終修正タイムスタンプを 16 進で表したものである。
 219 stat に失敗すると 0 になる。
 220 .I version
 221 はモジュールのコンパイル時に指定されたカーネルのバージョンで、
 222 バージョンが取得できなければ \-1 となる。
 223 .\"NAKANO ちょっと意訳気味ですけれども。
 224 シンボル _O はモジュールヘッダと同じスタートアドレスになる。
 225 .sp
 226 .nf
 227 __insmod_\fImodulename\fP_S\fIsectionname\fP_L\fIlength\fP
 228 .fi
 229 .sp
 230 このシンボルは指定された ELF セクションの先頭に現れる。
 231 現在は .text, .rodata, .data, .bss である。
 232 これが現れるのは、セクションの長さが 0 以上の場合だけである。
 233 .I sectionname
 234 は ELF セクションの名前、
 235 .I length
 236 は各セクションの長さの 10 進表記である。
 237 これらのシンボルにより、 ksymoops はシンボルが使えない場合でも
 238 アドレスをセクションにマップできるようになる。
 239 .sp
 240 .nf
 241 __insmod_\fImodulename\fP_P\fIpersistent_filename\fP
 242 .fi
 243 .sp
 244 モジュールが永続データとしてマークされたパラメータを持ち、
 245 永続データを保存するファイル名が有効な場合 (上述の
 246 .I -e
 247 参照) にのみ、insmod によって作成される。
 248 .PP
 249 モジュールにおけるカーネル Oops のデバッグにおける別の問題として、
 250 /proc/ksyms と /proc/modules の内容が Oops とログファイル処理の間で
 251 変わってしまう可能性がある。
 252 この問題の処理を助けるため、
 253 /var/log/ksymoops があると、insmod と rmmod は自動的に
 254 /proc/ksyms と /proc/modules を /var/log/ksymoops
 255 に `date\ +%Y%m%d%H%M%S` の prefix を付けてコピーする。
 256 システム管理者は ksymoops に対して、
 257 Oops のデバッグ時にどのスナップショットファイルを利用するか伝えることができる。
 258 この自動コピーを無効にするスイッチは存在しない。
 259 これを望まない場合は、 /var/log/ksymoops を作ってはならない。
 260 このディレクトリを置くときには、所有者は root とし、
 261 モードは 644 または 600 にして、
 262 以下のスクリプトを一日一回程度実行すると良い。
 263 このスクリプトは insmod_ksymoops_clean としてインストールされる。
 264 .PP
 265 .nf
 266   #!/bin/sh
 267   # Delete saved ksyms and modules not accessed in 2 days
 268   if [ -d /var/log/ksymoops ]
 269   then
 270           set -e
 271           # Make sure there is always at least one version
 272           d=`date +%Y%m%d%H%M%S`
 273           cp -a /proc/ksyms /var/log/ksymoops/${d}.ksyms
 274           cp -a /proc/modules /var/log/ksymoops/${d}.modules
 275           find /var/log/ksymoops -type f -atime +2 -exec rm {} \\;
 276   fi
 277 .fi
 278 .SH 関連項目
 279 \fBrmmod\fP(8), \fBmodprobe\fP(8), \fBdepmod\fP(8), \fBlsmod\fP(8),
 280 \fBksyms\fP(8), \fBmodules\fP(2), \fBgenksyms\fP(8), \fBkerneld\fP(8),
 281 \fBksymoops\fP(kernel).
 282 .SH 履歴
 283 モジュール対応を誰が最初に考えたのかは不明である。
 284 .br
 285 Linux 用の最初のバージョンは Bas Laarhoven <bas@vimec.nl> が作成した。
 286 .br
 287 バージョン 0.99.14 は Jon Tombs <jon@gtex02.us.es> が作成した。
 288 .br
 289 Bjorn Ekwall <bj0rn@blox.se> が拡張を行った。
 290 .br
 291 元々の ELF 対応は Eric Youngdale <eric@aib.com> の助力によるものである。
 292 .br
 293 バージョン 2.1.17 への更新は Richard Henderson <rth@tamu.edu> が行った。
 294 .br
 295 modutil-2.2.* での拡張は 1999 年 3 月に Bjorn Ekwall <bj0rn@blox.se> が行った。
 296 .br
 297 ksymoops の補助は 1999 年 5 月に Keith Owens <kaos@ocs.com.au> が行った。
 298 .br
 299 メンテナ: Keith Owens <kaos@ocs.com.au>.