Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PCAP(3)								       PCAP(3)

NAME
       pcap - Packet Capture library

SYNOPSIS
       #include	<pcap.h>

       char errbuf[PCAP_ERRBUF_SIZE];

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

       int pcap_setnonblock(pcap_t *p, int nonblock, char *errbuf);
       int pcap_getnonblock(pcap_t *p, char *errbuf);

       int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf)
       void pcap_freealldevs(pcap_if_t *)
       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)
       void pcap_freecode(struct bpf_program *);

       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
       NOTE:	  errbuf      in      pcap_open_live(),	     pcap_open_dead(),
       pcap_open_offline(), pcap_setnonblock(),	pcap_getnonblock(), pcap_find-
       alldevs(), pcap_lookupdev(), and	pcap_lookupnet() is assumed to be able
       to hold at least	PCAP_ERRBUF_SIZE chars.

       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 net-
       work device to open; on Linux systems with  2.2	or  later  kernels,  a
       device  argument	 of  "any" or NULL can be used to capture packets from
       all interfaces.	snaplen	specifies the maximum number of	bytes to  cap-
       ture.  promisc specifies	if the interface is to be put into promiscuous
       mode.  (Note that even if this parameter	is false, the interface	 could
       well  be	 in  promiscuous  mode	for some other reason.)	 For now, this
       doesn't work on the "any" device; if an argument	of "any"  or  NULL  is
       supplied,  the promisc flag is ignored.	to_ms specifies	the read time-
       out in milliseconds.  The read timeout is used to arrange that the read
       not  necessarily	 return	immediately when a packet is seen, but that it
       wait for	some amount of time to allow more packets  to  arrive  and  to
       read  multiple  packets	from  the OS kernel in one operation.  Not all
       platforms support a read	timeout; on platforms  that  don't,  the  read
       timeout	is  ignored.   errbuf is used to return	error or warning text.
       It will be set to error text when pcap_open_live()  fails  and  returns
       NULL.   errbuf  may  also  be set to warning text when pcap_open_live()
       succeds;	to detect this case the	 caller	 should	 store	a  zero-length
       string  in errbuf before	calling	pcap_open_live() and display the warn-
       ing to the user if errbuf is no longer a	zero-length string.

       pcap_open_dead()	is used	for creating a pcap_t structure	 to  use  when
       calling the other functions in libpcap.	It is typically	used when just
       using libpcap for compiling BPF code.

       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.  errbuf 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 stdout.  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_setnonblock()   puts   a   capture	 descriptor,	opened	  with
       pcap_open_live(), into ``non-blocking'' mode, or	takes it out of	``non-
       blocking'' mode,	depending on whether the nonblock argument is non-zero
       or  zero.  It has no effect on ``savefiles''.  If there is an error, -1
       is returned and errbuf is filled	in with	an appropriate error  message;
       otherwise, 0 is returned.  In ``non-blocking'' mode, an attempt to read
       from the	capture	descriptor with	pcap_dispatch()	will,  if  no  packets
       are  currently  available  to be	read, return 0 immediately rather than
       blocking	waiting	for packets to arrive.	 pcap_loop()  and  pcap_next()
       will not	work in	``non-blocking'' mode.

       pcap_getnonblock()  returns  the	 current ``non-blocking'' state	of the
       capture descriptor; it always returns 0 on ``savefiles''.  If there  is
       an  error,  -1  is returned and errbuf is filled	in with	an appropriate
       error message.

       pcap_findalldevs() constructs a list of network	devices	 that  can  be
       opened  with pcap_open_live().  (Note that there	may be network devices
       that cannot be opened with  pcap_open_live()  by	 the  process  calling
       pcap_findalldevs(),  because,  for example, that	process	might not have
       sufficient privileges to	open them for capturing; if so,	those  devices
       will  not  appear  on the list.)	 alldevsp is set to point to the first
       element of the list; each element of the	list is	of type	pcap_if_t, and
       has the following members:

	      next   if	 not  NULL, a pointer to the next element in the list;
		     NULL for the last element of the list

	      name   a pointer to a string giving a name  for  the  device  to
		     pass to pcap_open_live()

	      description
		     if	 not  NULL, a pointer to a string giving a human-read-
		     able description of the device

	      addresses
		     a pointer to the first element of a list of addresses for
		     the interface

	      flags  interface flags:

		     PCAP_IF_LOOPBACK
			    set	if the interface is a loopback interface

       Each  element  of the list of addresses is of type pcap_addr_t, and has
       the following members:

	      next   if	not NULL, a pointer to the next	element	in  the	 list;
		     NULL for the last element of the list

	      addr   a pointer to a struct sockaddr containing an address

	      netmask
		     if	not NULL, a pointer to a struct	sockaddr that contains
		     the netmask corresponding to the address  pointed	to  by
		     addr

	      broadaddr
		     if	not NULL, a pointer to a struct	sockaddr that contains
		     the  broadcast  address  corresponding  to	 the   address
		     pointed  to by addr; may be null if the interface doesn't
		     support broadcasts

	      dstaddr
		     if	not NULL, a pointer to a struct	sockaddr that contains
		     the  destination  address	corresponding  to  the address
		     pointed to	by addr; may be	null if	the interface isn't  a
		     point-to-point interface

       pcap_freealldevs()  is  used  to	 free  a  list allocated by pcap_find-
       alldevs().

       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	an appropriate error  message.

       pcap_lookupnet()	is used	to determine the network number	and mask asso-
       ciated with the	network	 device	 device.   Both	 netp  and  maskp  are
       bpf_u_int32  pointers.  A return	of -1 indicates	an error in which case
       errbuf is filled	in 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.  This	is not
       a minimum number; when reading a	live capture, only  one	 bufferful  of
       packets	is read	at a time, so fewer than cnt packets may be processed.
       A cnt of	-1 processes all the packets received in one buffer when read-
       ing  a  live  capture,  or  all	the packets in the file	when reading a
       ``savefile''.  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	u_char pointer to the packet data.

       The  number  of	packets	read is	returned.  0 is	returned if no packets
       were read from a	live capture (if, for  example,	 they  were  discarded
       because	they  didn't  pass the packet filter, or if, on	platforms that
       support a read timeout that starts before any packets arrive, the time-
       out  expires  before  any packets arrive, or if the file	descriptor for
       the capture device is in	non-blocking mode and no packets  were	avail-
       able to be read)	or if no more packets are available 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.

       NOTE: when reading a live capture, pcap_dispatch() will not necessarily
       return when the read times out; on some	platforms,  the	 read  timeout
       isn't supported,	and, on	other platforms, the timer doesn't start until
       at least	one packet arrives.  This means	that the read  timeout	should
       NOT  be	used in, for example, an interactive application, to allow the
       packet capture loop to ``poll'' for user	input periodically, as there's
       no  guarantee  that  pcap_dispatch()  will  return  after  the  timeout
       expires.

       pcap_loop() is similar to pcap_dispatch() except	it keeps reading pack-
       ets  until  cnt	packets	are processed or an error occurs.  It does not
       return when live	read timeouts occur.  Rather,  specifying  a  non-zero
       read  timeout  to  pcap_open_live()  and	 then  calling pcap_dispatch()
       allows the reception and	processing of any packets that arrive when the
       timeout	occurs.	 A negative cnt	causes pcap_loop() to loop forever (or
       at least	until an error occurs).

       pcap_next() reads the next packet (by calling  pcap_dispatch()  with  a
       cnt  of	1)  and	 returns  a u_char pointer to the data in that packet.
       (The pcap_pkthdr	struct for that	packet is not supplied.)

       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() or pcap_loop().   If  called  directly,  the  user
       parameter is of type pcap_dumper_t as returned by pcap_dump_open().

       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 result-
       ing code	is performed.  netmask specifies the netmask of	the local net.
       A  return  of  -1 indicates an error in which case pcap_geterr()	may be
       used to display the error text.

       pcap_compile_nopcap() is	similar	to pcap_compile() except that  instead
       of  passing  a  pcap  structure,	 one  passes  the snaplen and linktype
       explicitly.  It is intended to be used for compiling filters for	direct
       BPF  usage, without necessarily having called pcap_open().  A return of
       -1 indicates an error;  the  error  text	 is  unavailable.   (pcap_com-
       pile_nopcap() is	a wrapper around pcap_open_dead(), pcap_compile(), and
       pcap_close(); the latter	three routines can be used directly  in	 order
       to get the error	text for a compilation error.)

       pcap_setfilter()	 is used to specify a filter program.  fp is a pointer
       to a bpf_program	struct,	usually	the result  of	a  call	 to  pcap_com-
       pile().	 -1 is returned	on failure, in which case pcap_geterr()	may be
       used to display the error text; 0 is returned on	success.

       pcap_freecode() is used to free up allocated memory  pointed  to	 by  a
       bpf_program struct generated by pcap_compile() when that	BPF program is
       no longer needed, for example after it has been made the	filter program
       for a pcap structure by a call to pcap_setfilter().

       pcap_datalink()	returns	 the  link layer type; link layer types	it can
       return include:

	    DLT_NULL
		 BSD loopback encapsulation; the link layer header is a	4-byte
		 field,	 in  host  byte	 order,	 containing  a	PF_ value from
		 socket.h for the network-layer	protocol of the	packet

		 Note that ``host byte	order''	 is  the  byte	order  of  the
		 machine on which the packets are captured, and	the PF_	values
		 are for the OS	of the machine on which	the packets  are  cap-
		 tured;	 if  a live capture is being done, ``host byte order''
		 is the	byte order of the machine capturing the	 packets,  and
		 the  PF_  values are those of the OS of the machine capturing
		 the packets, but if a ``savefile'' is being  read,  the  byte
		 order and PF_ values are not necessarily those	of the machine
		 reading the capture file.

	    DLT_EN10MB
		 Ethernet (10Mb, 100Mb,	1000Mb,	and up)

	    DLT_IEEE802
		 IEEE 802.5 Token Ring

	    DLT_ARCNET
		 ARCNET

	    DLT_SLIP
		 SLIP; the link	layer header contains, in order:

		      a	1-byte flag, which is 0	for packets  received  by  the
		      machine and 1 for	packets	sent by	the machine;

		      a	 1-byte	 field,	the upper 4 bits of which indicate the
		      type of packet, as per RFC 1144:

			   0x40	an unmodified IP datagram (TYPE_IP);

			   0x70	an  uncompressed-TCP   IP   datagram   (UNCOM-
				PRESSED_TCP),  with  that byte being the first
				byte of	the raw	IP header on  the  wire,  con-
				taining	 the connection	number in the protocol
				field;

			   0x80	a compressed-TCP IP datagram (COMPRESSED_TCP),
				with  that  byte  being	 the first byte	of the
				compressed TCP/IP datagram header;

		      for  UNCOMPRESSED_TCP,  the  rest	 of  the  modified  IP
		      header,  and  for	 COMPRESSED_TCP, the compressed	TCP/IP
		      datagram header;

		 for a total of	16 bytes; the uncompressed IP datagram follows
		 the header

	    DLT_PPP
		 PPP;  if  the	first  2  bytes	are 0xff and 0x03, it's	PPP in
		 HDLC-like framing, with the PPP header	 following  those  two
		 bytes,	 otherwise  it's  PPP  without framing,	and the	packet
		 begins	with the PPP header

	    DLT_FDDI
		 FDDI

	    DLT_ATM_RFC1483
		 RFC 1483 LLC/SNAP-encapsulated	ATM; the packet	begins with an
		 IEEE 802.2 LLC	header

	    DLT_RAW
		 raw IP; the packet begins with	an IP header

	    DLT_PPP_SERIAL
		 PPP  in HDLC-like framing, as per RFC 1662, or	Cisco PPP with
		 HDLC framing, as per section 4.3.1 of	RFC  1547;  the	 first
		 byte  will  be	0xFF for PPP in	HDLC-like framing, and will be
		 0x0F or 0x8F for Cisco	PPP with HDLC framing

	    DLT_PPP_ETHER
		 PPPoE;	the packet begins with a PPPoE header, as per RFC 2516

	    DLT_C_HDLC
		 Cisco PPP with	HDLC framing, as per section 4.3.1 of RFC 1547

	    DLT_IEEE802_11
		 IEEE 802.11 wireless LAN

	    DLT_LOOP
		 OpenBSD loopback encapsulation; the link layer	 header	 is  a
		 4-byte	 field,	 in network byte order,	containing a PF_ value
		 from OpenBSD's	socket.h for the network-layer protocol	of the
		 packet

		 Note  that, if	a ``savefile'' is being	read, those PF_	values
		 are not necessarily those of the machine reading the  capture
		 file.

	    DLT_LINUX_SLL
		 Linux	"cooked"  capture encapsulation; the link layer	header
		 contains, in order:

		      a	2-byte "packet type", in network byte order, which  is
		      one of:

			   0	packet was sent	to us by somebody else

			   1	packet was broadcast by	somebody else

			   2	packet	was  multicast,	 but not broadcast, by
				somebody else

			   3	packet was sent	by somebody else  to  somebody
				else

			   4	packet was sent	by us

		      a	 2-byte	 field,	 in  network  byte order, containing a
		      Linux ARPHRD_ value for the link layer device type;

		      a	2-byte field, in network byte  order,  containing  the
		      length  of  the  link layer address of the sender	of the
		      packet (which could be 0);

		      an 8-byte	field containing that number of	bytes  of  the
		      link  layer header (if there are more than 8 bytes, only
		      the first	8 are present);

		      a	2-byte field containing	an Ethernet protocol type,  in
		      network  byte  order,  or	 containing 1 for Novell 802.3
		      frames without an	802.2  LLC  header  or	4  for	frames
		      beginning	with an	802.2 LLC header.

	    DLT_LTALK
		 Apple	LocalTalk;  the	 packet	 begins	with an	AppleTalk LLAP
		 header

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

       pcap_is_swapped()  returns true if the current ``savefile'' uses	a dif-
       ferent 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  minor  number of the	version	of the
       pcap used to write the savefile.

       pcap_file() returns the standard	I/O stream of the ``savefile,''	 if  a
       ``savefile'' was	opened with pcap_open_offline(), or NULL, if a network
       device was opened with pcap_open_live().

       pcap_stats() returns 0 and fills	in a pcap_stat struct. The values rep-
       resent  packet  statistics from the start of the	run to the time	of the
       call. If	there is an error or the  underlying  packet  capture  doesn't
       support	packet	statistics,  -1	 is returned and the error text	can be
       obtained	with pcap_perror() or  pcap_geterr().	pcap_stats()  is  sup-
       ported  only  on	live captures, not on ``savefiles''; no	statistics are
       stored in ``savefiles'',	so no statistics are  available	 when  reading
       from a ``savefile''.

       pcap_fileno()  returns  the  file descriptor number from	which captured
       packets are read, if a network device was opened	with pcap_open_live(),
       or -1, if a ``savefile''	was opened with	pcap_open_offline().

       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.	NOTE: the pointer it returns will no longer point to a
       valid error message string after	the pcap_t passed to it	is closed; you
       must use	or copy	the string before closing the pcap_t.

       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)

AUTHORS
       The original authors are:

       Van Jacobson, Craig Leres and  Steven  McCanne,	all  of	 the  Lawrence
       Berkeley	National Laboratory, University	of California, Berkeley, CA.

       The current version is available	from "The Tcpdump Group"'s Web site at

	      http://www.tcpdump.org/

BUGS
       Please send problems, bugs, questions, desirable	enhancements, etc. to:

	      tcpdump-workers@tcpdump.org

       Please send source code contributions, etc. to:

	      patches@tcpdump.org

				3 January 2001			       PCAP(3)

NAME | SYNOPSIS | DESCRIPTION | ROUTINES | SEE ALSO | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=pcap&sektion=3&manpath=FreeBSD+4.7-RELEASE>

home | help