pcap - Packet Capture library


SYNOPSIS

       #include <pcap.h>

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

       char errbuf[PCAP_ERRBUF_SIZE];
       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.

       NOTE:  errbuf  in  pcap_open_live(),  pcap_open_offline(),
       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.   ebuf  is  used  to
       return  error  text  and is only set when pcap_open_live()
       fails and returns NULL.

       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.
       ebuf  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_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

       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
       to the pcap_pkthdr struct (which precede the  actual  net­
       work 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 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() returns a u_char pointer to the next packet.

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

       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.

       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_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,   e.g.
       DLT_EN10MB.

       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 name of the ``savefile.''

       int  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 under lying packet  capture  doesn't  support
       packet  statistics,  -1 is returned and the error text can
       be obtained with pcap_perror() or pcap_geterr().

       ``savefile.''

       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 deal­
       locates 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 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