Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PCAP(3)								       PCAP(3)

       pcap - Packet Capture library

       #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)

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

       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

       pcap_dump_close() closes	the ``savefile.''

       tcpdump(1), tcpslice(1)

       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

       Please send problems, bugs, questions, desirable	enhancements, etc. to:

       Please send source code contributions, etc. to:

				3 January 2001			       PCAP(3)


Want to link to this manual page? Use this URL:

home | help