From 3f1edad4e6ba0a7876750aea55507fae14d8badf Mon Sep 17 00:00:00 2001
From: Milan Lenco <milan.lenco@pantheon.tech>
Date: Wed, 11 Oct 2017 16:40:58 +0200
Subject: ODPM 266: Go-libmemif + 2 examples.

Change-Id: Icdb9b9eb2314eff6c96afe7996fcf2728291de4a
Signed-off-by: Milan Lenco <milan.lenco@pantheon.tech>
---
 vendor/github.com/google/gopacket/pcap/doc.go | 106 ++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 vendor/github.com/google/gopacket/pcap/doc.go

(limited to 'vendor/github.com/google/gopacket/pcap/doc.go')

diff --git a/vendor/github.com/google/gopacket/pcap/doc.go b/vendor/github.com/google/gopacket/pcap/doc.go
new file mode 100644
index 0000000..5bf8d86
--- /dev/null
+++ b/vendor/github.com/google/gopacket/pcap/doc.go
@@ -0,0 +1,106 @@
+// Copyright 2012 Google, Inc. All rights reserved.
+//
+// Use of this source code is governed by a BSD-style license
+// that can be found in the LICENSE file in the root of the source
+// tree.
+
+/*
+Package pcap allows users of gopacket to read packets off the wire or from
+pcap files.
+
+This package is meant to be used with its parent,
+http://github.com/google/gopacket, although it can also be used independently
+if you just want to get packet data from the wire.
+
+Reading PCAP Files
+
+The following code can be used to read in data from a pcap file.
+
+ if handle, err := pcap.OpenOffline("/path/to/my/file"); err != nil {
+   panic(err)
+ } else {
+   packetSource := gopacket.NewPacketSource(handle, handle.LinkType())
+   for packet := range packetSource.Packets() {
+     handlePacket(packet)  // Do something with a packet here.
+   }
+ }
+
+Reading Live Packets
+
+The following code can be used to read in data from a live device, in this case
+"eth0".
+
+ if handle, err := pcap.OpenLive("eth0", 1600, true, pcap.BlockForever); err != nil {
+   panic(err)
+ } else if err := handle.SetBPFFilter("tcp and port 80"); err != nil {  // optional
+   panic(err)
+ } else {
+   packetSource := gopacket.NewPacketSource(handle, handle.LinkType())
+   for packet := range packetSource.Packets() {
+     handlePacket(packet)  // Do something with a packet here.
+   }
+ }
+
+Inactive Handles
+
+Newer PCAP functionality requires the concept of an 'inactive' PCAP handle.
+Instead of constantly adding new arguments to pcap_open_live, users now call
+pcap_create to create a handle, set it up with a bunch of optional function
+calls, then call pcap_activate to activate it.  This library mirrors that
+mechanism, for those that want to expose/use these new features:
+
+  inactive, err := pcap.NewInactiveHandle(deviceName)
+  if err != nil {
+    log.Fatal(err)
+  }
+  defer inactive.CleanUp()
+
+  // Call various functions on inactive to set it up the way you'd like:
+  if err = inactive.SetTimeout(time.Minute); err != nil {
+    log.Fatal(err)
+  } else if err = inactive.SetTimestampSource("foo"); err != nil {
+    log.Fatal(err)
+  }
+
+  // Finally, create the actual handle by calling Activate:
+  handle, err := inactive.Activate()  // after this, inactive is no longer valid
+  if err != nil {
+    log.Fatal(err)
+  }
+  defer handle.Close()
+
+  // Now use your handle as you see fit.
+
+PCAP Timeouts
+
+pcap.OpenLive and pcap.SetTimeout both take timeouts.
+If you don't care about timeouts, just pass in BlockForever,
+which should do what you expect with minimal fuss.
+
+A timeout of 0 is not recommended.  Some platforms, like Macs
+(http://www.manpages.info/macosx/pcap.3.html) say:
+  The read timeout is used to arrange that the read not necessarily return
+  immediately when a packet is seen, but that it wait for some amount of time
+  to allow more packets to arrive and to read multiple packets from the OS
+  kernel in one operation.
+This means that if you only capture one packet, the kernel might decide to wait
+'timeout' for more packets to batch with it before returning.  A timeout of
+0, then, means 'wait forever for more packets', which is... not good.
+
+To get around this, we've introduced the following behavior:  if a negative
+timeout is passed in, we set the positive timeout in the handle, then loop
+internally in ReadPacketData/ZeroCopyReadPacketData when we see timeout
+errors.
+
+PCAP File Writing
+
+This package does not implement PCAP file writing.  However, gopacket/pcapgo
+does!  Look there if you'd like to write PCAP files.
+
+Note For Windows 10 Users
+
+If you're trying to use 64-bit winpcap on Windows 10, you might have to do
+the crazy hijinks detailed at
+http://stackoverflow.com/questions/38047858/compile-gopacket-on-windows-64bit
+*/
+package pcap
-- 
cgit 1.2.3-korg