PCAP(3)                                                                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
              "Radio  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_rfmon() 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
              arrive,  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
              arrives.  This means that the read timeout should NOT  be  used,
              for  example,  in an interactive application to allow the packet
              capture 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
              interface unless the  super-user  has  enabled  promiscuous-mode
              operation  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  pfcon-
              fig,  so useful packet capture on an interface probably requires
              that either 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
              involve more than just having somebody  with  super-user  access
              setting  the  ownership  or  permissions on the BPF devices - it
              might involve configuring devfs to set the ownership or  permis-
              sions  every  time the system is booted, if the system even sup-
              ports 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(8),  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)

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen