vendor/github.com/google/gopacket/pcap/doc.go

   1 // Copyright 2012 Google, Inc. All rights reserved.
   2 //
   3 // Use of this source code is governed by a BSD-style license
   4 // that can be found in the LICENSE file in the root of the source
   5 // tree.
   6
   7 /*
   8 Package pcap allows users of gopacket to read packets off the wire or from
   9 pcap files.
  10
  11 This package is meant to be used with its parent,
  12 http://github.com/google/gopacket, although it can also be used independently
  13 if you just want to get packet data from the wire.
  14
  15 Reading PCAP Files
  16
  17 The following code can be used to read in data from a pcap file.
  18
  19  if handle, err := pcap.OpenOffline("/path/to/my/file"); err != nil {
  20    panic(err)
  21  } else {
  22    packetSource := gopacket.NewPacketSource(handle, handle.LinkType())
  23    for packet := range packetSource.Packets() {
  24      handlePacket(packet)  // Do something with a packet here.
  25    }
  26  }
  27
  28 Reading Live Packets
  29
  30 The following code can be used to read in data from a live device, in this case
  31 "eth0".
  32
  33  if handle, err := pcap.OpenLive("eth0", 1600, true, pcap.BlockForever); err != nil {
  34    panic(err)
  35  } else if err := handle.SetBPFFilter("tcp and port 80"); err != nil {  // optional
  36    panic(err)
  37  } else {
  38    packetSource := gopacket.NewPacketSource(handle, handle.LinkType())
  39    for packet := range packetSource.Packets() {
  40      handlePacket(packet)  // Do something with a packet here.
  41    }
  42  }
  43
  44 Inactive Handles
  45
  46 Newer PCAP functionality requires the concept of an 'inactive' PCAP handle.
  47 Instead of constantly adding new arguments to pcap_open_live, users now call
  48 pcap_create to create a handle, set it up with a bunch of optional function
  49 calls, then call pcap_activate to activate it.  This library mirrors that
  50 mechanism, for those that want to expose/use these new features:
  51
  52   inactive, err := pcap.NewInactiveHandle(deviceName)
  53   if err != nil {
  54     log.Fatal(err)
  55   }
  56   defer inactive.CleanUp()
  57
  58   // Call various functions on inactive to set it up the way you'd like:
  59   if err = inactive.SetTimeout(time.Minute); err != nil {
  60     log.Fatal(err)
  61   } else if err = inactive.SetTimestampSource("foo"); err != nil {
  62     log.Fatal(err)
  63   }
  64
  65   // Finally, create the actual handle by calling Activate:
  66   handle, err := inactive.Activate()  // after this, inactive is no longer valid
  67   if err != nil {
  68     log.Fatal(err)
  69   }
  70   defer handle.Close()
  71
  72   // Now use your handle as you see fit.
  73
  74 PCAP Timeouts
  75
  76 pcap.OpenLive and pcap.SetTimeout both take timeouts.
  77 If you don't care about timeouts, just pass in BlockForever,
  78 which should do what you expect with minimal fuss.
  79
  80 A timeout of 0 is not recommended.  Some platforms, like Macs
  81 (http://www.manpages.info/macosx/pcap.3.html) say:
  82   The read timeout is used to arrange that the read not necessarily return
  83   immediately when a packet is seen, but that it wait for some amount of time
  84   to allow more packets to arrive and to read multiple packets from the OS
  85   kernel in one operation.
  86 This means that if you only capture one packet, the kernel might decide to wait
  87 'timeout' for more packets to batch with it before returning.  A timeout of
  88 0, then, means 'wait forever for more packets', which is... not good.
  89
  90 To get around this, we've introduced the following behavior:  if a negative
  91 timeout is passed in, we set the positive timeout in the handle, then loop
  92 internally in ReadPacketData/ZeroCopyReadPacketData when we see timeout
  93 errors.
  94
  95 PCAP File Writing
  96
  97 This package does not implement PCAP file writing.  However, gopacket/pcapgo
  98 does!  Look there if you'd like to write PCAP files.
  99
 100 Note For Windows 10 Users
 101
 102 If you're trying to use 64-bit winpcap on Windows 10, you might have to do
 103 the crazy hijinks detailed at
 104 http://stackoverflow.com/questions/38047858/compile-gopacket-on-windows-64bit
 105 */
 106 package pcap