MAN page from Old RedHat 5.X libpcap-0.4a6-1.i386.rpm

PCAP

Section: C Library Functions (3)
Updated: 18 October 1997
Index

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, 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)

DESCRIPTION

The Packet Capture libraryprovides a high level interface to packet capture systems. All packetson the network, even those destined for other hosts, are accessiblethrough this mechanism.

ROUTINES

pcap_open_live()is used to obtain a packet capture descriptor to lookat packets on the network.deviceis a string that specifies the network device to open.snaplenspecifies the maximum number of bytes to capture.promiscspecifies if the interface is to be put into promiscuous mode.(Note that even if this parameter is false, the interfacecould well be in promiscuous mode for some other reason.)to_msspecifies the read timeout in milliseconds.ebufis used to return error text and is only set whenpcap_open_live()fails and returnsNULL.

pcap_open_offline()is called to open a ``savefile'' for reading.fnamespecifies the name of the file to open. The file hasthe same format as those used bytcpdump(1)andtcpslice(1).The name "-" in a synonym forstdin.ebufis used to return error text and is only set whenpcap_open_offline()fails and returnsNULL.

pcap_dump_open()is called to open a ``savefile'' for writing. The name "-" in a synonymforstdout.NULLis returned on failure.pis apcapstruct as returned bypcap_open_offline()orpcap_open_live().fnamespecifies the name of the file to open.IfNULLis returned,pcap_geterr()can be used to get the error text.

pcap_lookupdev()returns a pointer to a network device suitable for use withpcap_open_live()andpcap_lookupnet().If there is an error,NULLis returned anderrbufis filled in with with an appropriate error message.

pcap_lookupnet()is used to determine the network number and maskassociated with the network devicedevice.Bothnetpandmaskparebpf_u_int32pointers.A return of -1 indicates an error in which caseerrbufis filled in with with an appropriate error message.

pcap_dispatch()is used to collect and process packets.cntspecifies the maximum number of packets to process before returning. Acntof -1 processes all the packets received in one buffer. Acntof 0 processes all packets until an error occurs,EOFis reached, or the read times out (when doing live reads and a non-zeroread timeout is specified).callbackspecifies a routine to be called with three arguments:au_charpointer which is passed in frompcap_dispatch(),a pointer to thepcap_pkthdrstruct (which precede the actual network headers and data),and au_charpointer to the packet data. The number of packets read is returned.Zero is returned whenEOFis reached in a ``savefile.'' A return of -1 indicatesan error in which casepcap_perror()orpcap_geterr()may be used to display the error text.

pcap_dump()outputs a packet to the ``savefile'' opened withpcap_dump_open().Note that its calling arguments are suitable for use withpcap_dispatch().

pcap_compile()is used to compile the stringstrinto a filter program.programis a pointer to abpf_programstruct and is filled in bypcap_compile().optimizecontrols whether optimization on the resulting code is performed.netmaskspecifies the netmask of the local net.

pcap_setfilter()is used to specify a filter program.fpis a pointer to an array ofbpf_programstruct, usually the result of a call topcap_compile().-1is returned on failure;0is returned on success.

pcap_loop()is similar topcap_dispatch()except it keeps reading packets untilcntpackets are processed or an error occurs.It doesnotreturn when live read timeouts occur.Rather, specifying a non-zero read timeout topcap_open_live()and then callingpcap_dispatch()allows the reception and processing of any packets that arrive when thetimeout occurs.A negativecntcausespcap_loop()to loop forever (or at least until an error occurs).

pcap_next()returns au_charpointer to the next packet.

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

pcap_snapshot()returns the snapshot length specified whenpcap_open_livewas called.

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

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

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

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

int pcap_stats()returns 0 and fills in apcap_statstruct. The values represent packet statistics from the start of therun to the time of the call. If there is an error or the under lyingpacket capture doesn't support packet statistics, -1 is returned andthe error text can be obtained withpcap_perror()orpcap_geterr().

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

pcap_perror()prints the text of the last pcap library error onstderr,prefixed byprefix.

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

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

pcap_close()closes the files associated withpand deallocates resources.

pcap_dump_close()closes the ``savefile.''

AUTHORS

Van Jacobson,Craig Leres andSteven McCanne, all of theLawrence Berkeley National Laboratory, University of California, Berkeley, CA.

The current version is available via anonymous ftp:

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

BUGS

Please send bug reports to libpcapAATTee.lbl.gov.

This document was created byman2html,using the manual pages.