Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

PCAP_LOOP(3PCAP)                                                                            PCAP_LOOP(3PCAP)



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

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 processed until another ending condition occurs.

       pcap_dispatch() processes packets from a live capture or ``savefile''  until  cnt  packets  are  pro-cessed, processed,
       cessed,  the end of the current bufferful of packets is reached when doing a live capture, the end of
       the ``savefile'' 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  pack-ets packets
       ets in the file to be processed when reading a ``savefile''.

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

       callback  specifies  a pcap_handler routine to be called with three arguments: 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 rou-tine, routine,
       tine, 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.

RETURN VALUE
       pcap_loop() returns 0 if cnt is exhausted, -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
       filter,  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 packets 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)



                                              24 December 2008                              PCAP_LOOP(3PCAP)