日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
PCAP(3) PCAP(3)
名称
pcap - パケット Capture (獲得) ライブラリ
書式
#include <pcap/pcap.h>
解説
パケット Capture (獲得) ライブラリは、パケットキャプチャ (捕獲) システ
ムのための高レベルのインタフェースを供給します。他のホストに向かうもの
でさえ、このメカニズムを通してネットワーク上のすべてのパケットをアクセ
ス可能です。また、``savefile'' にキャプチャされたパケットを格納すること
と、``savefile'' からパケットを読み込むことをサポートしています。
読み込みのためにキャプチャのハンドルをオープン
ライブキャプチャ、キャプチャが行われるべきである、ネットワークまたは他
のインタフェースの与えられた名前のためのハンドルをオープンするために
は、ハンドルで適切なオプションを設定する pcap_create() を呼び出し、次に
pcap_activate() でそれを活性化します。
ライブキャプチャのためにオープンすることができるデバイスのリストを取得
するためには、pcap_findalldevs() を呼び出します。pcap_findalldevs() に
よって返されたリストを解放するためには、pcap_freealldevs() を呼び出しま
す。pcap_lookupdev() は、``ループバック'' ネットワークインタフェースで
ないそのリストの最初のデバイスを返します。
``savefile'' のパスを与えられ、パケットを読み込むために ``savefile'' の
ためのハンドルをオープンするためには、pcap_open_offline() を呼び出しま
す。読み込みのために既にオープンされているファイルを参照する FILE * を
与えられて、``savefile'' のためのハンドルをセットアップするためには、
pcap_fopen_offline() を呼び出します。
書き込みのために ``savefile'' をオープンし、フィルタ表現をコンパイルす
るルーチンのように、引数として pcap_t を要求するルーチンで使用するため
に ``偽の'' pcap_t を取得するためには、pcap_open_dead() を呼び出しま
す。
pcap_create(), pcap_open_offline(), pcap_fopen_offline() と
pcap_open_dead() は、キャプチャストリームまたは ``savefile'' からパケッ
トを読み込むために、そしてキャプチャストリームまたは ``savefile'' に関
する情報を見つけるために使用するハンドルである、pcap_t へのポインタを返
します。ハンドルをクローズするためには、pcap_close() を使用します。
キャプチャハンドルで次のオプション設定できます
スナップショットの長さ (snapshot length)
キャプチャするとき、利用者がパケットの全体の内容をキャプチャする
るなら、それは、パケットを利用者のアプリケーションにコピーするた
めに多くの CPU 時間、パケットデータをファイルに書き込むために多
くのディスク空間と場合によりネットワーク回線容量、とパケットを保
存するためにより多くのディスク空間を必要とします。利用者がパケッ
ト全体の内容を必要としないなら - 例えば、パケットの TCP ヘッダの
みに関心があるなら、- 利用者は、キャプチャのための "スナップ
ショットの長さ" を適切な値に設定できます。スナップショットの長さ
が snaplen に設定されて、snaplen がキャプチャされるパケットのサ
イズ以下であるなら、パケットの最初の snaplen バイトのみがキャプ
チャされ、パケットデータとして提供されます。
パケットから利用可能なすべてのデータをキャプチャするためにすべて
のネットワークではありませんが、ほとんどで、65535 のスナップ
ショットの長さは、十分でしょう。
スナップショットの長さは、pcap_set_snaplen() で設定されます。
プロミスキャス (混合) モード (promiscuous mode)
イーサネットのようなブロードキャスト (同報通信) LAN では、ネット
ワークが切り換えられないか、またはアダプタがスイッチを通過するす
べてのパケットが、送信されるスイッチの "ミラーポート" に接続され
るなら、ネットワークアダプタは、ネットワークアダプタが認識するよ
うに設定されていないネットワークアドレスに送信されなかったユニ
キャストまたはマルチキャストパケットを含んでいる、LAN ですべての
パケットを受信します。
通常、そのアダプタは、それらのパケットを捨てます。しかしながら、
多くのネットワークアダプタは、パケットがアダプタが認識するアドレ
スに送信されなくても、すべてのパケットは、ホストに提供されるモー
ドである、"プロミスキャスモード" をサポートします。これは、解析
のために 2 つ以上の他のホストの間のトラフィックをそのままキャプ
チャするために役に立ちます。
アプリケーションがプロミスキャスモードを設定しなくても、アダプタ
は、ある他の理由のためにプロミスキャスモードとなるかもしれないこ
とに注意してください。
今のところ、これは、"any (どの)" デバイスでも動作していません。
"any" または NULL の引数が供給されるなら、プロミスキャスモードの
設定は、無視されます。
プロミスキャスモードは、pcap_set_promisc() で設定されます。
ミラーモード (monitor mode)
IEEE 802.11 無線 LAN では、たとえアダプタがプロミスキャスモード
であっても、関連しているネットワークのためにフレームだけをホスト
に提供します。それは、また、管理または制御フレームではなく、デー
タフレームだけを提供し、それらのフレームのために 802.11 ヘッダま
たはラジオ情報疑似ヘッダを供給しないかもしれません。
また時々 "rfmon モード" ("Radio Frequency MONitor" (ラジオ周波
数モニタ) のために) と呼ばれる "モニタモード" で、アダプタは、そ
れが 802.11 ヘッダで受信するすべてのフレームを提供し、同様にフ
レームに関するラジオ情報で疑似ヘッダを提供するかもしれません。
モニタモードで、アダプタは、利用者がそのアダプタで任意の無線ネッ
トワークを使用することができないように、それに関連しているネット
ワークから分離するかもしれないことに注意してください。これは、利
用者がモニタモードでキャプチャし、別のアダプタで別のネットワーク
に接続されないなら、ネットワークサーバのファイルにアクセスする
か、またはホスト名またはネットワークアドレスを解決することを防ぐ
かもしれません。
pcap_set_rfmon() でモニタモードを設定し、アダプタをモニタモード
にすることができるかどうかを決定するために pcap_can_set_rfmon()
を使用することができます。
パケットバッファのみタイムアウト (packet buffer timeout)
キャプチャするとき、パケットが到着するとすぐに配信されるなら、パ
ケットをキャプチャするアプリケーションは、パケットが到着すると
き、各パケットのために起こされます、そして各パケットを取って来る
ためにオペレーティングシステムを 1 回以上の呼び出しを行わなけれ
ばならないかもしれません。
代りに、パケットを到着するとすぐに配信されませんが、("パケット
バッファのタイムアウト" と呼ばれる) 少しのディレイ (遅れ) の後に
配信されるるなら、複数のパケットのために単一の wakeup (起きるこ
と) を行い、オペレーティングシステムに行われる呼び出しの各組は、
単一のパケットではなく、複数のパケットを供給することができるよう
に、パケットが配信される前に、複数のパケットを蓄積することができ
ます。パケットが高いレートで到着するなら、これは、キャプチャする
ことができる 1 秒毎のパケットの数を増加させ、パケット毎の CPU の
オーバヘッドを削減します。
パケットバッファのタイムアウトは、パケットを配信する前に、アプリ
ケーションがオペレーティングシステムのキャプチャバッファを満たす
ために wait (待ち) しなくてもよいように要求されます。パケットが
ゆっくり到着するなら、その wait (待ち) は、任意に長い期間がかか
るかもしれません。
すべてのプラットフォームが、パケットバッファのタイムアウトをサ
ポートしているというわけではありません。それを行わないプラット
フォームで、パケットバアファのタイムアウトは、無視されます。パ
ケットバッファのタイムアウトをサポートするプラットフォームで、タ
イムアウトための 0 値によって、読み込みは、タイムアウトなしで、
パケットが到着するのを十分可能なだけ wait (待ち) します。負な値
は、無効です。タイムアウトを負な値に設定することの結果は、予測不
可能です。
注: いくつかのプラットフォームでは、パケットバッファのタイムアウ
トがサポートされず、いくつかのプラットフォームでは、タイマは、少
なくとも 1 つのパケットが到着するまで開始しないので、時間の制限
された期間以内に返るために読み込みパケットを呼び出しを引き起こす
ためにパケットバッファタイムアウトを使用することはできません。こ
れは、読み込むタイムアウトが使用されるべきでないことを意味しま
す、例えば、パケットキャプチャのループがユーザ入力のために定期的
に ``ポーリング'' することができるインタラクティブなアプリケー
ションで、パケットが到着しなくても、タイムアウトが期限が切れた後
に、パケットを読み込む呼び出しが、返るという保証が全くない場合で
す。
パケットバッファのタイムアウトは、pcap_set_timeout() で設定され
ます。
immediate mode
即時モードで、パケットは、常に、それらが到着するとすぐにバッファ
リングなしで配信されます。即時モードは、
pcap_set_immediate_mode() で設定されます。
バッファサイズ (buffer size)
キャプチャのために到着するパケットは、到着するとすぐに、アプリ
ケーションに読み込まれる必要がないように、バッファに格納されま
す。いくつかのプラットフォームでは、バッファのサイズを設定するこ
とできます。小さ過ぎるサイズは、あまりに多くのパケットがキャプ
チャされ、スナップショットの長さがバッファリングされるデータの量
を制限しないなら、大き過ぎるサイズは、パケットが落されることを防
ぐために必要とするより、より多くのページング不可能なオペレーティ
ングシステムのメモリを使用するかもしれませんが、アプリケーション
が、それからパケットを読み込むことができる前に、バッファが満杯に
なるなら、パケットが落されるかもしれないことを意味します。
バッファサイズは、pcap_set_buffer_size() で設定されます。
タイムスタンプのタイプ (timestamp type)
いくつかのプラットフォームにおいて、ライブキャプチャのパケットに
与えられたタイムスタンプは、異なる解決があるかもしれないか、また
はネイティブのオペレーティングシステムのルーチンによって供給され
た現在の時刻のための時間の値と異なる関係があるかもしれない、異
なったソースから来るかもしれません。タイムスタンプのタイプのリス
トについては、pcap-tstamp(7) を参照してください。
タイムスタンプのタイプは、pcap_set_tstamp_type() で設定されま
す。
ネットワークインタフェースからパケットを読み込むことは、利用者に特権が
あることを必要とします:
NIT または BPF がある SunOS 3.x または 4.x の下で:
利用者には、/dev/nit または /dev/bpf* の読み込みアクセスができな
ければなりません。
DLPI がある Solaris の下で:
利用者には、ネットワーク疑似デバイス、例えば、/dev/le の読み込
み/書き込みアクセスができなければなりません。しかしながら、
Solaris の少なくともいくつかのバージョンでは、これは、tcpdump が
プロミスキャスモードでキャプチャすることができるために十分ではあ
りません。Solaris のそれらのバージョンでは、プロミスキャスモード
でキャプチャするために、利用者は、root でなければなりません、ま
たはパケットをキャプチャするアプリケーションは、root に setuid
してインストールされていなければなりません。多く (おそらくすべ
て) のインタフェースで、利用者がプロミスキャスモードでキャプチャ
しないなら、利用者は、任意の発信パケットを見れないので、プロミス
キャスモードで行われなかったキャプチャは、それほど役に立たないこ
とに注意してください。
Solaris の新しいバージョンでは、利用者は、net_rawaccess 特権を与
えられていなければなりません。これは、ネットワーク疑似デバイスへ
のアクセスを利用者に与えるために必要で十分です - そのデバイスで
特権を変更する必要はありません。例えば、usermod (8) コマンドで
ユーザの defaultpriv キーにその特権を追加することによって、その
特権をユーザに与えることができます。
DLPI がある HP-UX の下で:
利用者は、ルートでなければならないか、またはパケットをキャプチャ
するアプリケーションが、ルートに setuid をしてインストールされて
いなければなりません。
スヌープ (snoop) がある IRIX の下で:
利用者は、ルートでなければならないか、またはパケットをキャプチャ
するアプリケーションが、ルートに setuid をしてインストールされて
いなければなりません。
Linux の下で:
利用者は、ルートでなければならないか、または (利用者の配布に、
CAP_NET_RAW とそれらがログインするとき、ユーザの初期プロセスでそ
れらのビットを設定するのを許容するために、それらのケーパビリティ
ビットを特定のアカウントに与えられることができるコードのような
ケーパビリティビットをサポートするカーネルがないなら、その場合、
利用者には、キャプチャするための CAP_NET_RAW と、例えば、-D フラ
グでネットワークデバイスを列挙するための CAP_NET_ADMIN がなけれ
ばなりませんが) パケットをキャプチャするアプリケーションが、ルー
トに setuid をしてインストールされていなければなりません。
ULTRIX と Digital UNIX/Tru64 UNIX の下で:
任意のユーザが、ネットワークトラフィックをキャプチャします。しか
しながら、(スーパユーザでさえない) ユーザは、スーパユーザが
pfconfig(8) を使用するインタフェースでプロミスキャスモードの操作
を有効にしていないなら、インタフェースでプロミスキャスモードで
キャプチャすることができません、そして、(スーパユーザでさえない)
ユーザは、スーパユーザが pfconfig を使用するインタフェースでコ
ピーオールモード (copy-all-mode) の操作を有効にしていないなら、
インタフェースでマシンによって受信されるか、または送信されるユニ
キャストトラフィックをキャプチャすることができませんので、インタ
フェースで役に立つパケットのキャプチャは、そのインタフェースで有
効にされるプロミスキャスモードまたはコピーオールモード操作のいず
れか、または両方の操作モードをたぶん必要とします。
(macOS を含んで) BSD の下で:
利用者は、クローニング BPF デバイスを持っていないシステムで
/dev/bpf* または、持っているシステムで /dev/bpf への読み込みアク
セスがなければなりません。(macOS を含んで) devfs がある BSDs で
は、これは、BPF デバイスで所有権またはパーミッションを設定する
スーパユーザのアクセスがある誰かが単に持つ以上の必要があるかもし
れません - システムがブートされるたびに、システムが devfs サポー
トしていても、所有権またはパーミッションを設定するために devfs
を設定するする必要があるかもしれません。それをサポートしないな
ら、利用者は、ブート時に起こるようにするある他の方法を見つけなけ
ればならないかもしれません。
保存されたパケットファイルを読み込むために特権を必要としません。
ハンドルから読み込まれたパケットは、パケットメタデータの様々な形式を含
んでいる ``偽ヘッダ''、たぶんその内容が異なるネットワークインタフェース
のための異なるかもしれないリンクレイヤヘッダを含んでいます。ハンドルに
よって供給されたパケットの形式を決定するためには、pcap_datalink() を呼
び出します。https://www.tcpdump.org/linktypes.html は、それが返す値をリ
ストし、それらの値に対応するパケットの形式を記述しています。
与えられたキャプチャまたは ``savefile`` のためのパケットが、イーサネッ
トのための DLT_EN10MB のような、あらゆる与えられたリンクレイヤのヘッダ
タイプがあることを仮定してはなりません。例えば、Linux の "any" デバイス
は、たとえ、その時点のシステムのすべてのデバイスでも、DLT_LINUX_SLL の
リンクレイヤのヘッダタイプがあり、オープンされた "any" デバイスには、
イーサネットのための DLT_EN10MB のような、いくつかの他のデータのリンク
タイプがあります。
``savefile'' のためにオープンされる pcap_t に対応する FILE * を得るため
には、pcap_file() を呼び出します。
ルーチン
pcap_create(3)
ライブキャプチャのための pcap_t を取得します。
pcap_activate(3)
ライブキャプチャのための pcap_t を活性化します。
pcap_findalldevs(3)
ライブキャプチャのためのオープンすることができるデバイス
のリストを取得します。
pcap_freealldevs(3)
デバイスのリストを解放します。
pcap_lookupdev(3)
そのリストで最初の非ループバック (non-loopback) デバイス
を取得します。
pcap_open_offline(3)
パス名を与えられて、``savefile'' のための pcap_t をオープ
ンします。
pcap_open_offline_with_tstamp_precision(3)
与えられたパス名とパケットのタイムスタンプのために提供さ
れる精度を指定して ``savefile'' のために pcap_t をオープ
ンします。
pcap_fopen_offline(3)
FILE * を与えられて、``savefile'' のための pcap_t をオー
プンします。
pcap_fopen_offline_with_tstamp_precision(3)
与えられた FILE *, とパケットのタイムスタンプのために提供
する精度を指定して ``savefile'' のための pcap_t をオープ
ンします。
pcap_open_dead(3)
``偽の'' pcap_t を作成します。
pcap_close(3)
pcap_t をクローズします。
pcap_set_snaplen(3)
ライブキャプチャのための、まだ活性化されていない (not
yet-activated) pcap_t のためのスナップショットの長さを設
定します。
pcap_snapshot(3)
pcap_t のためのスナップショットの長さを取得します。
pcap_set_promisc(3)
ライブキャプチャのための、まだ活性化されていない (not
yet-activated) pcap_t のためのプロミスキャスモードを設定
します。
pcap_set_protocol_linux(3)
ライブキャプチャのための、まだ活性化されていない (not
yet-activated) pcap_t のためのキャプチャプロトコルを設定
します。
pcap_set_rfmon(3)
ライブキャプチャのための、まだ活性化されていない (not
yet-activated) pcap_t のためのモニタモードを設定します。
pcap_can_set_rfmon(3)
ライブキャプチャのための、pcap_t のためのモニタモードを設
定できるかどうか判断します。
pcap_set_timeout(3)
ライブキャプチャのための、まだ活性化されていない (not
yet-activated) pcap_t のためのパケットバッファのタイムア
ウトを設定します。
pcap_set_immediate_mode(3)
ライブキャプチャのための、まだ活性化されていない (not
yet-activated) pcap_t のための即時モードを設定します。
pcap_set_buffer_size(3)
ライブキャプチャのための、まだ活性化されていない (not
yet-activated) pcap_t のためのバッファサイズを設定しま
す。
pcap_set_tstamp_type(3)
ライブキャプチャのための、まだ活性化されていない (not
yet-activated) pcap_t のためのタイムスタンプのタイプを設
定します。
pcap_list_tstamp_types(3)
ライブキャプチャのための、まだ活性化されていない (not
yet-activated) pcap_t のための使用可能なタイムスタンプの
タイプのリストを取得します。
pcap_free_tstamp_types(3)
使用可能なタイムスタンプのタイプのリストを解放します。
pcap_tstamp_type_val_to_name(3)
タイムスタンプのタイプの名前を取得します。
pcap_tstamp_type_val_to_description(3)
タイムスタンプのタイプのために記述を取得します。
pcap_tstamp_type_name_to_val(3)
名前に対応するタイムスタンプのタイプを取得します。
pcap_set_tstamp_precision(3)
ライブキャプチャのための、まだ活性化されていない (not
yet-activated) pcap_t のためのタイムスタンプの精度を設定
します。
pcap_get_tstamp_precision(3)
ライブキャプチャのための、pcap_t のタイムスタンプの精度を
取得します。
pcap_datalink(3)
pcap_t のためのリンクレイヤヘッダタイプを取得します。
pcap_file(3)
``savefile'' のためにオープンされた pcap_t のための
FILE * を取得します。
pcap_is_swapped(3)
読み込まれている ``savefile'' が反対のバイト順のマシンか
ら来たかどうか判断します。
pcap_major_version(3)
pcap_minor_version(3)
``savefile'' のためのファイル形式バージョンのメジャーとマ
イナのバージョンを取得します。
ライブキャプチャのためのリンクレイヤヘッダタイプを選択
いくつかのデバイスは、2 つ以上のリンクレイヤヘッダタイプを提供します。
デバイスによって提供されるすべてのリンクレイヤヘッダタイプのリストを取
得するためには、デバイスのために活性化された pcap_t で
pcap_list_datalinks() を呼び出します。リンクレイヤヘッダタイプのリスト
を解放するためには、pcap_free_datalinks() を呼び出します。デバイスのた
めにリンクレイヤヘッダタイプを設定するためには、pcap_set_datalink() を
呼び出します。これは、デバイスが活性化された後に、行われるべきですが、
あらゆるパケットが読み込まれる前で、あらゆるフィルタがコンパイルされる
かインストールされる前です。
ルーチン
pcap_list_datalinks(3)
デバイスのためのリンクレイヤヘッダタイプのリストを取得し
ます。
pcap_free_datalinks(3)
リンクレイヤヘッダタイプのリストを解放します。
pcap_set_datalink(3)
デバイスのためのリンクレイヤヘッダタイプを設定します。
pcap_datalink_val_to_name(3)
リンクレイヤヘッダタイプの名前を取得する。
pcap_datalink_val_to_description(3)
リンクレイヤヘッダタイプのために記述を取得します。
pcap_datalink_name_to_val(3)
名前に対応するリンクレイヤヘッダタイプを取得します。
パケットを読み込む
パケットは、1 つ以上のパケットを処理する、pcap_dispatch() または
pcap_loop() で、各パケットのためのコールバックルーチンを呼び出すか、ま
たは次のパケットを返す pcap_next() または pcap_next_ex() で読み込まれま
す。pcap_dispatch() と pcap_loop() のためのコールバックは、次のメンバを
含む struct pcap_pkthdr へのポインタが提供されます:
ts パケットがキャプチャされるとき、時間を含む struct
timeval。
caplen キャプチャから利用可能なパケットのバイト数を与える
bpf_u_int32。
len (パケットの長さがキャプチャするためのバイトの最大数より大
きいなら、パケットから利用可能なバイト数より多いかもしれ
ない) バイト単位のパケットの長さを与える bpf_u_int32。
また、コールバックは、(上記の struct pcap_pkthdr ポインタで与えられるよ
うな) パケットの最初の caplen バイトのデータへの const u_char ポインタ
を供給されます。これは、必ずしもパケット全体となるというわけではありま
せん。すべてのパケットをキャプチャするために、利用者は、
pcap_set_snaplen() への呼び出しでパケットのデータのすべてを得るために十
分大きな snaplen のための値を提供しなければなりません - 値が 65535 であ
れば、すべてのネットワークでないなら、ほぼ十分のはずです)。``savefile''
から読み込むとき、キャプチャが実行されたとき指定されたスナップショット
の長さは、利用可能なパケットデータの総量を制限します。
pcap_next() は、struct pcap_pkthdr 構造対を指す引数を渡されて、パケット
のためのタイムスタンプと長さの値でそれに書き込みます。それは、成功すれ
ば、パケットの最初の caplen バイトへの const u_char を返し、エラーで、
NULL を返します。
pcap_next_ex() は、2 つのポインタの引数を渡し、1 つは、
structpcap_pkthdr* を指し、1 つは、const u_char* を指します。それは、パ
ケットのためのタイムスタンプと長さ値で struct pcap_pkthdr 構造体を指す
最初のポインタを設定し、パケットの最初の caplen バイトを指する 2 番目の
ポインタを設定します。
pcap_dispatch() または pcap_loop() のループを強制的に終了するためには、
pcap_breakloop() を呼び出します。
デフォルトで、ライブキャプチャのためにオープンされたインタフェースから
パケットを読み込むとき、pcap_dispatch(), pcap_next() と pcap_next_ex()
は、パケットが読み込まれるれることが現在利用可能でなければ、利用可能と
なるパケットのためのウェートをブロックします。すべてのプラットフォーム
ではなくいくつかで、パケットバッファのタイムアウトが指定されたなら、
ウェートは、パケットバッファのタイムアウトが終了した後に終了します。ア
プリケーションは、いくつかのプラットフォームで起こるように、このために
準備されているべきですが、他のプラットフォームで起こらないので、それに
依存するべきではありません。たとえパケットが利用可能でなくても、wait
(待ち) は、終了するかもしれないし、終了しないかもしれないことに注意して
ください。アプリケーションは、起こるように、これのために準備されるべき
ですが、起こることに頼ってはなりません。
ハンドルは、``非ブロッキングモード'' (non-blocking mode) に入れることが
できるので、それらのルーチンは、ブロッキングするのではなく、パケットが
読み込みできないことを示す印を返します。ハンドルを非ブロッキングモード
に入れるか、または非ブロッキングモードから抜けるためには、
pcap_setnonblock() を呼び出します。ハンドルが非ブロッキングモードである
かどうか判断するためには、pcap_getnonblock() を呼び出します。非ブロッキ
ングモードは、Mac OS X 10.6 で正確に動作しないことに注意してください。
非ブロッキングモードは、しばしば select(2) または poll(2) またはプラッ
トフォームが読み込みを準備する 1 組の記述子のうちのいずれかで wait (待
つ) するために提供する他のルーチンのように、ルーチンと組み合わされま
す。ハンドルのために、それらのルーチンで使用することができる記述子を取
得するためには、pcap_get_selectable_fd() を呼び出します。ルーチンが、
データが、記述子で読み込むために利用可能であることを示すなら、試みは、
デバイスから読み込むためにために行なわれるべきです。
すべてのハンドルが、そのような記述子を利用可能にしておくとは限りませ
ん。pcap_get_selectable_fd() は、そのような記述子が存在しないなら、
PCAP_ERROR を返します。そのような記述子が利用可能ではないなら、デバイス
がパケットのために周期的にポーリングされなければなりません。その場合
に、pcap_get_required_select_timeout() 値が、それらのルーチンでタイムア
ウトとして使用することができる、struct timeval へのポインタを返します。
ルーチンが返るとき、試みは、デバイスからパケットの読み込みために行なわ
れるべきです。pcap_get_required_select_timeout() が NULL を返るなら、そ
のようなタイムアウトが￥は、利用可能ではなく、それらのルーチンは、デバ
イスで使用することはできません。
さらに、様々な理由で、それらのルーチンの 1 つ以上は、記述子で適切に動作
しません。pcap_get_selectable_fd() のための文書は、詳細を示します。ちょ
うど pcap_t からパケットを読み込む試みとして、パケットバッファのタイム
アウトが期限切れになるなら、なにもパケットを返しません、select(),
poll() または他のそのような呼び出しは、パケットバッファのタイムアウトの
期限切れであるなら、たとえ読み込むために利用可能なパケットがなくても、
記述子が読み込む準備ができていることを示します。
ルーチン
pcap_dispatch(3)
ライブキャプチャまたは ``savefile'' のためにオープンする
pcap_t からのパケットのフルセットのためにオープンする
pcap_t からパケット満杯のバッファを読み込みます。
pcap_loop(3)
割り込みまたはエラーが生じるまで、pcap_t からパケットを読
み込みます。
pcap_next(3)
エラーが生じたかどうかを示す印なしに pcap_t からパケット
を読み込みます。
pcap_next_ex(3)
エラーでエラー表示をつけて pcap_t からパケットを読み込み
ます。
pcap_breakloop(3)
時期を早めて、pcap_dispatch() または pcap_loop() でループ
を終了します。
pcap_setnonblock(3)
pcap_t で非ブロッキングモードを設定するか、またはクリアし
ます。
pcap_getnonblock(3)
pcap_t のために非ブロッキングモードの状態を取得します。
pcap_get_selectable_fd(3)
select(2) と poll(2) のような呼び出しで使用することができ
る pcap_t のための記述子を取得することを試みます。
pcap_get_required_select_timeout(3)
select(2) と poll(2) で利用可能でない記述子が、pcap_t の
ために利用可能であるなら、それらのルーチンで使用可能なタ
イムアウトを取得することを試みます。
フィルタ
パケットを読み込むとき、特定のパケットだけを返すためには、ハンドルで
フィルタを設定することができます。ライブキャプチャについては、フィルタ
リングは、カーネルからユーザモードまでの ``つまらない'' パケットのコ
ピーを避けるために、できれば、カーネルモードで実行されます。
テキスト文字列としてフィルタを指定することができます。文字列の構文とセ
マンティクスは、pcap-filter(7) によって記述された通りです。フィルタの文
字列は、pcap_compile() によって疑似マシン語 (pseudo-machine-language)
でプログラムにコンパイルされ、pcap_setfilter() でハンドルに対して結果の
プログラムをフィルタリングすることができます。pcap_compile() の結果は、
pcap_freecode() への呼び出しで解放することができます。pcap_compile()
は、フィルタの文字列の特定の表現のためのネットワークマスクを要求しま
す。与えられたキャプチャデバイスのためのネットワークアドレスとネット
ワークマスクを見つけるために pcap_lookupnet() を使用することができま
す。
また、コンパイルされたフィルタを pcap_offline_filter() を使用して読み込
まれたパケットに直接適用することができます。
ルーチン
pcap_compile(3)
疑似マシン語のコードのプログラムへのフィルタ表現をコンパ
イルします。
pcap_freecode(3)
フィルタプログラムを解放します。
pcap_setfilter(3)
pcap_t のためのフィルタを設定します。
pcap_lookupnet(3)
キャプチャデバイスのためのネットワークアドレスとネット
ワークマスクを取得します。
pcap_offline_filter(3)
パケットにフィルタプログラムを適用します。
着信と発信パケット
デフォルトで、libpcap は、マシンによって送信されたパケットとマシンに
よって受信されたパケットの両方をキャプチャすることを試みます。それをマ
シンによって受信されたパケットだけ、またはできれば、マシンによって送信
されたパケットだけをキャプチャすることを制限するためには、
pcap_setdirection() を呼び出します。
ルーチン
pcap_setdirection(3)
着信パケット、発信パケットまたは両方をキャプチャするかど
うかを指定します。
キャプチャの統計
ライブキャプチャで受信され、落されたパケットに関する統計を取得するに
は、pcap_stats() を呼び出します。
ルーチン
pcap_stats(3)
キャプチャの統計を取得します。
キャプチャされたパケットを書き込むためのハンドルをオープン
``savefile'' にあるべきパス名を与えられ、パケットを書き込むために
``savefile'' をオープンするためには、pcap_dump_open() を呼び出します。
``savefile'' にあるべきパス名を与えられ、パケットを書き込むために
``savefile'' をオープンするためには、pcap_dump_open() を呼び出します。
書き込みのために既にオープンされているファイルを参照する FILE * を与え
られて、``savefile'' のためのハンドルをセットアップするためには、
pcap_dump_fopen() を呼び出します。それらは各々、``savefile'' にパケット
を書き込むために使用されたハンドルである、pcap_dumper_t へのポインタを
返します。それが成功するなら、それが存在しないなら、ファイルを作成し、
それが存在するなら、ファイルを切り詰めます。pcap_dumper_t をクローズす
るためには、pcap_dump_close() を呼び出します。
ルーチン
pcap_dump_open(3)
パス名を与えられ、``savefile'' のために pcap_dumper_t を
オープンする。
pcap_dump_fopen(3)
FILE * を与えられ、``savefile'' のために pcap_dumper_t を
オープンする。
pcap_dump_close(3)
pcap_dumper_t をクローズします。
pcap_dump_file(3)
``savefile'' のためにオープンされた pcap_dumper_t のため
の FILE * を取得します。
パケットを書き込む
pcap_dumper_t にパケットを書き込むためには、pcap_dump() を呼び出しま
す。pcap_dump() で書き込まれたパケットは、``savefile'' に直接書き込むの
ではなく、バッファリングされます。pcap_dumper_t をクローズすることに
よって、すべてのバッファリングされているが、まだ書き込まれていない
(buffered-but-not-yet-written) パケットは、``savefile'' に書き込まれる
ます。pcap_dumper_t をクローズせずに、``savefile'' に書き込むために
pcap_dumper_t によってバッファリングされるので、pcap_dumper_t に
``savefile'' にまだ書き込まれていない、すべてのパケットを強制的に書き込
むためには、pcap_dump_flush() を呼び出します。
ルーチン
pcap_dump(3)
pcap_dumper_t にパケットを書き込みます。
pcap_dump_flush(3)
pcap_dumper_t に書き込まれるバッファリングされているパ
ケットを ``savefile'' にフラッシュします。
pcap_dump_ftell(3)
pcap_dumper_t に対して現在のファイル位置を取得します。
パケットを注入
必要な特権があるなら、pcap_inject() または pcap_sendpacket() を使用し
て、ライブキャプチャのための pcap_t でネットワークにパケットを注入する
ことができます。(2 つのルーチンは、OpenBSD と WinPcap の両方との互換性
のために存在します。それらは、同じ機能を実行しますが、異なる返り値があ
ります。)
ルーチン
pcap_inject(3)
pcap_sendpacket(3)
パケットを送信します。
エラーの報告
いくつかのルーチンは、エラーまたは警告の状態コードを返します。それらを
文字列に変換するためには、pcap_statustostr() を使用します。
ルーチン
pcap_statustostr(3)
エラーまたは警告の状態コードのための文字列を取得します。
ライブラリバージョン情報を取得
libpcap に関するバージョン情報を与える文字列を取得するためには、
pcap_lib_version() を呼び出します。
ルーチン
pcap_lib_version(3)
ライブラリのバージョンの文字列を取得します。
後方互換性
1.0 より前の libpcap のバージョンでは、pcap.h ヘッダファイルは、ほとん
どのプラットフォームで pcap ディレクトリにありませんでした。利用者が、
1.0 より前の libpcap のバージョンで動作しなければならないアプリケーショ
ンを書いているなら、<pcap/pcap.h> を含めるよりむしろ利用者のための
<pcap/pcap.h> を含む、<pcap.h> を含めてください。
pcap_create() と pcap_activate() は、1.0 より前の libpcap のバージョン
で利用可能ではありませんでした。利用者が、1.0 より前の libpcap のバー
ジョンで動作しなければならないアプリケーションを書いているなら、ライブ
キャプチャのためにハンドルを取得するために pcap_open_live() を使用する
か、または pcap_create() と pcap_activate() を使用することによって提供
された追加機能は使用できるようにしたいなら、libpcap 1.0 API が利用可能
であるかどうかをチェックするために autoconf(1) スクリプトか、またはある
他の設定スクリプトを使用します、そしてそれらがある場合のみ使用します。
関連項目
autoconf(1), tcpdump(1), tcpslice(1), pcap-filter(7), pfconfig(8),
usermod(8)
作者
libpcap の原作者は、次の通りです:
Van Jacobson, Craig Leres と Steven McCanne, all of the Lawrence
Berkeley National Laboratory, University of California, Berkeley, CA.
現在のバージョンは、次の "The Tcpdump Group" のウェブサイトで利用可能で
す。
https://www.tcpdump.org/
バグ
セキュリティ問題を報告するためには、電子メールを security@tcpdump.org
に送ってください。
バグと他の問題を報告するためには、パッチを提供し、機能を要求し、一般的
なフィードバックなどを提供し、libpcap ソースツリーのルートで、ファイル
CONTRIBUTING を参照してください。
25 July 2018 PCAP(3)