DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

pcap(3)


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_getnon­
       block(),   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 network 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 capture.  promisc specifies if the interface is  to  be
       put into promiscuous mode.  (Note that even if this param­
       eter 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 timeout in milliseconds.   The  read  timeout  is
       used to arrange that the read not necessarily return imme­
       diately 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() suc­
       ceds; to detect this case the caller should store a  zero-
       length  string  in  errbuf before calling pcap_open_live()
       and display the warning 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
       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_dis­
       patch() 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_find­
       alldevs(), 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 fol­
       lowing 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-readable 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

       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  corre­
                     sponding  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 corre­
                     sponding  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_findalldevs().

       pcap_lookupdev() returns a pointer  to  a  network  device
       suitable  for  use  with pcap_open_live() and pcap_lookup­
       net().  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 associated 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 pro­
       cessed. A cnt of -1 processes all the packets received  in
       one buffer when reading a live capture, or all the packets
       in the file when reading a ``savefile''.  callback  speci­
       fies a routine to be called with three arguments: a u_char
       pointer which is passed in from pcap_dispatch(), a pointer
       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 timeout expires
       before any packets arrive, or if the file  descriptor  for
       the  capture device is in non-blocking mode and no packets
       were available 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_dis­
       patch() will return after the timeout expires.

       pcap_loop()  is similar to pcap_dispatch() except it keeps
       reading packets 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_dis­
       patch() 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  con­
       trols  whether  optimization on the resulting code is per­
       formed.  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.
       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_compile_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_compile().  -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_com­
       pile()  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  cap­
                 tured,  and the PF_ values are for the OS of the
                 machine on which the packets are captured; 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
                 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
                                (UNCOMPRESSED_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 com­
                                pressed TCP/IP datagram header;

                      for UNCOMPRESSED_TCP, the rest of the modi­
                      fied 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
                 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, con­
                      taining a Linux ARPHRD_ value for the  link
                      layer device type;

                      a 2-byte field, in network byte order, con­
                      taining  the  length  of  the  link   layer
                      address  of the sender of the packet (which
                      could be 0);
                      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 pro­
                      tocol type, in network byte order, or  con­
                      taining  1  for Novell 802.3 frames without
                      an 802.2 LLC header or 4 for frames  begin­
                      ning 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 different byte order than the current system.

       pcap_major_version() returns the major number of the  ver­
       sion of the pcap used to write the savefile.

       pcap_minor_version()  returns the minor number of the ver­
       sion of the pcap used to write the savefile.

       pcap_file() returns the standard I/O stream of the ``save­
       file,''    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 represent 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  supported  only on live captures, not on
       ``savefiles''; no statistics are stored in  ``savefiles'',
       so no statistics are available when reading from a ``save­
       file''.

       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
       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 deal­
       locates 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 Cali­
       fornia, 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 enhance­
       ments, etc. to:

              tcpdump-workers@tcpdump.org

       Please send source code contributions, etc. to:

              patches@tcpdump.org


















Man(1) output converted with man2html