contrib/libpcap/pcap_breakloop.3pcap

   1 .\" Copyright (c) 1994, 1996, 1997
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that: (1) source code distributions
   6 .\" retain the above copyright notice and this paragraph in its entirety, (2)
   7 .\" distributions including binary code include the above copyright notice and
   8 .\" this paragraph in its entirety in the documentation or other materials
   9 .\" provided with the distribution, and (3) all advertising materials mentioning
  10 .\" features or use of this software display the following acknowledgement:
  11 .\" ``This product includes software developed by the University of California,
  12 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
  13 .\" the University nor the names of its contributors may be used to endorse
  14 .\" or promote products derived from this software without specific prior
  15 .\" written permission.
  16 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  17 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  18 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  19 .\"
  20 .TH PCAP_BREAKLOOP 3PCAP "8 December 2022"
  21 .SH NAME
  22 pcap_breakloop \- force a pcap_dispatch() or pcap_loop() call to return
  23 .SH SYNOPSIS
  24 .nf
  25 .ft B
  26 #include <pcap/pcap.h>
  27 .ft
  28 .LP
  29 .ft B
  30 void pcap_breakloop(pcap_t *);
  31 .ft
  32 .fi
  33 .SH DESCRIPTION
  34 .BR pcap_breakloop ()
  35 sets a flag that will force
  36 .BR pcap_dispatch (3PCAP)
  37 or
  38 .BR pcap_loop (3PCAP)
  39 to return rather than looping; they will return the number of packets
  40 that have been processed so far, or
  41 .B PCAP_ERROR_BREAK
  42 if no packets have been processed so far.  If the loop is currently
  43 blocked waiting for packets to arrive,
  44 .BR pcap_breakloop ()
  45 will also, on some platforms, wake up the thread that is blocked.  In
  46 this version of libpcap, the only platforms on which a wakeup is caused
  47 by
  48 .BR pcap_breakloop ()
  49 are Linux and Windows, and the wakeup will only be caused when capturing
  50 on network interfaces; it will not be caused on other operating systems,
  51 and will not be caused on any OS when capturing on other types of
  52 devices.
  53 .PP
  54 This routine is safe to use inside a signal handler on UNIX or a console
  55 control handler on Windows, or in a thread other than the one in which
  56 the loop is running, as it merely sets a flag that is checked within the
  57 loop and, on some platforms, performs a signal-safe and thread-safe API
  58 call.
  59 .PP
  60 The flag is checked in loops reading packets from the OS - a signal by
  61 itself will not necessarily terminate those loops - as well as in loops
  62 processing a set of packets returned by the OS.
  63 .ft B
  64 Note that if you are catching signals on UNIX systems that support
  65 restarting system calls after a signal, and calling pcap_breakloop()
  66 in the signal handler, you must specify, when catching those signals,
  67 that system calls should NOT be restarted by that signal.  Otherwise,
  68 if the signal interrupted a call reading packets in a live capture,
  69 when your signal handler returns after calling pcap_breakloop(), the
  70 call will be restarted, and the loop will not terminate until more
  71 packets arrive and the call completes.
  72 .ft R
  73 .PP
  74 .ft B
  75 Note also that, in a multi-threaded application, if one thread is
  76 blocked in pcap_dispatch(), pcap_loop(), pcap_next(3PCAP), or
  77 pcap_next_ex(3PCAP), a call to pcap_breakloop() in a different thread
  78 will only unblock that thread on the platforms and capture devices
  79 listed above.
  80 .PP
  81 If a non-zero packet buffer timeout is set on the
  82 .BR pcap_t ,
  83 and you are capturing on a network interface, the thread will be
  84 unblocked with the timeout expires.  This is not guaranteed to happen
  85 unless at least one packet has arrived; the only platforms on which it
  86 happens are macOS, the BSDs, Solaris 11, AIX, Tru64 UNIX, and Windows.
  87 .PP
  88 If you want to ensure that the loop will eventually be unblocked on any
  89 other platforms, or unblocked when capturing on a device other than a
  90 network interface, you will need to use whatever mechanism the OS
  91 provides for breaking a thread out of blocking calls in order to unblock
  92 the thread, such as thread cancellation or thread signalling in systems
  93 that support POSIX threads.
  94 .ft R
  95 .PP
  96 .ft B
  97 Note that if pcap_breakloop() unblocks the thread capturing packets, and
  98 you are running on a platform that supports packet buffering, there may
  99 be packets in the buffer that arrived before pcap_breakloop() were
 100 called but that weren't yet provided to libpcap, those packets will not
 101 have been processed by pcap_dispatch() or pcap_loop().  If
 102 pcap_breakloop() was called in order to terminate the capture process,
 103 then, in order to process those packets, you would have to call
 104 pcap_dispatch() one time in order to process the last batch of packets.
 105 This may block until the packet buffer timeout expires, so a non-zero
 106 packet buffer timeout must be used.
 107 .ft R
 108 .PP
 109 Note that
 110 .BR pcap_next ()
 111 and
 112 .BR pcap_next_ex ()
 113 will, on some platforms, loop reading packets from the OS; that loop
 114 will not necessarily be terminated by a signal, so
 115 .BR pcap_breakloop ()
 116 should be used to terminate packet processing even if
 117 .BR pcap_next ()
 118 or
 119 .BR pcap_next_ex ()
 120 is being used.
 121 .PP
 122 .BR pcap_breakloop ()
 123 does not guarantee that no further packets will be processed by
 124 .BR pcap_dispatch ()
 125 or
 126 .BR pcap_loop ()
 127 after it is called; at most one more packet might be processed.
 128 .PP
 129 If
 130 .B PCAP_ERROR_BREAK
 131 is returned from
 132 .BR pcap_dispatch ()
 133 or
 134 .BR pcap_loop (),
 135 the flag is cleared, so a subsequent call will resume reading packets.
 136 If a positive number is returned, the flag is not cleared, so a
 137 subsequent call will return
 138 .B PCAP_ERROR_BREAK
 139 and clear the flag.
 140 .SH BACKWARD COMPATIBILITY
 141 .PP
 142 This function became available in libpcap release 0.8.1.
 143 .PP
 144 In releases prior to libpcap 1.10.0,
 145 .BR pcap_breakloop ()
 146 will not wake up a blocked thread on any platform.
 147 .SH SEE ALSO
 148 .BR pcap (3PCAP)