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

FreeBSD Manual Pages

  
 
  

home | help
PCAP_LOOP(3PCAP)					      PCAP_LOOP(3PCAP)

NAME
       pcap_loop, pcap_dispatch	- process packets from a live capture or save-
       file

SYNOPSIS
       #include	<pcap/pcap.h>

       typedef void (*pcap_handler)(u_char *user, const	struct pcap_pkthdr *h,
	   const u_char	*bytes);
       int pcap_loop(pcap_t *p,	int cnt,
	   pcap_handler	callback, u_char *user);
       int pcap_dispatch(pcap_t	*p, int	cnt,
	   pcap_handler	callback, u_char *user);

DESCRIPTION
       pcap_loop() processes packets from a live capture or ``savefile'' until
       cnt  packets are	processed, the end of the ``savefile'' is reached when
       reading from a ``savefile'', pcap_breakloop(3PCAP) is called, or	an er-
       ror occurs.  It does not	return when live packet	buffer timeouts	occur.
       A value of -1 or	0 for cnt is equivalent	to infinity, so	 that  packets
       are processed until another ending condition occurs.

       pcap_dispatch()	processes  packets from	a live capture or ``savefile''
       until cnt packets are processed,	the end	of the	current	 bufferful  of
       packets	is  reached  when doing	a live capture,	the end	of the ``save-
       file'' is reached when reading from a ``savefile'', pcap_breakloop() is
       called, or an error occurs.  Thus, when doing a live  capture,  cnt  is
       the maximum number of packets to	process	before returning, but 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  value	 of  -1	 or  0	for cnt	causes all the packets received	in one
       buffer to be processed when reading a live capture, and causes all  the
       packets in the file to be processed when	reading	a ``savefile''.

       Note  that,  when  doing	 a live	capture	on some	platforms, if the read
       timeout expires when there are no  packets  available,  pcap_dispatch()
       will  return  0,	 even  when  not in non-blocking mode, as there	are no
       packets to process.  Applications should	be prepared for	this  to  hap-
       pen, but	must not rely on it happening.

       callback	specifies a pcap_handler routine to be called with three argu-
       ments:  a  u_char  pointer  which  is  passed  in  the user argument to
       pcap_loop() or pcap_dispatch(),	a  const  struct  pcap_pkthdr  pointer
       pointing	 to  the  packet  time	stamp  and lengths, and	a const	u_char
       pointer to the first caplen (as given  in  the  struct  pcap_pkthdr,  a
       pointer	to which is passed to the callback routine) bytes of data from
       the packet.  The	struct pcap_pkthdr and the packet data are not	to  be
       freed by	the callback routine, and are not guaranteed to	be valid after
       the  callback routine returns; if the code needs	them to	be valid after
       the callback, it	must make a copy of them.

       The bytes of data from the packet begin with a link-layer header.   The
       format of the link-layer	header is indicated by the return value	of the
       pcap_datalink(3PCAP)  routine  when handed the pcap_t value also	passed
       to  pcap_loop()	or   pcap_dispatch().	 https://www.tcpdump.org/link-
       types.html  lists  the  values pcap_datalink() can return and describes
       the packet formats that correspond to those values.  The	value  it  re-
       turns  will  be	valid  for  all	 packets  received  unless  and	 until
       pcap_set_datalink(3PCAP)	 is  called;  after  a	successful   call   to
       pcap_set_datalink(),  all  subsequent  packets  will  have a link-layer
       header of the type specified by the link-layer header type value	passed
       to pcap_set_datalink().

       Do NOT assume that the packets for a given capture or ``savefile`` will
       have any	given link-layer header	type, such as DLT_EN10MB for Ethernet.
       For example, the	"any" device on	Linux will have	 a  link-layer	header
       type of DLT_LINUX_SLL or	DLT_LINUX_SLL2 even if all devices on the sys-
       tem  at	the  time the "any" device is opened have some other data link
       type, such as DLT_EN10MB	for Ethernet.

RETURN VALUE
       pcap_loop() returns 0 if	cnt is exhausted or if,	when  reading  from  a
       ``savefile'',  no  more	packets	 are  available.   It returns PCAP_ER-
       ROR_BREAK if the	loop terminated	due to a call to pcap_breakloop()  be-
       fore  any packets were processed, PCAP_ERROR_NOT_ACTIVATED if called on
       a capture handle	that has been created but not activated, or PCAP_ERROR
       if another error	occurs.	 It does not return when  live	packet	buffer
       timeouts	occur; instead,	it attempts to read more packets.

       pcap_dispatch()	returns	 the  number  of packets processed on success;
       this can	be 0 if	no packets were	read from a live capture (if, for  ex-
       ample,  they were discarded because they	didn't pass the	packet filter,
       or if, on platforms that	support	a packet buffer	 timeout  that	starts
       before  any  packets arrive, the	timeout	expires	before any packets ar-
       rive, or	if the file descriptor for the capture device is in non-block-
       ing mode	and no packets were available to be read) or if	no more	 pack-
       ets are available in a ``savefile.'' It returns PCAP_ERROR_BREAK	if the
       loop  terminated	 due  to a call	to pcap_breakloop() before any packets
       were processed, PCAP_ERROR_NOT_ACTIVATED	if called on a capture	handle
       that has	been created but not activated,	or PCAP_ERROR if another error
       occurs.	 If your application uses pcap_breakloop(), make sure that you
       explicitly check	for PCAP_ERROR and PCAP_ERROR_BREAK, rather than  just
       checking	for a return value < 0.

       If PCAP_ERROR is	returned, pcap_geterr(3PCAP) or	pcap_perror(3PCAP) may
       be called with p	as an argument to fetch	or display the error text.

BACKWARD COMPATIBILITY
       In libpcap versions before 1.5.0, the behavior when cnt was 0 was unde-
       fined;  different  platforms  and  devices behaved differently, so code
       that must work with these versions of libpcap should use	-1, not	0,  as
       the value of cnt.

SEE ALSO
       pcap(3PCAP)

				 5 March 2022		      PCAP_LOOP(3PCAP)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pcap_loop&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help