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/pcap.h>

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.  It also supports
       saving captured packets to a ``savefile'', and reading packets  from  a
       ``savefile''.

       To open a handle	for a live capture, call pcap_create(),	set the	appro-
       priate options on the handle, and  then	activate  it  with  pcap_acti-
       vate().	 To  open  a  handle for a ``savefile''	with captured packets,
       call pcap_open_offline().  Both pcap_create()  and  pcap_open_offline()
       return  a  pointer  to  a  pcap_t, which	is the handle used for reading
       packets from the	capture	stream or the ``savefile'',  and  for  finding
       out information about the capture stream	or ``savefile''.

       The options that	can be set on a	capture	handle include

       snapshot	length
	      If,  when	 capturing,  you  capture  the	entire contents	of the
	      packet, that requires more CPU time to copy the packet  to  your
	      application,  more  disk and possibly network bandwidth to write
	      the packet data to a file, and  more  disk  space	 to  save  the
	      packet.	If  you	don't need the entire contents of the packet -
	      for example, if you are only interested in the  TCP  headers  of
	      packets  -  you can set the "snapshot length" for	the capture to
	      an appropriate value.  If	the snapshot length is set to snaplen,
	      and  snaplen is less than	the size of a packet that is captured,
	      only the first snaplen bytes of that packet will be captured and
	      provided as packet data.

	      A	 snapshot length of 65535 should be sufficient,	on most	if not
	      all networks, to capture all the data available from the packet.

	      The snapshot length is set with pcap_set_snaplen().

       promiscuous mode
	      On broadcast  LANs  such	as  Ethernet,  if  the	network	 isn't
	      switched,	or if the adapter is connected to a "mirror port" on a
	      switch to	which all packets passing through the switch are sent,
	      a	 network  adapter  receives  all packets on the	LAN, including
	      unicast or multicast packets not sent to a network address  that
	      the network adapter isn't	configured to recognize.

	      Normally,	 the adapter will discard those	packets; however, many
	      network adapters support "promiscuous mode", which is a mode  in
	      which  all packets, even if they are not sent to an address that
	      the adapter recognizes, are provided to the host.	 This is  use-
	      ful  for	passively  capturing traffic between two or more other
	      hosts for	analysis.

	      Note that	even if	an application does not	set promiscuous	 mode,
	      the  adapter  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	setting	of promiscuous mode is
	      ignored.

	      Promiscuous mode is set with pcap_set_promisc().

       monitor mode
	      On IEEE 802.11 wireless LANs, even if an adapter is in promiscu-
	      ous mode,	it will	supply to the host only	frames for the network
	      with which it's associated.  It  might  also  supply  only  data
	      frames,  not management or control frames, and might not provide
	      the 802.11 header	or radio information pseudo-header  for	 those
	      frames.

	      In  "monitor mode", sometimes also called	"rfmon mode" (for "Ra-
	      dio Frequency MONitor"), the adapter will	supply all frames that
	      it  receives,  with  802.11  headers, and	might supply a pseudo-
	      header with radio	information about the frame as well.

	      Note that	in monitor mode	the adapter  might  disassociate  from
	      the  network with	which it's associated, so that you will	not be
	      able to use any wireless networks	with that adapter.  This could
	      prevent  accessing  files	on a network server, or	resolving host
	      names or network addresses, if you are capturing in monitor mode
	      and are not connected to another network with another adapter.

	      Monitor  mode is set with	pcap_set_rfmon(), and pcap_can_set_rf-
	      mon() can	be used	to determine whether an	 adapter  can  be  put
	      into monitor mode.

       read timeout
	      If,  when	 capturing,  packets are delivered as soon as they ar-
	      rive, the	application capturing the packets will be woken	up for
	      each  packet  as	it arrives, and	might have to make one or more
	      calls to the operating system to fetch each packet.

	      If, instead, packets are not delivered as	soon as	 they  arrive,
	      but are delivered	after a	short delay (called a "read timeout"),
	      more than	one packet can be accumulated before the  packets  are
	      delivered,  so  that  a single wakeup would be done for multiple
	      packets, and each	set of calls  made  to	the  operating	system
	      would  supply  multiple  packets,	 rather	 than a	single packet.
	      This reduces the per-packet CPU overhead if packets are arriving
	      at a high	rate, increasing the number of packets per second that
	      can be captured.

	      The read timeout is required so that an application  won't  wait
	      for  the	operating  system's  capture  buffer to	fill up	before
	      packets are delivered; if	packets	are arriving slowly, that wait
	      could take an arbitrarily	long period of time.

	      Not  all	platforms  support  a  read timeout; on	platforms that
	      don't, the read timeout is ignored.  A zero value	for the	 time-
	      out, on platforms	that support a read timeout, will cause	a read
	      to wait forever to allow enough packets to arrive, with no time-
	      out.

	      NOTE:  the  read timeout cannot be used to cause calls that read
	      packets to return	within a limited period	of time,  because,  on
	      some  platforms, the read	timeout	isn't supported, and, on other
	      platforms, the timer doesn't start until at least	one packet ar-
	      rives.  This means that the read timeout should NOT be used, for
	      example, in an interactive application to	allow the packet  cap-
	      ture loop	to ``poll'' for	user input periodically, as there's no
	      guarantee	that a call reading  packets  will  return  after  the
	      timeout expires even if no packets have arrived.

	      The read timeout is set with pcap_set_timeout().

       buffer size
	      Packets  that  arrive  for  a capture are	stored in a buffer, so
	      that they	do not have to be read by the application as  soon  as
	      they arrive.  On some platforms, the buffer's size can be	set; a
	      size that's too small could mean that, if	too many  packets  are
	      being  captured and the snapshot length doesn't limit the	amount
	      of data that's buffered, packets could be	dropped	if the	buffer
	      fills  up	before the application can read	packets	from it, while
	      a	size that's too	large could use	 more  non-pageable  operating
	      system  memory  than  is necessary to prevent packets from being
	      dropped.

	      The buffer size is set with pcap_set_buffer_size().

       Reading packets from a network interface	may require that you have spe-
       cial privileges:

       Under SunOS 3.x or 4.x with NIT or BPF:
	      You must have read access	to /dev/nit or /dev/bpf*.

       Under Solaris with DLPI:
	      You  must	 have  read/write access to the	network	pseudo device,
	      e.g.  /dev/le.  On at least some versions	of  Solaris,  however,
	      this  is not sufficient to allow tcpdump to capture in promiscu-
	      ous mode;	on those versions of Solaris, you must be root,	or the
	      application  capturing packets must be installed setuid to root,
	      in order to capture in promiscuous mode.	 Note  that,  on  many
	      (perhaps	all)  interfaces,  if you don't	capture	in promiscuous
	      mode, you	will not see any outgoing packets, so  a  capture  not
	      done in promiscuous mode may not be very useful.

	      In  newer	 versions  of  Solaris,	 you  must have	been given the
	      net_rawaccess privilege; this is both necessary  and  sufficient
	      to  give	you  access to the network pseudo-device - there is no
	      need to change the privileges on that device.   A	 user  can  be
	      given  that  privilege by, for example, adding that privilege to
	      the user's defaultpriv key with the usermod (1M) command.

       Under HP-UX with	DLPI:
	      You must be root or the application capturing  packets  must  be
	      installed	setuid to root.

       Under IRIX with snoop:
	      You  must	 be  root or the application capturing packets must be
	      installed	setuid to root.

       Under Linux:
	      You must be root or the application capturing  packets  must  be
	      installed	 setuid	to root	(unless	your distribution has a	kernel
	      that supports capability bits such as CAP_NET_RAW	 and  code  to
	      allow  those  capability bits to be given	to particular accounts
	      and to cause those bits to be set	on a user's initial  processes
	      when  they  log  in, in which case you  must have	CAP_NET_RAW in
	      order to capture and CAP_NET_ADMIN to enumerate network  devices
	      with, for	example, the -D	flag).

       Under ULTRIX and	Digital	UNIX/Tru64 UNIX:
	      Any  user	 may  capture  network traffic.	 However, no user (not
	      even the super-user) can capture in promiscuous mode on  an  in-
	      terface unless the super-user has	enabled	promiscuous-mode oper-
	      ation on that interface using pfconfig(8), and no	user (not even
	      the  super-user) can capture unicast traffic received by or sent
	      by the machine on	an interface unless the	super-user has enabled
	      copy-all-mode  operation	on  that  interface using pfconfig, so
	      useful packet capture on an interface probably requires that ei-
	      ther  promiscuous-mode or	copy-all-mode operation, or both modes
	      of operation, be enabled on that interface.

       Under BSD (this includes	Mac OS X):
	      You must have read access	to /dev/bpf*  on  systems  that	 don't
	      have  a  cloning	BPF device, or to /dev/bpf on systems that do.
	      On BSDs with a devfs (this includes Mac OS X),  this  might  in-
	      volve more than just having somebody with	super-user access set-
	      ting the ownership or permissions	on the BPF devices - it	 might
	      involve  configuring  devfs  to set the ownership	or permissions
	      every time the system is booted, if  the	system	even  supports
	      that;  if	 it  doesn't support that, you might have to find some
	      other way	to make	that happen at boot time.

       Reading a saved packet file doesn't require special privileges.

       To  open	  a   ``savefile``   to	  which	  to   write   packets,	  call
       pcap_dump_open().   It  returns	a pointer to a pcap_dumper_t, which is
       the handle used for writing packets to the ``savefile''.

       Packets are read	with pcap_dispatch() or	pcap_loop(), which process one
       or  more	 packets,  calling a callback routine for each packet, or with
       pcap_next() or pcap_next_ex(), which return the next packet.  The call-
       back  for  pcap_dispatch()  and	pcap_loop() is supplied	a pointer to a
       struct pcap_pkthdr, which includes the following	members:

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

       pcap_next_ex()  supplies	 that  pointer	through	 a  pointer  argument.
       pcap_next() is passed an	argument that points to	a  struct  pcap_pkthdr
       structure, and fills it in.

       The  callback  is  also	supplied  a  const u_char pointer to the first
       caplen (as given	in the struct pcap_pkthdr a pointer to which is	passed
       to  the	callback  routine)  bytes of data from the packet.  This won't
       necessarily be the entire packet; to capture  the  entire  packet,  you
       will   have   to	  provide   a  value  for  snaplen  in	your  call  to
       pcap_open_live()	that is	sufficiently large to get all of the  packet's
       data  -	a  value of 65535 should be sufficient on most if not all net-
       works).	When reading from a ``savefile'', the snapshot	length	speci-
       fied  when  the	capture	 was performed will limit the amount of	packet
       data available.	pcap_next() returns that pointer; pcap_next_ex()  sup-
       plies that pointer through a pointer argument.

BACKWARDS COMPATIBILITY
       In  versions of libpcap prior to	1.0, the pcap.h	header file was	not in
       a pcap directory	on most	platforms; if you are writing  an  application
       that  must  work	on versions of libpcap prior to	1.0, include <pcap.h>,
       which  will  include  <pcap/pcap.h>  for	 you,  rather  than  including
       <pcap/pcap.h>.

       pcap_create()  and  pcap_activate()  were  not available	in versions of
       libpcap prior to	1.0; if	you are	writing	an application that must  work
       on versions of libpcap prior to 1.0, either use pcap_open_live()	to get
       a handle	for a live capture or, if you want to be able to use the addi-
       tional capabilities offered by using pcap_create() and pcap_activate(),
       use an autoconf(1) script or some other configuration script  to	 check
       whether	the  libpcap  1.0 APIs are available and use them only if they
       are.

SEE ALSO
       autoconf(1),  tcpdump(1),  tcpslice(1),	pcap-filter(7),	  pfconfig(8),
       usermod(1M)

AUTHORS
       The original authors of libpcap 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@lists.tcpdump.org

				 4 April 2008			       PCAP(3)

NAME | SYNOPSIS | DESCRIPTION | BACKWARDS COMPATIBILITY | 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=FreeBSD+8.2-RELEASE>

home | help