libpcap

NAME

pcap_open_live- open a device for capturing

SYNOPSIS

#include<pcap/pcap.h>

charerrbuf[PCAP_ERRBUF_SIZE];

pcap_t*pcap_open_live(constchar *device,int snaplen,

int promisc,int to_ms,char *errbuf);

DESCRIPTION

pcap_open_live() is used to obtain a packet capture handle to look at packets onthe network.

deviceis a string that specifies the network device to open; on Linuxsystems with 2.2 or later kernels, a device argument of "any"or NULL can be used to capture packets from all interfaces.

snaplenspecifies the snapshot length to be set on the handle. snaplenspecifies the maximum number of bytes tocapture. If this value is less than the size of a packet thatis captured, only the first snaplen bytes of that packet will becaptured and provided as packet data. Avalue of 65535 should be sufficient, on most if not allnetworks, to capture all the data available from the packet.

promiscspecifies if the interface is to be put into promiscuousmode.(Note that even if thisparameter is false, the interface could well be in promiscuous modefor some other reason.) For now, thisdoesn't work on the "any" device; if an argument of "any"or NULL is supplied, the promisc flag is ignored.

to_msspecifies the read timeout in milliseconds. The read timeout is usedto arrange that the read not necessarily return immediately when apacket is seen, but that it wait for some amount of time to allowmore packets to arrive and to read multiple packets from the OSkernel in one operation. Not all platforms support a read timeout; onplatforms that don't, the read timeout is ignored. Azero value for to_ms, on platforms that support a readtimeout, will cause a read to waitforever to allow enough packets toarrive, with no timeout.

RETURNVALUE

pcap_open_live() returns a pcap_t * on success and NULL on failure.

IfNULL is returned, errbufis filled in with an appropriate error message. errbuf may also be set to warning text whenpcap_open_live() succeeds; to detect this case the callershould store a zero-length string in errbuf before callingpcap_open_live() and display the warning to the user if errbuf is nolonger a zero-length string. errbuf is assumed to be able to holdat least PCAP_ERRBUF_SIZE chars.

NAME

pcap_next_ex,pcap_next - read the next packet from a pcap_t handler returned bypcap_open_live()

SYNOPSIS

#include<pcap/pcap.h>

intpcap_next_ex(pcap_t*p,struct pcap_pkthdr **pkt_header,

const u_char **pkt_data);

constu_char *pcap_next(pcap_t*p,struct pcap_pkthdr *h);

DESCRIPTION

Reada packet from an interface or from an offline capture.

Thisfunction is used to retrieve the next available packet, bypassing thecallback method traditionally provided by libpcap.

pcap_next_ex()reads the next packet and returns a success/failure indication.

Ifthe packet was read without problems, the pointer pointed to by thepkt_headerargument is set to point to the pcap_pkthdr struct for the packet, and the pointer pointed to by the pkt_dataargument is set to point to the data in the packet. Thestruct pcap_pkthdr and the packet data are not to be freed by thecaller, and are not guaranteed to be validafter the next call to pcap_next_ex(), pcap_next(), pcap_loop(), orpcap_dispatch(); if the code needs them to remain valid, itmust make a copy of them.

pcap_next()reads the next packet (by callingpcap_dispatch() with a cnt of 1) and returns a u_char pointerto the data in that packet. The packet data is not to be freed bythe caller, and is not guaranteed to be valid after the next call topcap_next_ex(), pcap_next(), pcap_loop(), or pcap_dispatch(); if thecode needs it to remain valid, it must make a copy of it. Thepcap_pkthdr structure pointed to by h is filled in with theappropriate values for the packet.

RETURNVALUE

Thevalue pcap_next_ex() returns can be:

1 ifthe packet was read without problems,

0 ifpackets are being read from a live capture, and thetimeout expired,

-1 ifan error occurred while reading the packet,

-2 ifpackets are being read from a ‘‘savefile’’, and there are nomore packets to read from the savefile. That is to say EOFwas reached.

If -1 is returned, pcap_geterr() or pcap_perror() may be called withp as an argument to fetch or display the error text.

pcap_next() returns a pointer to the packet data on success, and returns NULL

(1)if an error occurred,

(2)or if no packets were read from a live capture (if, for example, theywere discarded because they didn’t pass the packet filter, or if, on platforms that support a read timeout that starts beforeany packets arrive, the timeout expires before any packets arrive, orif the file descriptor for the capture device is in non-blocking modeand no packets were available to be read),

(3)or if no more packets are available in a ‘‘savefile.’’ .

Unfortunately,there is no way to determine whether an error occurred or not.

SEEALSO

DetailedDescription of struct pcap_pkthdr

structpcap_pkthdr {

structtimeval ts; //time stamp of capture

bpf_u_int32caplen; //length of portion present--number of bytes

bpf_u_int32len; //length of this packet (off wire)

};

Headerof a packet in the dump file.

Eachpacket in the dump file is prepended with this generic header.This gets around the problem of different headers for differentpacket interfaces.