pcap_loop man page on Archlinux

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

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() is called,	 or  an	 error
       occurs.	 It does not return when live read timeouts occur.  A value of
       -1 or 0 for cnt is equivalent to infinity, so  that  packets  are  pro‐
       cessed 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 buf‐
       fer to be processed when reading a live capture,	 and  causes  all  the
       packets in the file to be processed when reading a ``savefile''.

       (In  older  versions  of libpcap, the behavior when cnt was 0 was unde‐
       fined; different platforms and devices  behaved	differently,  so  code
       that  must work with older versions of libpcap should use -1, not 0, as
       the value of cnt.)

       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()	routine	 when  handed  the pcap_t value also passed to
       pcap_loop() or pcap_dispatch().	 http://www.tcpdump.org/linktypes.html
       lists  the  values  pcap_datalink() can return and describes the packet
       formats that correspond to those values.	 The value it returns will  be
       valid  for all packets received unless and until pcap_set_datalink() 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 even if all devices on the system 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 -1 if an error
       occurs  or  -2 if the loop terminated due to a call to pcap_breakloop()
       before any packets were processed.  It does not return when  live  read
       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
       example,	 they  were discarded because they didn't pass the packet fil‐
       ter, 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.''  It returns -1 if an error occurs or -2 if
       the  loop terminated due to a call to pcap_breakloop() before any pack‐
       ets were processed.  If your application	 uses  pcap_breakloop(),  make
       sure that you explicitly check for -1 and -2, rather than just checking
       for a return value < 0.

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

SEE ALSO
       pcap(3PCAP),	    pcap_geterr(3PCAP),		pcap_breakloop(3PCAP),
       pcap_datalink(3PCAP)

			       24 December 2008		      PCAP_LOOP(3PCAP)
[top]

List of man pages available for Archlinux

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