utils: many fixups

* `{Raw,}PcapWriter._write_packet`:

  * Remove unused support for `packet` as tuple, as `write` will always
    unroll iterators for us (and do it better).
  * Always set the `usec` parameter if `sec` was unset.
  * Set `usec=0` if `sec` was set, but `usec` was unset (instead of using
    the current time's usec value
  * PEP-8 fixup, add docstring.
  * Only write the header if there is a packet

* `PcapWriter._write_packet`: support packet as bytes

* `RawPcapWriter.close`: write the file header here if not already written

* `tcpdump()`:

  * Add `linktype` parameter, like `wrpcap(linktype=...)`
  * Add `wait` parameter, which controls whether a program should be run in
    the background. Defaults to `True` (run in foreground).
  * Throw an error if `prog` is not a string.
  * Copy `read_stdin_opts` (for thread safety).

* `tdecode()`: Add `args` parameter (defaults to `-V`, as before), pass
  other `tcpdump()` kwargs.

* `wireshark()`: Run in the background by default, pass other `tcpdump()`
  kwargs.

* Add tests that hit `wireshark`, `tdecode`, `tcpdump` with new parameters,
  and try to pass packets as bytes.

Author: micolous

scapy/utils.py

@@ -1278,35 +1278,48 @@ def _write_header(self, pkt):
         self.f.flush()
 
     def write(self, pkt):
-        """accepts either a single packet or a list of packets to be
-        written to the dumpfile
+        """
+        Writes a Packet or bytes to a pcap file.
 
+        :param pkt: Packet(s) to write (one record for each Packet), or raw
+                    bytes to write (as one record).
+        :type pkt: iterable[Packet], Packet or bytes
         """
         if isinstance(pkt, bytes):
             if not self.header_present:
                 self._write_header(pkt)
             self._write_packet(pkt)
         else:
             pkt = pkt.__iter__()
-            if not self.header_present:
-                try:
-                    p = next(pkt)
-                except (StopIteration, RuntimeError):
-                    self._write_header(None)
-                    return
-                self._write_header(p)
-                self._write_packet(p)
             for p in pkt:
+                if not self.header_present:
+                    self._write_header(p)
                 self._write_packet(p)
 
-    def _write_packet(self, packet, sec=None, usec=None, caplen=None, wirelen=None):  # noqa: E501
-        """writes a single packet to the pcap file
+    def _write_packet(self, packet, sec=None, usec=None, caplen=None,
+                      wirelen=None):
+        """
+        Writes a single packet to the pcap file.
+
+        :param packet: bytes for a single packet
+        :type packet: bytes
+        :param sec: time the packet was captured, in seconds since epoch. If
+                    not supplied, defaults to now.
+        :type sec: int or long
+        :param usec: If ``nano=True``, then number of nanoseconds after the
+                     second that the packet was captured. If ``nano=False``,
+                     then the number of microseconds after the second the
+                     packet was captured
+        :type usec: int or long
+        :param caplen: The length of the packet in the capture file. If not
+                       specified, uses ``len(packet)``.
+        :type caplen: int
+        :param wirelen: The length of the packet on the wire. If not
+                        specified, uses ``caplen``.
+        :type wirelen: int
+        :returns: None
+        :rtype: None
         """
-        if isinstance(packet, tuple):
-            for pkt in packet:
-                self._write_packet(pkt, sec=sec, usec=usec, caplen=caplen,
-                                   wirelen=wirelen)
-            return
         if caplen is None:
             caplen = len(packet)
         if wirelen is None:
@@ -1316,9 +1329,13 @@ def _write_packet(self, packet, sec=None, usec=None, caplen=None, wirelen=None):
             it = int(t)
             if sec is None:
                 sec = it
-            if usec is None:
-                usec = int(round((t - it) * (1000000000 if self.nano else 1000000)))  # noqa: E501
-        self.f.write(struct.pack(self.endian + "IIII", sec, usec, caplen, wirelen))  # noqa: E501
+                usec = int(round((t - it) *
+                                 (1000000000 if self.nano else 1000000)))
+            elif usec is None:
+                usec = 0
+
+        self.f.write(struct.pack(self.endian + "IIII",
+                                 sec, usec, caplen, wirelen))
         self.f.write(packet)
         if self.sync:
             self.f.flush()
@@ -1327,6 +1344,8 @@ def flush(self):
         return self.f.flush()
 
     def close(self):
+        if not self.header_present:
+            self._write_header(None)
         return self.f.close()
 
     def __enter__(self):
@@ -1341,8 +1360,6 @@ class PcapWriter(RawPcapWriter):
     """A stream PCAP writer with more control than wrpcap()"""
 
     def _write_header(self, pkt):
-        if isinstance(pkt, tuple) and pkt:
-            pkt = pkt[0]
         if self.linktype is None:
             try:
                 self.linktype = conf.l2types[pkt.__class__]
@@ -1351,17 +1368,51 @@ def _write_header(self, pkt):
                 self.linktype = DLT_EN10MB
         RawPcapWriter._write_header(self, pkt)
 
-    def _write_packet(self, packet):
-        if isinstance(packet, tuple):
-            for pkt in packet:
-                self._write_packet(pkt)
-            return
-        sec = int(packet.time)
-        usec = int(round((packet.time - sec) * (1000000000 if self.nano else 1000000)))  # noqa: E501
+    def _write_packet(self, packet, sec=None, usec=None, caplen=None,
+                      wirelen=None):
+        """
+        Writes a single packet to the pcap file.
+
+        :param packet: Packet, or bytes for a single packet
+        :type packet: Packet or bytes
+        :param sec: time the packet was captured, in seconds since epoch. If
+                    not supplied, defaults to now.
+        :type sec: int or long
+        :param usec: If ``nano=True``, then number of nanoseconds after the
+                     second that the packet was captured. If ``nano=False``,
+                     then the number of microseconds after the second the
+                     packet was captured. If ``sec`` is not specified,
+                     this value is ignored.
+        :type usec: int or long
+        :param caplen: The length of the packet in the capture file. If not
+                       specified, uses ``len(raw(packet))``.
+        :type caplen: int
+        :param wirelen: The length of the packet on the wire. If not
+                        specified, tries ``packet.wirelen``, otherwise uses
+                        ``caplen``.
+        :type wirelen: int
+        :returns: None
+        :rtype: None
+        """
+        if hasattr(packet, "time"):
+            if sec is None:
+                sec = int(packet.time)
+                usec = int(round((packet.time - sec) *
+                                 (1000000000 if self.nano else 1000000)))
+        if usec is None:
+            usec = 0
+
         rawpkt = raw(packet)
-        caplen = len(rawpkt)
-        RawPcapWriter._write_packet(self, rawpkt, sec=sec, usec=usec, caplen=caplen,  # noqa: E501
-                                    wirelen=packet.wirelen or caplen)
+        caplen = len(rawpkt) if caplen is None else caplen
+
+        if wirelen is None:
+            if hasattr(packet, "wirelen"):
+                wirelen = packet.wirelen
+        if wirelen is None:
+            wirelen = caplen
+
+        RawPcapWriter._write_packet(
+            self, rawpkt, sec=sec, usec=usec, caplen=caplen, wirelen=wirelen)
 
 
 @conf.commands.register
@@ -1390,21 +1441,35 @@ def import_hexcap():
 
 
 @conf.commands.register
-def wireshark(pktlist):
-    """Run wireshark on a list of packets"""
-    tcpdump(pktlist, prog=conf.prog.wireshark)
+def wireshark(pktlist, wait=False, **kwargs):
+    """
+    Runs Wireshark on a list of packets.
+
+    See :func:`tcpdump` for more parameter description.
+
+    Note: this defaults to wait=False, to run Wireshark in the background.
+    """
+    return tcpdump(pktlist, prog=conf.prog.wireshark, wait=wait, **kwargs)
 
 
 @conf.commands.register
-def tdecode(pktlist):
-    """Run tshark -V on a list of packets"""
-    tcpdump(pktlist, prog=conf.prog.tshark, args=["-V"])
+def tdecode(pktlist, args=None, **kwargs):
+    """
+    Run tshark on a list of packets.
+
+    :param args: If not specified, defaults to ``tshark -V``.
+
+    See :func:`tcpdump` for more parameters.
+    """
+    if args is None:
+        args = ["-V"]
+    return tcpdump(pktlist, prog=conf.prog.tshark, args=args, **kwargs)
 
 
 @conf.commands.register
 def tcpdump(pktlist, dump=False, getfd=False, args=None,
             prog=None, getproc=False, quiet=False, use_tempfile=None,
-            read_stdin_opts=None):
+            read_stdin_opts=None, linktype=None, wait=True):
     """Run tcpdump or tshark on a list of packets.
 
     When using ``tcpdump`` on OSX (``prog == conf.prog.tcpdump``), this uses a
@@ -1444,6 +1509,13 @@ def tcpdump(pktlist, dump=False, getfd=False, args=None,
               ``tcpdump`` on OSX.
 read_stdin_opts: When set, a list of arguments needed to capture from stdin.
                  Otherwise, attempts to guess.
+linktype: If a Packet (or list) is passed in the ``pktlist`` argument,
+          set the ``linktype`` parameter on ``wrpcap``. If ``pktlist`` is a
+          path to a pcap file, then this option will have no effect.
+wait: If True (default), waits for the process to terminate before returning
+      to Scapy. If False, the process will be detached to the background. If
+      dump, getproc or getfd is True, these have the same effect as
+      ``wait=False``.
 
 Examples:
 
@@ -1485,9 +1557,16 @@ def tcpdump(pktlist, dump=False, getfd=False, args=None,
     elif isinstance(prog, six.string_types):
         _prog_name = "{}()".format(prog)
         prog = [prog]
+    else:
+        raise ValueError("prog must be a string")
 
     # Build Popen arguments
-    args = args if args is not None else []
+    if args is None:
+        args = []
+    else:
+        # Make a copy of args
+        args = list(args)
+
     stdout = subprocess.PIPE if dump or getfd else None
     stderr = open(os.devnull) if quiet else None
 
@@ -1502,6 +1581,9 @@ def tcpdump(pktlist, dump=False, getfd=False, args=None,
             read_stdin_opts = ["-ki", "-"]
         else:
             read_stdin_opts = ["-r", "-"]
+    else:
+        # Make a copy of read_stdin_opts
+        read_stdin_opts = list(read_stdin_opts)
 
     if pktlist is None:
         # sniff
@@ -1524,7 +1606,7 @@ def tcpdump(pktlist, dump=False, getfd=False, args=None,
         try:
             tmpfile.writelines(iter(lambda: pktlist.read(1048576), b""))
         except AttributeError:
-            wrpcap(tmpfile, pktlist)
+            wrpcap(tmpfile, pktlist, linktype=linktype)
         else:
             tmpfile.close()
         with ContextManagerSubprocess(_prog_name, prog[0]):
@@ -1545,7 +1627,7 @@ def tcpdump(pktlist, dump=False, getfd=False, args=None,
         try:
             proc.stdin.writelines(iter(lambda: pktlist.read(1048576), b""))
         except AttributeError:
-            wrpcap(proc.stdin, pktlist)
+            wrpcap(proc.stdin, pktlist, linktype=linktype)
         except UnboundLocalError:
             raise IOError("%s died unexpectedly !" % prog)
         else:
@@ -1556,7 +1638,8 @@ def tcpdump(pktlist, dump=False, getfd=False, args=None,
         return proc
     if getfd:
         return proc.stdout
-    proc.wait()
+    if wait:
+        proc.wait()
 
 
 @conf.commands.register