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

FreeBSD Manual Pages

  
 
  

home | help
PCAP(3)			   Library Functions Manual		       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_off-
       line(),	pcap_setnonblock(),  pcap_getnonblock(),   pcap_findalldevs(),
       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(8) and tcpslice(8).  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
       const struct pcap_pkthdr	pointer	to a structure with the	following mem-
       bers:

	      ts     a struct timeval containing the time when the packet  was
		     captured

	      caplen a	bpf_u_int32  giving  the number	of bytes of the	packet
		     that are available	from the capture

	      len    a bpf_u_int32 giving the length of	the packet,  in	 bytes
		     (which  might  be more than the number of bytes available
		     from the capture, if the length of	the packet  is	larger
		     than the maximum number of	bytes to capture)

       and a const 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).	 A negative number is returned	on  an
       error; 0	is returned if cnt is exhausted.

       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(8), tcpslice(8)

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:
<https://www.freebsd.org/cgi/man.cgi?query=pcap&sektion=3&manpath=Red+Hat+Linux%2fi386+9>

home | help