PCAP(3)

NAME
pcap - Packet Capture library

SYNOPSIS
#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, u_long *netp,
u_long *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_immediate(pcap_t *p)

int pcap_compile(pcap_t *p, struct bpf_program *fp,
char *str, int optimize, u_long 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)

DESCRIPTION
The Packet Capture library provides a high level interface to packet capture systems. All packets on the network, even those destined for other hosts, are accessible through this mechanism.

ROUTINES
pcap_open_live() is used to obtain a packet capture descriptor to look at packets on the network. device is a string that specifies the network device to open. snaplen specifies the maximum number of bytes to capture. to_ms specifies the read timeout in milliseconds. ebuf is used to return error text and is only set when pcap_open_live() fails and returns NULL.

pcap_open_offline() is called to open a ``savefile'' for reading. fname specifies the name of the file to open. The file has the same format as those used by tcpdump(1) and tcpslice(1). The name "-" in a synonym for stdin. ebuf is used to return error text and is only set when pcap_open_offline() fails and returns NULL.

pcap_dump_open() is called to open a ``savefile'' for writing. The name "-" in a synonym for stdin. NULL is returned on failure. p is a pcap struct as returned by pcap_open_offline() or pcap_open_live(). fname specifies the name of the file to open. If NULL is returned, pcap_geterr() can be used to get the error text.

pcap_lookupdev() returns a pointer to a network device suitable for use with pcap_open_live() and pcap_lookupnet(). If there is an error, NULL is returned and errbuf is filled in with with an appropriate error message.

pcap_lookupnet() is used to determine the network number and mask associated with the network device device. Both netp and maskp are u_long pointers. A return of -1 indicates an error in which case errbuf is filled in with with an appropriate error message.

pcap_dispatch() is used to collect and process packets. cnt specifies the maximum number of packets to process before returning. A cnt of -1 processes all the packets received in one buffer. A cnt of 0 processes all packets until an error occurs (or EOF is reached). callback specifies a routine to be called with three arguments: a u_char pointer which is passed in from pcap_dispatch(), a pointer to the pcap_pkthdr struct (which precede the actual network headers and data), and a length. The number of packets read is returned. Zero is returned when EOF is reached in a ``savefile.'' A return of -1 indicates an error in which case pcap_perror() or pcap_geterr() may be used to display the error text.

pcap_dump() outputs a packet to the ``savefile'' opened with pcap_dump_open(). Note that its calling arguments are suitable for use with pcap_dispatch(). (??? this guy is kind of weird.)

pcap_immediate() sets ``immediate'' mode. If this isn't supported by the under lying packet capture, -1 is returned and the error text can be obtained with pcap_perror() or pcap_geterr().

pcap_compile() is used to compile the string str into a filter program. program is a pointer to a bpf_program struct and is filled in by pcap_compile(). optimize controls whether optimization on the resulting code is performed. netmask specifies the netmask of the local net.

pcap_setfilter() is used to specify the a filter program. fp is a pointer to an array of bpf_program struct, usually the result of a call to pcap_compile().

pcap_loop() is similar to pcap_dispatch() except it keeps reading packets until cnt packets are processed or an error occurs. A negative cnt causes pcap_loop() to loop forever (or at least until an error occurs).

pcap_next() returns a u_char pointer to the next packet.

pcap_datalink() returns the link layer type, e.g. DLT_EN10MB.

pcap_snapshot() returns the snapshot length specified when pcap_open_live was called.

pcap_is_swapped() returns true if the current ``savefile'' uses a different byte order than the current system.

pcap_major_version() returns the major number of the version of the pcap used to write the savefile.

pcap_minor_version() returns the major number of the version of the pcap used to write the savefile.

pcap_file() returns the name of the ``savefile.''

int pcap_stats() returns 0 and fills in a pcap_stat struct with packet statistics. If there is an error or the under lying packet capture doesn't support packet statistics, -1 is returned and the error text can be obtained with pcap_perror() or pcap_geterr().

pcap_fileno() returns the file descriptor number of the ``savefile.''

pcap_perror() prints the text of the last pcap library error on stderr, prefixed by prefix.

pcap_geterr() returns the error text pertaining to the last pcap library error.

pcap_strerror() is provided in case strerror(1) isn't available.

pcap_close() closes the files associated with p and deallocates resources.

pcap_dump_close() closes the ``savefile.''

SEE ALSO
tcpdump(1), tcpslice(1)

BUGS

HISTORY