*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> pcap_freecode (3)              



NAME    [Toc]    [Back]

     pcap - Packet Capture library

SYNOPSIS    [Toc]    [Back]

     #include <pcap.h>

     pcap_t *
     pcap_open_live(char *device, int snaplen, int  promisc,  int
             char *errbuf);

     pcap_t *
     pcap_open_offline(char *fname, char *errbuf);

     pcap_dumper_t *
     pcap_dump_open(pcap_t *p, char *fname);

     char *
     pcap_lookupdev(char *errbuf);

     pcap_lookupnet(char  *device, bpf_u_int32 *netp, bpf_u_int32
             char *errbuf);

     pcap_dispatch(pcap_t *p,  int  cnt,  pcap_handler  callback,
u_char *user);

     pcap_loop(pcap_t  *p, int cnt, pcap_handler callback, u_char

     pcap_dump(u_char *user, struct pcap_pkthdr *h, u_char *sp);

     pcap_inject(pcap_t *p, void *, size_t);

     pcap_compile(pcap_t *p, struct bpf_program *fp,  char  *str,
int optimize,
             bpf_u_int32 netmask);

     pcap_setfilter(pcap_t *p, struct bpf_program *fp);

     pcap_freecode(struct bpf_program *fp);

     u_char *
     pcap_next(pcap_t *p, struct pcap_pkthdr *h);

     pcap_datalink(pcap_t *p);

     pcap_snapshot(pcap_t *p);

     pcap_is_swapped(pcap_t *p);

     pcap_major_version(pcap_t *p);

     pcap_minor_version(pcap_t *p);

     pcap_stats(pcap_t *p, struct pcap_stat *ps);

     FILE *
     pcap_file(pcap_t *p);

     pcap_fileno(pcap_t *p);

     pcap_perror(pcap_t *p, char *prefix);

     char *
     pcap_geterr(pcap_t *p);

     char *
     pcap_strerror(int error);

     pcap_close(pcap_t *p);

     pcap_dump_close(pcap_dumper_t *p);

DESCRIPTION    [Toc]    [Back]

     pcap  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    [Toc]    [Back]

     Note:   errbuf   in  pcap_open_live(),  pcap_open_offline(),
     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.  snaplen specifies  the  maximum  number  of
bytes to capture.
   promisc specifies if the interface is to be put into
     mode.  (Note that even if this parameter is false,  the  interface could
     well  be  in promiscuous mode for some other reason.)  to_ms
specifies the
     read timeout in milliseconds.  errbuf is used to return  error text and is
     only set when pcap_open_live() fails and returns NULL.

     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).   The name `-' is a synonym for
stdin.  errbuf
     is  used  to  return  error  text  and  is  only  set   when
     fails and returns NULL.

     pcap_dump_open()  is called to open a ``savefile'' for writing. The name
     `-' is a synonym for stdin.  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_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 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
     the maximum number of packets to process  before  returning.
A cnt of -1
     processes  all the packets received in one buffer.  A cnt of
0 processes
     all packets until an error occurs, EOF is  reached,  or  the
read times out
     (when doing live reads and a non-zero read timeout is specified).
     callback specifies 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 network headers
and data),
     and  a  u_char  pointer  to  the packet data.  The number of
packets read is
     returned.  Zero is returned when EOF is reached 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.

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

     pcap_inject()  uses  write(2) to inject a raw packet through
the network

     pcap_compile() is used to compile the string str into a filter program.
     fp is a pointer to a bpf_program struct and is filled in by
     pcap_compile().   optimize  controls whether optimization on
the resulting
     code is performed.  netmask specifies the netmask of the local net.

     pcap_setfilter() is used to specify a filter program.  fp is
a pointer to
     an array of bpf_program struct, usually the result of a call
     pcap_compile().  -1 is returned on failure; 0 is returned on

     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_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_datalink()   returns   the   link   layer  type,  e.g.,

     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 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 stream associated with the savefile.

     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_fileno() returns the  file  descriptor  number  of  the

     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

     pcap_strerror() is provided in case strerror(3) isn't available.

     pcap_close() closes the files associated with p and  deallocates resources.

     pcap_dump_close() closes the savefile.

SEE ALSO    [Toc]    [Back]


AUTHORS    [Toc]    [Back]

     Van  Jacobson,  Craig  Leres  and Steven McCanne, all of the
Lawrence Berkeley
 National Laboratory, University of California, Berkeley,

BUGS    [Toc]    [Back]

     Please send bug reports to libpcap@ee.lbl.gov.

OpenBSD      3.6                           July      5,      1999
[ Back ]
 Similar pages
Name OS Title
vidtomem IRIX Video Library capture single frame tool
ipf FreeBSD alters packet filtering lists for IP packet input and output
libalias FreeBSD packet aliasing library for masquerading and network address translation
bktr OpenBSD video capture driver
brooktree FreeBSD video capture driver
bktr FreeBSD video capture driver
meteor FreeBSD video capture driver
tt_error HP-UX capture ToolTalk function errors
cdplayer IRIX play and capture audio CDs and DAT tapes
snoop IRIX capture and inspect network packets
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service