pcap man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

PCAP(3)								       PCAP(3)

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

ROUTINES
       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  net‐
       work  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 cap‐
       ture.  promisc specifies if the interface is to be put into promiscuous
       mode.   (Note that even if this parameter 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	 time‐
       out in milliseconds.  The read timeout is used to arrange that the read
       not necessarily return immediately 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(1) and tcpslice(1).  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_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 asso‐
       ciated 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 processed.
       A cnt of -1 processes all the packets received in one buffer when read‐
       ing  a  live  capture,  or  all	the packets in the file when reading a
       ``savefile''.  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.  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 time‐
       out  expires  before  any packets arrive, or if the file descriptor for
       the capture device is in non-blocking mode and no packets  were	avail‐
       able 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_dispatch()  will  return  after  the  timeout
       expires.

       pcap_loop() is similar to pcap_dispatch() except it keeps reading pack‐
       ets  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().

       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 controls whether optimization on the  result‐
       ing code is performed.  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_com‐
       pile_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_com‐
       pile().	-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_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_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 dif‐
       ferent 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 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().

       pcap_fileno() returns the file descriptor number of the ``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  deallocates
       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 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@tcpdump.org

       Please send source code contributions, etc. to:

	      patches@tcpdump.org

				3 January 2001			       PCAP(3)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net