contrib/libpcap/pcap_breakloop.3pcap

   1 .\" @(#) $Header: /tcpdump/master/libpcap/pcap_breakloop.3pcap,v 1.1.2.3 2008-04-06 03:21:55 guy Exp $
   2 .\"
   3 .\" Copyright (c) 1994, 1996, 1997
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that: (1) source code distributions
   8 .\" retain the above copyright notice and this paragraph in its entirety, (2)
   9 .\" distributions including binary code include the above copyright notice and
  10 .\" this paragraph in its entirety in the documentation or other materials
  11 .\" provided with the distribution, and (3) all advertising materials mentioning
  12 .\" features or use of this software display the following acknowledgement:
  13 .\" ``This product includes software developed by the University of California,
  14 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
  15 .\" the University nor the names of its contributors may be used to endorse
  16 .\" or promote products derived from this software without specific prior
  17 .\" written permission.
  18 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  19 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  20 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  21 .\"
  22 .TH PCAP_BREAKLOOP 3PCAP "5 April 2008"
  23 .SH NAME
  24 pcap_breakloop \- force a pcap_dispatch() or pcap_loop() call to return
  25 .SH SYNOPSIS
  26 .nf
  27 .ft B
  28 #include <pcap/pcap.h>
  29 .ft
  30 .LP
  31 .ft B
  32 void pcap_breakloop(pcap_t *);
  33 .ft
  34 .fi
  35 .SH DESCRIPTION
  36 .B pcap_breakloop()
  37 sets a flag that will force
  38 .B pcap_dispatch()
  39 or
  40 .B pcap_loop()
  41 to return rather than looping; they will return the number of packets
  42 that have been processed so far, or \-2 if no packets have been
  43 processed so far.
  44 .PP
  45 This routine is safe to use inside a signal handler on UNIX or a console
  46 control handler on Windows, as it merely sets a flag that is checked
  47 within the loop.
  48 .PP
  49 The flag is checked in loops reading packets from the OS - a signal by
  50 itself will not necessarily terminate those loops - as well as in loops
  51 processing a set of packets returned by the OS.
  52 .ft B
  53 Note that if you are catching signals on UNIX systems that support
  54 restarting system calls after a signal, and calling pcap_breakloop()
  55 in the signal handler, you must specify, when catching those signals,
  56 that system calls should NOT be restarted by that signal.  Otherwise,
  57 if the signal interrupted a call reading packets in a live capture,
  58 when your signal handler returns after calling pcap_breakloop(), the
  59 call will be restarted, and the loop will not terminate until more
  60 packets arrive and the call completes.
  61 .PP
  62 Note also that, in a multi-threaded application, if one thread is
  63 blocked in
  64 .BR pcap_dispatch() ,
  65 .BR pcap_loop() ,
  66 .BR pcap_next() ,
  67 or
  68 .BR pcap_next_ex() ,
  69 a call to
  70 .B pcap_breakloop()
  71 in a different thread will not unblock that thread; you will need to use
  72 whatever mechanism the OS provides for breaking a thread out of blocking
  73 calls in order to unblock the thread, such as thread cancellation in
  74 systems that support POSIX threads.
  75 .ft R
  76 .PP
  77 Note that
  78 .B pcap_next()
  79 and
  80 .B pcap_next_ex()
  81 will, on some platforms, loop reading packets from the OS; that loop
  82 will not necessarily be terminated by a signal, so
  83 .B pcap_breakloop()
  84 should be used to terminate packet processing even if
  85 .B pcap_next()
  86 or
  87 .B pcap_next_ex()
  88 is being used.
  89 .PP
  90 .B pcap_breakloop()
  91 does not guarantee that no further packets will be processed by
  92 .B pcap_dispatch()
  93 or
  94 .B pcap_loop()
  95 after it is called; at most one more packet might be processed.
  96 .PP
  97 If \-2 is returned from
  98 .B pcap_dispatch()
  99 or
 100 .BR pcap_loop() ,
 101 the flag is cleared, so a subsequent call will resume reading packets.
 102 If a positive number is returned, the flag is not cleared, so a
 103 subsequent call will return \-2 and clear the flag.
 104 .SH SEE ALSO
 105 pcap(3PCAP), pcap_loop(3PCAP), pcap_next_ex(3PCAP)