PCAP(3)

名称
pcap - Packet Capture ライブラリ

書式
#include <pcap.h>

pcap_t *pcap_open_live(char *device, int snaplen,
int promisc, int to_ms, char *ebuf)
pcap_t *pcap_open_offline(char *fname, char *ebuf)
pcap_dumper_t *pcap_dump_open(pcap_t *p, char *fname)

char errbuf[PCAP_ERRBUF_SIZE];
char *pcap_lookupdev(char *errbuf)
int pcap_lookupnet(char *device, bpf_u_int32 *netp,
bpf_u_int32 *maskp, char *errbuf)

int pcap_dispatch(pcap_t *p, int cnt,
pcap_handler callback, u_char *user)
int pcap_loop(pcap_t *p, int cnt,
pcap_handler callback, u_char *user)
void pcap_dump(u_char *user, struct pcap_pkthdr *h,
u_char *sp)

int pcap_compile(pcap_t *p, struct bpf_program *fp,
char *str, int optimize, bpf_u_int32 netmask)
int pcap_setfilter(pcap_t *p, struct bpf_program *fp)

u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)

int pcap_datalink(pcap_t *p)
int pcap_snapshot(pcap_t *p)
int pcap_is_swapped(pcap_t *p)
int pcap_major_version(pcap_t *p)
int pcap_minor_version(pcap_t *p)
int pcap_stats(pcap_t *p, struct pcap_stat *ps)
FILE *pcap_file(pcap_t *p)
int pcap_fileno(pcap_t *p)
void pcap_perror(pcap_t *p, char *prefix)
char *pcap_geterr(pcap_t *p)
char *pcap_strerror(int error)

void pcap_close(pcap_t *p)
void pcap_dump_close(pcap_dumper_t *p)

解説
Packet Capture ライブラリは、パケット獲得システムの高レベルなインタフェー スを提供します。このメカニズムでは、ネットワークのすべてのパケットに、 その他のホスト用であってもアクセスできます。

ルーチン
pcap_open_live() は、ネットワークのパケットを調べるためのパケット獲得記述子を取得するた めに用います。 device は、開くネットワークデバイスを指定するストリングです。 snaplen は、獲得する最大バイト数を指定します。 promisc は、インタフェースを無差別モードにするかどうかを指定します(このパラメー タが偽である場合でも、その他の理由でインタフェースが無差別モードになる ことがあります)。 to_ms は、読込みタイムアウトをミリ秒単位で指定します。 ebuf は、エラーテキストを戻すために使用するもので、 pcap_open_live() がエラーになり、 NULL が戻された場合に設定されます。

pcap_open_offline() は、読込み用の「保存ファイル」を開くために呼び出します。 fname は、開くファイルの名前を指定します。このファイルは、 tcpdump(1) と tcpslice(1) で使用するファイルと同じフォーマットになっています。エラーテキストが戻 される場合、 stdin ebuf stdin.ebuf のシノニムで名前「-」が使用されます。これは、 pcap_open_offline() がエラーになり、 NULL が戻される場合に設定されます。

pcap_dump_open() は、書込み用の「保存ファイル」を開くために呼び出します。エラーが発生し た場合は、 stdout NULL のシノニムで名前「-」が戻されます。 p は、 pcap_open_offline() か pcap_open_live() が戻す pcap 構造体です。 fname は、開くファイルの名前を指定します。 NULL が戻された場合は、 pcap_geterr() を使用してエラーテキストを入手できます。

pcap_lookupdev() は、 pcap_open_live() と pcap_lookupnet() での使用に適したネットワークデバイスのポインタを戻します。エラーが発生 した場合は NULL が戻され、 errbuf に適切なエラーメッセージが入ります。

pcap_lookupnet() は、ネットワークデバイス device に関連するネットワーク番号とマスクを決めます。 netp と maskp は、 bpf_u_int32 ポインタです。エラーが発生した場合は -1 が戻されます。この場合は errbuf に適切な エラーメッセージが入ります。

pcap_dispatch() は、パケットの収集と処理に使用します。 cnt は、戻る前に処理するパケットの最大数を指定します。 cnt を -1 にすると、1つのバッファで受け取ったすべてのパケットが処理されま す。 cnt を 0にすると、エラーが発生するか、 EOF に達するか、読込みタイムアウトになる(ライブ読込みを行ない、0以外の読込 みタイムアウトを指定している場合)までパケットが処理されます。 callback は、呼び出すルーチンを指定します。このルーチンの呼び出しに使用する引数 は、 pcap_dispatch() から渡される u_char ポインタ、 pcap_pkthdr 構造体のポインタ(実際のネットワークヘッダとデータの前に置かれる)、パケッ トデータの u_char ポインタです。戻り値は、読み込まれたパケットの数です。「保存ファイル」 で EOF に達するとゼロが戻されます。エラーが発生した場合は -1 が戻されます。 pcap_perror() か pcap_geterr() を使用してエラーテキストを表示してください。

pcap_dump() は、 pcap_dump_open() で開いた「保存ファイル」にパケットを出力します。呼び出し引数が、 pcap_dispatch() での使用に適していることに注意してください。

pcap_compile() は、ストリング str をフィルタプログラムにコンパイルします。 program は、 bpf_program 構造体のポインタで、 pcap_compile() によって値が入力されます。 optimize は、作成されたコードで最適化を実行するかどうかを制御します。 netmask は、ローカルネットのネットマスクを指定します。

pcap_setfilter() は、フィルタプログラムを指定します。 fp は bpf_program 構造体の配列を指すポインタで、一般的には pcap_compile() を呼び 出した結果になっています。エラーが発生した場合は -1 が戻され、エラー が発生しなかった場合は 0が戻されます。

pcap_loop() は、 cnt パケットが処理されるかエラーが発生するまでパケットの読込みが続くことを 除いて、 pcap_dispatch() と同じです。ライブ読込みタイムアウトが発生しても戻りません。 pcap_open_live() に 0以外の読込みタイムアウトを指定して pcap_dispatch() を呼び出すと、タイムアウトが発生した場合に届いたパケットの受信と処理が できます。 cnt に負の値を指定すると、 pcap_loop() は無限にループします(最低でもエラーが発生するまでループします)。

pcap_next() は、次のパケットの u_char ポインタを戻します。

pcap_datalink() は、 DLT_EN10MB などのリンクレイヤタイプを戻します。

pcap_snapshot() は、 pcap_open_live を呼び出した場合に指定されるスナップショットの長さを戻します。

pcap_is_swapped() は、現在の「保存ファイル」が、現在のシステムとは異なるバイトオーダを使 用している場合に真を戻します。

pcap_major_version() は、保存ファイルの書込みに使用した pcap のメジャーバージョン番号を戻します。

pcap_minor_version() は、保存ファイルの書込みに使用した pcap のマイナーバージョン番号を戻します。

pcap_file() は「保存ファイル」の名前を戻します。

int pcap_stats() は 0を戻し、 pcap_stat 構造体にデータを入力します。値は、実行の開始から呼び出しまでのパケット 統計を表します。エラーが発生した場合、または基礎となるパケット獲得でパ ケット統計がサポートされていない場合は -1 が戻されます。 pcap_perror() か pcap_geterr() でエラーテキストを入手してください。

pcap_fileno() は、「保存ファイル」のファイル記述子番号を戻します。

pcap_perror() は、最後の pcap ライブラリエラーのテキストを prefix に続けて stderr に出力します。

pcap_geterr() は、最後の pcap ライブラリエラーに関するエラーテキストを戻します。

pcap_strerror() は、 strerror(1) が使用できない場合に使用できます。

pcap_close() は、 p に関連するファイルを閉じ、リソースの割り振りを解除します。

pcap_dump_close() は「保存ファイル」を閉じます。

関連項目
tcpdump(1), tcpslice(1)

作者
カリフォルニア大学バークレー校、Lawrence Berkeley National Laboratory の Van Jacobson、Craig Leres、Steven McCanne

現行バージョンは、以下の匿名 ftp で使用できます。

    ftp://ftp.ee.lbl.gov/libpcap.tar.Z

バグ
バグを発見した場合は、libpcap@ee.lbl.gov に報告してください。