path: root/docbook/wsug_src/WSUG_chapter_io.xml

<!-- WSUG Chapter IO -->
<!-- $Id$ -->

<chapter id="ChapterIO">
  <title>File Input / Output and Printing</title>

  <section id="ChIOIntroductionSection"><title>Introduction</title>
    <para>
	This chapter will describe input and output of capture data.
	<itemizedlist>
	<listitem>
	  <para>
	    Open/Import capture files in various capture file formats
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Save/Export capture files in various capture file formats
	  </para>
	</listitem>
	<listitem>
	  <para>
	  Merge capture files together
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Print packets
	  </para>
	</listitem>
      </itemizedlist>
    </para>
  </section>

  <section id="ChIOOpenSection"><title>Open capture files</title>
    <para>
      Wireshark can read in previously saved capture files. 
	  To read them, simply select the menu or toolbar item: "File/
	  <inlinegraphic entityref="WiresharkToolbarOpen" format="PNG"/>
	  <command>Open</command>".  
      Wireshark will then pop up the File 
      Open dialog box, which is discussed in more detail in 
      <xref linkend="ChIOOpen"/>. 
    </para>
	<tip><title>It's convenient to use drag-and-drop!</title>
    <para>
	... to open a file, by simply dragging the desired file from your file 
	manager and dropping it onto Wireshark's main window. 
	However, drag-and-drop is not available/won't work in all desktop 
	environments.
    </para>
    </tip>
    <para>
	  If you haven't previously saved the current capture file, you will be asked 
	  to do so, to prevent data loss (this behaviour can be disabled in the 
	  preferences).
    </para>
    <para>
	  In addition to its native file format (libpcap format, also used by 
	  tcpdump/WinDump and other libpcap/WinPcap-based programs), Wireshark can 
	  read capture files from a large number of other packet capture programs 
	  as well. See <xref linkend="ChIOInputFormatsSection"/> for the list of 
	  capture formats Wireshark understands.
    </para>
	
    <section id="ChIOOpen">
    <title>The "Open Capture File" dialog box</title>
      <para>
	The "Open Capture File" dialog box allows you to search for a 
	capture file containing previously captured packets for display in 
	Wireshark.  <xref linkend="ChIOOpenFileTab"/> shows some examples 
	  of the Wireshark Open File Dialog box.
      </para>
	    <note>
	      <title>The dialog appearance depends on your system!</title>
	      <para>
		  The appearance of this dialog depends on the system and/or GTK+ 
		  toolkit version used. However, the functionality remains basically 
		  the same on any particular system.
	      </para>
	    </note>
		
	<para>
	<command>Common dialog behaviour</command> on all systems:
	</para>
	<itemizedlist>
	  <listitem>
	    <para>
	      Select files and directories.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Click the Open/Ok button to accept your selected file and open it. 
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Click the Cancel button to go back to Wireshark and not load a capture 
	      file.
	    </para>
	  </listitem>
	</itemizedlist>

      <para>
	<command>Wireshark extensions</command> to the standard behaviour of 
	these dialogs:
      </para>
	<itemizedlist>
	  <listitem>
	    <para>
	      View file preview information (like the filesize, the number of 
		  packets, ...), if you've selected a capture file.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Specify a display filter with the "Filter:" button and filter 
	      field. This filter will be used when opening the new file. 
		  The text field background becomes green for a valid filter string 
		  and red for an invalid one.
		  Clicking on the Filter button causes Wireshark to pop up 
	      the Filters dialog box (which is discussed further in 
	      <xref linkend="ChWorkDisplayFilterSection"/>).
	    </para>
	    <para>
		  XXX - we need a better description of these read filters
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Specify which type of name resolution is to be performed for all packets by 
		  clicking on one of the "... name resolution" check buttons. 
		  Details about name resolution can be found in 
		  <xref linkend="ChAdvNameResolutionSection"/>.
	    </para>
	  </listitem>
	</itemizedlist>

	<tip><title>Save a lot of time loading huge capture files!</title>
    <para>
	You can change the display filter and name resolution settings later 
	while viewing the packets. 
	However, loading huge capture files can take a significant amount of 
	extra time if these settings are changed later, so in such situations it can 
	be a good idea to set at least the filter in advance here.
    </para>
    </tip>
	
	<!-- frame="none" -->
    <table id="ChIOOpenFileTab">
	<title>The system specific "Open Capture File" dialog box</title>
      <tgroup cols="2">
	    <tbody>
		<row>
		<entry valign="top">
		<para>
      <figure id="ChIOOpenFileDialogWin32">
	<title>"Open" on native Windows</title>
	<graphic entityref="WiresharkOpenDialogWin32" format="PNG"/>
      </figure>
		</para>
		</entry>
		<entry valign="top">
		<para><command>Microsoft Windows</command></para>
      <para>
		This is the common Windows file open dialog - 
		plus some Wireshark extensions.
      </para>
	    <para>
		Specific for this dialog:
      </para>
	<itemizedlist>
	<listitem>
	    <para>
	      If available, the "Help" button will lead you to this section of 
		  this "User's Guide".
	    </para>
	</listitem>
	<listitem>
	    <note><para>
 		  The "Filter:" button currently doesn't work on Windows!
	    </para></note>
	</listitem>
	</itemizedlist>
		</entry>
	      </row>
		<row>
		<entry valign="top">
		<para>
      <figure id="ChIOOpenFileDialog">
	<title>"Open" - new GTK version</title>
	<graphic entityref="WiresharkOpenDialog24" format="PNG"/>
      </figure>
		</para>
	  </entry>
	  <entry valign="top">
      <para><command>Unix/Linux: GTK version >= 2.4</command></para>
      <para>
		This is the common Gimp/GNOME file open dialog - 
		plus some Wireshark extensions.
      </para>
	    <para>
		Specific for this dialog:
      </para>
	<itemizedlist>
	<listitem>
	    <para>
		The "+ Add" button allows you to add a directory, selected in the 
		right-hand pane, to the favorites list on the left. Those changes 
		are persistent.
	    </para>
	</listitem>
	<listitem>
	    <para>
		The "- Remove" button allows you to remove a selected directory from 
		that list again (the items like: "Home", "Desktop", and "Filesystem" 
		cannot be removed).
	    </para>
	</listitem>
	<listitem>
	    <para>
		  If Wireshark doesn't recognize the selected file as a capture file, 
		  it will grey out the "Open" button.
	    </para>
	</listitem>
	</itemizedlist>
	  </entry>
		</row>
	      <row>
		<entry valign="top">
		<para>
      <figure id="ChIOOpenFileDialog1">
	<title>"Open" - old GTK version</title>
	<graphic entityref="WiresharkOpenDialog20" format="PNG"/>
      </figure>
		</para>
		</entry>
	  <entry valign="top">
	    <para>
		<command>Unix/Linux: GTK version &lt; 2.4</command></para>
		<para>
		  This is the file open dialog of former Gimp/GNOME versions - 
		  plus some Wireshark extensions.
		</para>
	    <para>
		Specific for this dialog:
      </para>
	<itemizedlist>
	<listitem>
	    <para>
		  If Wireshark doesn't recognize the selected file as a capture file, 
		  it will grey out the "Ok" button.
	    </para>
	</listitem>
	</itemizedlist>
		</entry>
		</row>
	    </tbody>
      </tgroup>
    </table>
		
		
    </section>

  <section id="ChIOInputFormatsSection">
    <title>Input File Formats</title>
    <para>
	The following file formats from other capture tools can be opened by 
	<application>Wireshark</application>:
	<itemizedlist>
	      <listitem><para>libpcap, tcpdump and various other tools using tcpdump's capture format</para></listitem>
	      <listitem><para>Sun snoop and atmsnoop</para></listitem>
	      <listitem><para>Shomiti/Finisar <emphasis>Surveyor</emphasis> captures</para></listitem>
	      <listitem><para>Novell <emphasis>LANalyzer</emphasis> captures</para></listitem>
	      <listitem><para>Microsoft Network Monitor captures</para></listitem>
	      <listitem><para>AIX's iptrace captures</para></listitem>
	      <listitem><para>Cinco Networks NetXray captures</para></listitem>		  
	      <listitem><para>Network Associates Windows-based Sniffer and Sniffer Pro captures</para></listitem>
	      <listitem><para>Network General/Network Associates DOS-based Sniffer (compressed or uncompressed) captures</para></listitem>
	      <listitem><para>AG Group/WildPackets EtherPeek/TokenPeek/AiroPeek/EtherHelp/PacketGrabber captures</para></listitem>
	      <listitem><para>RADCOM's WAN/LAN Analyzer captures</para></listitem>
	      <listitem><para>Network Instruments Observer version 9 captures</para></listitem>
	      <listitem><para>Lucent/Ascend router debug output</para></listitem>		  
	      <listitem><para>HP-UX's nettl</para></listitem>
	      <listitem><para>Toshiba's ISDN routers dump output</para></listitem>
	      <listitem><para>ISDN4BSD <emphasis>i4btrace</emphasis> utility</para></listitem>
	      <listitem><para>traces from the EyeSDN USB S0</para></listitem>
	      <listitem><para>IPLog format from the Cisco Secure Intrusion Detection System</para></listitem>
	      <listitem><para>pppd logs (pppdump format)</para></listitem>
	      <listitem><para>the output from VMS's TCPIPtrace/TCPtrace/UCX$TRACE utilities</para></listitem>
	      <listitem><para>the text output from the DBS Etherwatch VMS utility</para></listitem>
	      <listitem><para>Visual Networks' Visual UpTime traffic capture</para></listitem>
	      <listitem><para>the output from CoSine L2 debug</para></listitem>
	      <listitem><para>the output from Accellent's 5Views LAN agents</para></listitem>
	      <listitem><para>Endace Measurement Systems' ERF format captures</para></listitem>
	      <listitem><para>Linux Bluez Bluetooth stack hcidump -w traces</para></listitem>
	      <listitem><para>Catapult DCT2000 .out files</para></listitem>
	      <listitem><para>Gammu generated text output from Nokia DCT3 phones in Netmonitor mode</para></listitem>
	      <listitem><para>IBM Series (OS/400) Comm traces (ASCII &amp; UNICODE)</para></listitem>
	      <listitem><para>Juniper Netscreen snoop captures</para></listitem>
	      <listitem><para>Symbian OS btsnoop captures</para></listitem>
	      <listitem><para>Tamosoft CommView captures</para></listitem>
	      <listitem><para>Textronix K12xx 32bit .rf5 format captures</para></listitem>
	      <listitem><para>Textronix K12 text file format captures</para></listitem>
	      <listitem><para>Wireshark .pcapng captures (Experimental)</para></listitem>
	      <listitem><para>... new file formats are added from time to time</para></listitem>
	</itemizedlist>
    </para>
    <note><title>Opening a file may fail due to invalid packet types!</title>
	<para>
	It may not be possible to read some formats dependent on the packet types 
	captured. Ethernet captures are usually supported for most file formats but
	it may not be possible to read other packet types (e.g. token ring packets) 
	from all file formats.
	</para>
	</note>
	
  </section>

  </section>
  
  <section id="ChIOSaveSection"><title>Saving captured packets</title>
    <para>
      You can save captured packets simply by using the Save As... menu 
      item from the File menu under Wireshark. You can choose which 
      packets to save and which file format to be used.
    </para>
	<warning>
	  <title>Saving may reduce the available information!</title>
	  <para>
	  Saving the captured packets will slightly reduce the amount of 
	  information, e.g. the number of dropped packets will be lost;
	  see <xref linkend="ChAppFilesCaptureFilesSection"/> for details.
	  </para>
	</warning>
    <section id="ChIOSaveAs">
      <title>The "Save Capture File As" dialog box</title>
      <para>
	The "Save Capture File As" dialog box allows you to save 
	the current capture to a file. 
	<xref linkend="ChIOSaveFileTab"/> shows some examples of this 
	  dialog box.
      </para>
	    <note>
	      <title>The dialog appearance depends on your system!</title>
	      <para>
		  The appearance of this dialog depends on the system and GTK+ toolkit 
		  version used. However, the functionality remains basically the same 
		  on any particular system.
	      </para>
	    </note>
		
    <table id="ChIOSaveFileTab">
	<title>The system specific "Save Capture File As" dialog box</title>
      <tgroup cols="2">
	    <tbody>
		<row>
		<entry valign="top">
		<para>
      <figure id="ChIOSaveAsFileWin32">
	<title>"Save" on native Windows</title>
	<graphic entityref="WiresharkSaveAsDialogWin32" format="PNG"/>
      </figure>
		</para>
		</entry>
		<entry valign="top">
		<para><command>Microsoft Windows</command></para>
      <para>
		This is the common Windows file save dialog - 
		plus some Wireshark extensions.
      </para>
	    <para>
		Specific for this dialog:
      </para>
	<itemizedlist>
	<listitem>
	    <para>
	      If available, the "Help" button will lead you to this section of 
		  this "User's Guide".
	    </para>
	</listitem>
	<listitem>
	    <para>
	      If you don't provide a file extension to the filename - e.g. .pcap, 
		  Wireshark will append the standard file extension for that file 
		  format.
	    </para>
	</listitem>
	</itemizedlist>
		</entry>
		</row>
		<row>
		<entry valign="top">
		<para>
      <figure id="ChIOSaveAsFile2">
	<title>"Save" - new GTK version</title>
	<graphic entityref="WiresharkSaveAsDialog24" format="PNG"/>
      </figure>
		</para>
		</entry>
		<entry valign="top">
		<para><command>Unix/Linux: GTK version >= 2.4</command></para>
      <para>
		This is the common Gimp/GNOME file save dialog - 
		plus some Wireshark extensions.
      </para>
	    <para>
		Specific for this dialog:
      </para>
	<itemizedlist>
	<listitem>
	    <para>
		Clicking on the + at "Browse for other folders" will allow you 
		to browse files and folders in your file system.
	    </para>
	</listitem>
	</itemizedlist>
		</entry>
		</row>
		<row>
		<entry valign="top">
		<para>
      <figure id="ChIOSaveAsFile1">
	<title>"Save" - old GTK version</title>
	<graphic entityref="WiresharkSaveAsDialog20" format="PNG"/>
      </figure>
		</para>
		</entry>
		<entry valign="top">
		<para><command>Unix/Linux: GTK version &lt; 2.4</command></para>
      <para>
		This is the file save dialog of former Gimp/GNOME versions - 
		plus some Wireshark extensions.
      </para>
		</entry>
		</row>
      </tbody>
      </tgroup>
    </table>
		
      <para>
	With this dialog box, you can perform the following actions:
	<orderedlist>
	  <listitem>
	    <para>
	      Type in the name of the file you wish to save the captured 
	      packets in, as a standard file name in your file system.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
		Select the directory to save the file into.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Select the range of the packets to be saved, see 
		  <xref linkend="ChIOPacketRangeSection"/>
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Specify the format of the saved capture file by clicking on 
	      the File type drop down box. You can choose from the 
	      types, described in <xref linkend="ChIOOutputFormatsSection"/>.
		</para>
	    <note>
	      <title>The selection of capture formats may be reduced!</title>
	      <para>
		Some capture formats may not be available, depending on the 
		packet types captured.
	      </para>
	    </note>
	    <tip>
	      <title>File formats can be converted!</title>
	      <para>
		You can convert capture files from one format to another 
		by reading in a capture file and writing it out using a 
		different format.
	      </para>
	    </tip>
	  </listitem>
	  <listitem>
	    <para>
	      Click on the Save/Ok button to accept your selected file and save to 
		  it. If Wireshark has a problem saving the captured packets to 
	      the file you specified, it will display an error dialog box. 
	      After clicking OK on that error dialog box, you can try again. 
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Click on the Cancel button to go back to Wireshark and not save the 
	      captured packets.
	    </para>
	  </listitem>
	</orderedlist>
      </para>
    </section>
  <section id="ChIOOutputFormatsSection">
    <title>Output File Formats</title>
    <para>
	Wireshark can save the packet data in its "native" file format (libpcap) 
	and in the file formats of some other protocol analyzers, so other tools 
	can read the capture data.
    </para>
	<warning><title>File formats have different time stamp accuracies!</title>
	<para>
	Saving from the currently used file format to a different format may reduce the 
	time stamp accuracy; see the <xref linkend="ChAdvTimestamps"/> for details.
	</para>
	</warning>
    <para>
	The following file formats can be saved by <application>Wireshark</application> (with the known file extensions):
	<itemizedlist>
	      <listitem><para>libpcap, tcpdump and various other tools using tcpdump's capture format (*.pcap,*.cap,*.dmp)</para></listitem>
	      <listitem><para>Accellent 5Views (*.5vw)</para></listitem>
	      <listitem><para>HP-UX's nettl (*.TRC0,*.TRC1)</para></listitem>
	      <listitem><para>Microsoft Network Monitor - NetMon (*.cap)</para></listitem>
	      <listitem><para>Network Associates Sniffer - DOS (*.cap,*.enc,*.trc,*fdc,*.syc)</para></listitem>
	      <listitem><para>Network Associates Sniffer - Windows (*.cap)</para></listitem>
	      <listitem><para>Network Instruments Observer version 9 (*.bfr)</para></listitem>
	      <listitem><para>Novell LANalyzer (*.tr1)</para></listitem>
	      <listitem><para>Sun snoop (*.snoop,*.cap)</para></listitem>
	      <listitem><para>Visual Networks Visual UpTime traffic (*.*)</para></listitem>
	      <listitem><para>... new file formats are added from time to time</para></listitem>
	</itemizedlist>
    </para>
    <para>
	If the above tools will be more helpful than Wireshark is a different question ;-)
    </para>
	<note><title>Third party protocol analyzers may require specific file extensions!</title>
	<para>
	Other protocol analyzers than Wireshark may require that the file has a 
	certain file extension in order to read the files you generate with Wireshark, e.g.:
	</para>
	<para>
	".cap" for Network Associates Sniffer - Windows
	</para>
	</note>
  </section>	
  </section>
  
  <section id="ChIOMergeSection"><title>Merging capture files</title>
	<para>
	Sometimes you need to merge several capture files into one. For example 
	this can be useful, if you have captured simultaneously from multiple 
	interfaces at once (e.g. using multiple instances of Wireshark).
	</para>
	<para>
	Merging capture files can be done in three ways:
	<itemizedlist>
		<listitem><para>
		Use the <command>menu item "Merge"</command> from the "File" menu, 
		to open the merge dialog, see <xref linkend="ChIOMergeDialog"/>.
		This menu item will be disabled, until you have loaded a capture file.
		</para></listitem>
		<listitem><para>
	  	Use <command>drag-and-drop</command> to drop multiple files on the 
		main window. Wireshark will try to merge the packets in chronological 
		order from the dropped files into a newly created temporary file. If 
		you drop only a single file, it will simply replace a (maybe) existing
		one.
		</para></listitem>
		<listitem><para>
	  	Use the <command>mergecap</command> tool, which is a command 
		line tool to merge capture files. This tool provides the most options 
		to merge capture files, see <xref linkend="AppToolsmergecap"/>.
		</para></listitem>
	</itemizedlist>
	</para>
	<section id="ChIOMergeDialog">
	<title>The "Merge with Capture File" dialog box</title>
	<para>
	
	This dialog box let you select a file to be merged into the currently 
	loaded file.
	</para>
	<note><title>You will be prompted for an unsaved file first!</title>
	<para>If your current data wasn't saved before, you will be asked to save 
	it first, before this dialog box is shown.</para>
	</note>
	
	<para>
	Most controls of this dialog will work the same way as described in the 
	"Open Capture File" dialog box, see <xref linkend="ChIOOpen"/>.
	</para>
	<para>
	Specific controls of this merge dialog are:
	</para>
	
	<variablelist>
	<varlistentry>
	  <term><command>Prepend packets to existing file</command></term>
	  <listitem>
	    <para>
		Prepend the packets from the selected file before the currently loaded 
		packets.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><command>Merge packets chronologically</command></term>
	  <listitem>
	    <para>
		Merge both the packets from the selected and currently loaded file in 
		chronological order.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><command>Append packets to existing file</command></term>
	  <listitem>
	    <para>
		Append the packets from the selected file after the currently loaded 
		packets.
	    </para>
	  </listitem>
	</varlistentry>
	</variablelist>
	
    <table id="ChIOMergeFileTab">
	<title>The system specific "Merge Capture File As" dialog box</title>
      <tgroup cols="2">
	    <tbody>
		<row>
		<entry valign="top">
		<para>
      <figure id="ChIOMergeFileWin32">
	<title>"Merge" on native Windows</title>
	<graphic entityref="WiresharkMergeDialogWin32" format="PNG"/>
      </figure>
		</para>
		</entry>
		<entry valign="top">
		<para><command>Microsoft Windows</command></para>
      <para>
		This is the common Windows file open dialog - 
		plus some Wireshark extensions.
      </para>
		</entry>
		</row>
		<row>
		<entry valign="top">
		<para>
      <figure id="ChIOMergeFile2">
	<title>"Merge" - new GTK version</title>
	<graphic entityref="WiresharkMergeDialog24" format="PNG"/>
      </figure>
		</para>
		</entry>
		<entry valign="top">
		<para><command>Unix/Linux: GTK version >= 2.4</command></para>
      <para>
		This is the common Gimp/GNOME file open dialog - 
		plus some Wireshark extensions.
      </para>
		</entry>
		</row>
		<row>
		<entry valign="top">
		<para>
      <figure id="ChIOMergeFile1">
	<title>"Merge" - old GTK version</title>
	<graphic entityref="WiresharkMergeDialog20" format="PNG"/>
      </figure>
		</para>
		</entry>
		<entry valign="top">
		<para><command>Unix/Linux: GTK version &lt; 2.4</command></para>
      <para>
		This is the file open dialog of former Gimp/GNOME versions - 
		plus some Wireshark extensions.
      </para>
		</entry>
		</row>
      </tbody>
      </tgroup>
    </table>

	</section>
  </section>

  <section id="ChIOImportSection"><title>Import text file</title>
    <para>
    Wireshark can read in an ASCII hex dump and write the data described 
    into a temporary libpcap capture file. It can read hex dumps with multiple 
    packets in them, and build a capture file of multiple packets. It is also 
    capable of generating dummy Ethernet, IP and UDP, TCP, or SCTP headers, 
    in order to build fully processable packet dumps from hexdumps of 
    application-level data only.
    </para>
    <para>
    Wireshark understands a hexdump of the form generated by 
    <command>od -Ax -tx1 -v</command>.
    In other words, each byte is individually displayed and surrounded with a space.
    Each line begins with an offset describing the position in the file. The offset
    is a hex number (can also be octal or decimal), of more than two hex
    digits.  Here is a sample dump that can be imported:
    </para>
    <programlisting>
           000000 00 e0 1e a7 05 6f 00 10 ........
           000008 5a a0 b9 12 08 00 46 00 ........
           000010 03 68 00 00 00 00 0a 2e ........
           000018 ee 33 0f 19 08 7f 0f 19 ........
           000020 03 80 94 04 00 00 10 01 ........
           000028 16 a2 0a 00 03 50 00 0c ........
           000030 01 01 0f 19 03 80 11 01 ........
    </programlisting>
    <para>
    There is no limit on the width or number of bytes per line. Also the text dump at
    the end of the line is ignored. Bytes/hex numbers can be uppercase or lowercase.
    Any text before the offset is ignored, including email forwarding characters '>'.
    Any lines of text between the bytestring lines is ignored. The offsets are used
    to track the bytes, so offsets must be correct. Any line which has only bytes
    without a leading offset is ignored. An offset is recognized as being a hex
    number longer than two characters. Any text after the bytes is ignored (e.g. the
    character dump). Any hex numbers in this text are also ignored. An offset of zero
    is indicative of starting a new packet, so a single text file with a series of
    hexdumps can be converted into a packet capture with multiple packets. Packets may
    be preseded by a timestamp. These are interpreted according to the format
    given. If not the first packet is timestamped with the current time the import
    takes place. Multiple packets are read in with timestamps differing by one
    microsecond each. In general, short of these restrictions, Wireshark is pretty
    liberal about reading in hexdumps and has been tested with a variety of mangled
    outputs (including being forwarded through email multiple times, with limited
    line wrap etc.)
    </para>
    <para>
    There are a couple of other special features to note. Any line where the first
    non-whitespace character is '#' will be ignored as a comment. Any line beginning
    with #TEXT2PCAP is a directive and options can be inserted after this command to
    be processed by Wireshark. Currently there are no directives implemented; in the
    future, these may be used to give more fine grained control on the dump and the
    way it should be processed e.g. timestamps, encapsulation type etc.
    Wireshark also allows the user to read in dumps of application-level data, by
    inserting dummy L2, L3 and L4 headers before each packet. The user can elect to
    insert Ethernet headers, Ethernet and IP, or Ethernet, IP and UDP/TCP/SCTP headers
    before each packet. This allows Wireshark or any other full-packet decoder to
    handle these dumps.
    </para>
  	<section id="ChIOImportDialog">
	  <title>The "File import" dialog box</title>
	  <para>
	  This dialog box lets you select a file to be imported and set import parameters.
	  </para>
	  <para>
    <figure id="ChIOFileImportDialog">
      <title>The "File Import" dialog</title>
      <graphic entityref="WiresharkFileImportDialog" format="PNG"/>
    </figure>
    </para>
    <para>
    Specific controls of this import dialog are split in two sections:
        <variablelist>
        <varlistentry>
        <term>Input</term>
        <listitem><para>Determine which input file has to be imported and 
        how it is to be interpreted.
        </para></listitem>
        </varlistentry>
        <varlistentry>
        <term>Import</term>
        <listitem><para>Determine how the data is to be imported.</para></listitem>
        </varlistentry>
        </variablelist>
    </para>
	  <para>
	  The input parameters are as follows:
	  </para>
    <variablelist>
    <varlistentry>
      <term><command>Filename / Browse</command></term>
      <listitem>
      <para>
      Enter the name of the text file to import. You can use 
      <command>Browse</command> to browse for a file.
      </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><command>Offsets</command></term>
      <listitem>
      <para>
      Select the radix of the offsets given in the text file to import. 
      This is usually hexadecimal, but decimal and octal are also supported.
      </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><command>Date/Time</command></term>
      <listitem>
      <para>
      Tick this checkbox if there are timestamps associated with the frames 
      in the text file to import you would like to use. Otherwise the current time
      is used for timestamping the frames.
      </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><command>Format</command></term>
      <listitem>
      <para>
      This is the format specifier used to parse the timestamps in the text file 
      to import. It uses a simple syntax to describe the format of the timestamps,
      using %H for hours, %M for minutes, %S for seconds, etc. The straightforward
      HH:MM:SS format is covered by %T. For a full definition of the syntax look for 
      <command>strftime(3)</command>.
      </para>
      </listitem>
    </varlistentry>
    </variablelist>
	  <para>
	  The import parameters are as follows:
	  </para>
    <variablelist>
    <varlistentry>
      <term><command>Encapsulation type</command></term>
      <listitem>
      <para>
      Here you can select which type of frames you are importing. This all depends on
      from what type of medium the dump to import was taken. It lists all types that 
      Wirshark understands, so as to pass the capture file contents to the right dissector.
      </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><command>Dummy header</command></term>
      <listitem>
      <para>
      When Ethernet encapsulation is selected you have to option to prepend dummy
      headers to the frames to import. These headers can provide artificial Ethernet, IP,
      UDP or TCP or SCTP headers and SCTP data chunks. When selecting a type of dummy
      header the applicable entries are enabled, others are grayed out and default values 
      are used.
      </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><command>Max. frame length</command></term>
      <listitem>
      <para>
      You may not be interested in the full frames from the text file, just the first part. 
      Here you can define how much data from the start of the frame you want to import.
      If you leave this open the maximum is set to 64000 bytes.
      </para>
      </listitem>
    </varlistentry>
    </variablelist>
    <para>
    Once all input and import parameters are setup click <command>OK</command>
    to start the import.
    </para>
    <para>
	  <note><title>You will be prompted for an unsaved file first!</title>
	  <para>If your current data wasn't saved before, you will be asked to save 
    it first, before this dialog box is shown.</para>
    </note>
    </para>
    <para>
    When completed there will be a new capture file loaded with the frames imported 
    from the text file.
    </para>
  </section>
  </section>

  <section id="ChIOFileSetSection"><title>File Sets</title>
    <para>
      When using the "Multiple Files" option while doing a capture
	  (see: <xref linkend="ChCapCaptureFiles"/>), 
	  the capture data is spread over several capture files, called a file 
	  set. 
    </para>
    <para>
	  As it can become tedious to work with a file set by hand, Wireshark 
	  provides some features to handle these file sets in a convenient way.
    </para>
    <sidebar><title>How does Wireshark detect the files of a file set?</title>
    <para>
	  A filename in a file set uses the format Prefix_Number_DateTimeSuffix 
	  which might look like this: "test_00001_20060420183910.pcap".
	  All files of a file set share the same prefix (e.g. "test") and suffix 
	  (e.g. ".pcap") and a varying middle part.
    </para>
    <para>
	  To find the files of a file set, Wireshark scans the directory where the 
	  currently loaded file resides and checks for files matching the filename 
	  pattern (prefix and suffix) of the currently loaded file. 
    </para>
    <para>
	  This simple mechanism usually works well, but has its drawbacks. If several 
	  file sets were captured with the same prefix and suffix, Wireshark will detect 
	  them as a single file set. If files were renamed or spread over several 
	  directories the mechanism will fail to find all files of a set.
    </para>
	</sidebar>
    <para>
	  The following features in the "File Set" submenu of the "File" menu are 
	  available to work with file sets in a convenient way:
    </para>
	<itemizedlist>
		<listitem><para>
		The <command>List Files</command> dialog box will list the files 
		Wireshark has recognized as being part of the current file set.
		</para></listitem>
		<listitem><para>
		<command>Next File</command> closes the current and opens the next 
		file in the file set.
		</para></listitem>
		<listitem><para>
		<command>Previous File</command> closes the current and opens the 
		previous file in the file set.
		</para></listitem>
	</itemizedlist>
	<section id="ChIOFileSetListDialog">
	<title>The "List Files" dialog box</title>
    <figure>
      <title>The "List Files" dialog box</title>
      <graphic entityref="WiresharkFileSetDialog" format="PNG"/>
    </figure>
	  <para>
	  Each line contains information about a file of the file set:
	<itemizedlist>
		<listitem><para>
		<command>Filename</command> the name of the file. If you click on 
		the filename (or the radio button left to it), the current file will
		be closed and the corresponding capture file will be opened. 
		</para></listitem>
		<listitem><para>
		<command>Created</command> the creation time of the file
		</para></listitem>
		<listitem><para>
		<command>Last Modified</command> the last time the file was modified
		</para></listitem>
		<listitem><para>
		<command>Size</command> the size of the file
		</para></listitem>
	</itemizedlist>
	  The last line will contain info about the currently used directory where
	  all of the files in the file set can be found.
	  </para>
	  <para>
	  The content of this dialog box is updated each time a capture file is 
	  opened/closed.
	  </para>
	  <para>
	  The Close button will, well, close the dialog box.
	  </para>
	</section>
  </section>
  <section id="ChIOExportSection"><title>Exporting data</title>
    <para>
      Wireshark provides several ways and formats to export packet data. This 
	  section describes general ways to export data from Wireshark.
    </para>
	<note><title>Note!</title>
	<para>
	  There are more specialized functions to export specific data, 
	  which will be described at the appropriate places. 
	</para>
	</note>
    <para>
	  XXX - add detailed descriptions of the output formats and some sample 
	  output, too.
    </para>
	<section id="ChIOExportPlainDialog">
	<title>The "Export as Plain Text File" dialog box</title>
	  <para id="ChIOExportPlain">
	    Export packet data into a plain ASCII text file, much like the format 
		used to print packets.
    <figure>
      <title>The "Export as Plain Text File" dialog box</title>
      <graphic entityref="WiresharkExportPlainDialog" format="PNG"/>
    </figure>
	<itemizedlist>
		<listitem><para>
	  	<command>Export to file:</command> frame chooses the file to export 
		the packet data to.
		</para></listitem>
		<listitem><para>
	  	The <command>Packet Range</command> frame is described in <xref 
		linkend="ChIOPacketRangeSection"/>.
		</para></listitem>
		<listitem><para>
	  	The <command>Packet Details</command> frame is described in <xref 
		linkend="ChIOPacketFormatSection"/>.
		</para></listitem>
	</itemizedlist>	
	  </para>
    </section>
	<section id="ChIOExportPSDialog">
	<title>The "Export as PostScript File" dialog box</title>
	  <para>
	    Export packet data into PostScript, much like the format used 
		to print packets.
	<tip><title>Tip!</title>
	<para>
	You can easily convert PostScript files to PDF files using ghostscript.
	For example: export to a file named foo.ps and then call: 
	<command>ps2pdf foo.ps</command>
	</para>
	</tip>
    <figure>
      <title>The "Export as PostScript File" dialog box</title>
      <graphic entityref="WiresharkExportPSDialog" format="PNG"/>
    </figure>
	<itemizedlist>
		<listitem><para>
	  	<command>Export to file:</command> frame chooses the file to export 
		the packet data to.
		</para></listitem>
		<listitem><para>
	  	The <command>Packet Range</command> frame is described in <xref 
		linkend="ChIOPacketRangeSection"/>.
		</para></listitem>
		<listitem><para>
	  	The <command>Packet Details</command> frame is described in <xref 
		linkend="ChIOPacketFormatSection"/>.
		</para></listitem>
	</itemizedlist>	
	  </para>
    </section>
	<section id="ChIOExportCSVDialog">
	<title>The "Export as CSV (Comma Separated Values) File" dialog box</title>
	  <para>XXX - add screenshot</para>
	  <para>
	    Export packet summary into CSV, used e.g. by spreadsheet programs to 
		im-/export data.
    <!--<figure>
      <title>The "Export as Comma Separated Values File" dialog box</title>
      <graphic entityref="WiresharkExportCSVDialog" format="PNG"/>
    </figure>-->
	<itemizedlist>
		<listitem><para>
	  	<command>Export to file:</command> frame chooses the file to export 
		the packet data to.
		</para></listitem>
		<listitem><para>
	  	The <command>Packet Range</command> frame is described in <xref 
		linkend="ChIOPacketRangeSection"/>.
		</para></listitem>
	</itemizedlist>	
	  </para>
    </section>
    <section id="ChIOExportCArraysDialog">
      <title>The "Export as C Arrays (packet bytes) file" dialog box</title>
      <para>XXX - add screenshot</para>
      <para>
	Export packet bytes into C arrays so you can import the stream data
	into your own C program.
	<!--
	    <figure>
	    <title>The "Export as C Arrays (packet bytes) file" dialog box</title>
	    <graphic entityref="WiresharkExportCArraysDialog" format="PNG"/>
	    </figure>
	-->
	<itemizedlist>
	  <listitem><para>
	    <command>Export to file:</command> frame chooses the file to export 
	    the packet data to.
	  </para></listitem>
	  <listitem><para>
	    The <command>Packet Range</command> frame is described in <xref 
	    linkend="ChIOPacketRangeSection"/>.
	  </para></listitem>
	</itemizedlist>	
      </para>
    </section>
	<section id="ChIOExportPSMLDialog">
	<title>The "Export as PSML File" dialog box</title>
	  <para>
	    Export packet data into PSML. This is an XML based format including 
		only the packet summary. The PSML file specification is available at: 
		<ulink url="http://www.nbee.org/doku.php?id=netpdl:psml_specification"/>.
    <figure>
      <title>The "Export as PSML File" dialog box</title>
      <graphic entityref="WiresharkExportPSMLDialog" format="PNG"/>
    </figure>
	<itemizedlist>
		<listitem><para>
	  	<command>Export to file:</command> frame chooses the file to export 
		the packet data to.
		</para></listitem>
		<listitem><para>
	  	The <command>Packet Range</command> frame is described in <xref 
		linkend="ChIOPacketRangeSection"/>.
		</para></listitem>
	</itemizedlist>	
	There's no such thing as a packet details frame for PSML export, as the 
	packet format is defined by the PSML specification.
	  </para>
    </section>
	<section id="ChIOExportPDMLDialog">
	<title>The "Export as PDML File" dialog box</title>
	  <para>
	    Export packet data into PDML. This is an XML based format including 
		the packet details. The PDML file specification is available at: 
		<ulink url="http://www.nbee.org/doku.php?id=netpdl:pdml_specification"/>.
		<note><title></title>
		<para>
		The PDML specification is not officially released and Wireshark's 
		implementation of it is still in an early beta state, so please expect 
		changes in future Wireshark versions.
		</para>
		</note>
    <figure>
      <title>The "Export as PDML File" dialog box</title>
      <graphic entityref="WiresharkExportPDMLDialog" format="PNG"/>
    </figure>
	<itemizedlist>
		<listitem><para>
	  	<command>Export to file:</command> frame chooses the file to export 
		the packet data to.
		</para></listitem>
		<listitem><para>
	  	The <command>Packet Range</command> frame is described in <xref 
		linkend="ChIOPacketRangeSection"/>.
		</para></listitem>
	</itemizedlist>	
	There's no such thing as a packet details frame for PDML export, as the 
	packet format is defined by the PDML specification.
	  </para>
  </section>
	<section id="ChIOExportSelectedDialog">
	<title>The "Export selected packet bytes" dialog box</title>
	  <para>
	    Export the bytes selected in the "Packet Bytes" pane into a raw 
		binary file.
    <figure>
      <title>The "Export Selected Packet Bytes" dialog box</title>
      <graphic entityref="WiresharkExportSelectedDialog" format="PNG"/>
    </figure>
	<itemizedlist>
		<listitem><para>
	  	<command>Name:</command> the filename to export the packet data to.
		</para></listitem>
		<listitem><para>
	  	The <command>Save in folder:</command> field lets you select the 
		folder to save to (from some predefined folders).
		</para></listitem>
		<listitem><para>
	  	<command>Browse for other folders</command> provides a flexible 
		way to choose a folder.
		</para></listitem>
	</itemizedlist>	
	  </para>
  </section>
	<section id="ChIOExportObjectsDialog">
	<title>The "Export Objects" dialog box</title>
	  <para>
	    This feature scans through HTTP streams in the currently
	    open capture file or running capture and takes reassembled
	    objects such as HTML documents, image files, executables
	    and anything else that can be transferred over HTTP and
	    lets you save them to disk.  If you have a capture
	    running, this list is automatically updated every few
	    seconds with any new objects seen.  The saved objects can then be
	    opened with the proper viewer or executed in the case of
	    executables (if it is for the same platform you are
	    running Wireshark on) without any further work on your
	    part.  This feature is not available when using GTK2 versions 
		below 2.4.
	  </para>
    <figure>
      <title>The "Export Objects" dialog box</title>
      <graphic entityref="WiresharkExportObjectsDialog" format="PNG"/>
    </figure>
    
	<itemizedlist>
	  <para>Columns:</para>
		<listitem><para>
	  	<command>Packet num:</command> The packet number in
	  	which this object was found.  In some cases, there can
	  	be multiple objects in the same packet.
		</para></listitem>

		<listitem><para>
		<command>Hostname:</command> The hostname of the
		server that sent the object as a response to an HTTP request.
		</para></listitem>

		<listitem><para>
		<command>Content Type:</command> The HTTP content type
		of this object.
		</para></listitem>

		<listitem><para>
		<command>Bytes:</command> The size of this object in bytes.
		</para></listitem>

		<listitem><para>
		<command>Filename:</command> The final part of the URI
		(after the last slash).  This is typically a filename,
		but may be a long complex looking string, which
		typically indicates that the file was received in response to
		a HTTP POST request.
		</para></listitem>
	</itemizedlist>	

	<itemizedlist>
	  <para>Buttons:</para>
		<listitem><para>
	  	<command>Help:</command> Opens this section in the
	  	user's guide.
		</para></listitem>

		<listitem><para>
	  	<command>Close:</command> Closes this dialog.
		</para></listitem>

		<listitem><para>
	  	<command>Save As:</command> Saves the currently
	  	selected object as a filename you specify.  The
	  	default filename to save as is taken from the filename
	  	column of the objects list.
		</para></listitem>

		<listitem><para>
	  	<command>Save All:</command> Saves all objects in the
	  	list using the filename from the filename column.  You
	  	will be asked what directory / folder to save them
	  	in.  If	the filename is invalid for the operating system /
	  	file system you are running Wireshark on, then an error
	  	will appear and that object will not be saved (but all
	  	of the others will be).
		</para></listitem>
	</itemizedlist>
	</section>
  </section>

  <section id="ChIOPrintSection"><title>Printing packets</title>
    <para>
	    To print packets, select the "Print..." menu item from the File menu. 
		When you do this, Wireshark pops up the Print dialog box as shown in 
	    <xref linkend="ChIOPrintDialogBox"/>.
    </para>
	<section><title>The "Print" dialog box</title>
    <figure id="ChIOPrintDialogBox">
      <title>The "Print" dialog box</title>
      <graphic entityref="WiresharkPrint" format="PNG"/>
    </figure>
    <para>
      The following fields are available in the Print dialog box:
      <variablelist>
	<varlistentry><term><command>Printer</command></term>
	  <listitem>
	    <para>
	      This field contains a pair of mutually exclusive radio buttons:
	      <itemizedlist>
		<listitem>
		  <para>
		    <command>Plain Text</command> specifies that 
		    the packet print should be in plain text.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    <command>PostScript</command> specifies that 
		    the packet print process should use PostScript to 
		    generate a better print output on PostScript aware printers.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    <command>Output to file:</command> specifies that printing 
		    be done to a file, using the filename entered in the field or selected 
			with the browse button.
		  </para>
	    <para>
	      This field is where you enter the <command>file</command> to 
	      print to if you have selected Print to a file, or you can click the 
		  button to browse the filesystem. It is greyed out if Print to a file 
		  is not selected.
	    </para>
		</listitem>
		<listitem>
		  <para>
		    <command>Print command</command> specifies that a 
		    command be used for printing. 
		  </para>
		<note><title>Note!</title>
		<para>
		These <command>Print command</command> fields are not available on 
		windows platforms. 
		</para>
		</note>
	    <para>
	      This field specifies the command to use for printing. It 
	      is typically <command>lpr</command>. You would change it 
	      to specify a particular queue if you need to print to a 
	      queue other than the default.  An example might be:
	      <programlisting>
lpr -Pmypostscript
	      </programlisting>
	      This field is greyed out if <command>Output to file:</command> is 
	      checked above.
	    </para>
		</listitem>
	      </itemizedlist>
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><command>Packet Range</command></term>
	  <listitem>
	    <para>
		  Select the packets to be printed, see <xref 
		  linkend="ChIOPacketRangeSection"/>
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><command>Packet Format</command></term>
	  <listitem>
	    <para>
		  Select the output format of the packets to be printed. You can 
		  choose, how each packet is printed, see 
		  <xref linkend="ChIOPacketFormatFrame"/>
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </para>
  </section>
  </section>

  <section id="ChIOPacketRangeSection"><title>The Packet Range frame</title>
	<para>
	The packet range frame is a part of various output related dialog boxes. 
	It provides options to select which packets should be processed by the 
	output function.
    <figure id="ChIOPacketRangeFrame">
      <title>The "Packet Range" frame</title>
      <graphic entityref="WiresharkPacketRangeFrame" format="PNG"/>
    </figure>
	</para>
	<para>
	If the <command>Captured</command> button is set (default), all packets 
	from the selected rule will be processed. If the <command>Displayed
	</command> button is set, only the currently displayed packets are taken 
	into account to the selected rule.
	</para>
	<para>
	<itemizedlist>
		<listitem>
		  <para>
		  <command>All packets</command> will process all packets.
		  </para>
		</listitem>
		<listitem>
		  <para>
		  <command>Selected packet only</command> process only the selected 
		  packet.
		  </para>
		</listitem>
		<listitem>
		  <para>
		  <command>Marked packets only</command> process only the marked 
		  packets.
		  </para>
		</listitem>
		<listitem>
		  <para>
		  <command>From first to last marked packet</command> process the 
		  packets from the first to the last marked one.
		  </para>
		</listitem>
		<listitem>
		  <para>
		  <command>Specify a packet range</command> process a user specified 
		  range of packets, e.g. specifying <command>5,10-15,20-</command> will 
		  process the packet number five, the packets from packet number ten 
		  to fifteen (inclusive) and every packet from number twenty to the 
		  end of the capture.
		  </para>
		</listitem>
	</itemizedlist>
	</para>
  </section>
  
  <section id="ChIOPacketFormatSection"><title>The Packet Format frame</title>
	<para>
	The packet format frame is a part of various output related dialog boxes. 
	It provides options to select which parts of a packet should be used for 
	the output function.
    <figure id="ChIOPacketFormatFrame">
      <title>The "Packet Format" frame</title>
      <graphic entityref="WiresharkPacketFormatFrame" format="PNG"/>
    </figure>
	<itemizedlist>
		<listitem>
		  <para>
		  <command>Packet summary line</command> enable the output of the 
		  summary line, just as in the "Packet List" pane.
		  </para>
		</listitem>
		<listitem>
		  <para>
		  <command>Packet details</command> enable the output of the packet 
		  details tree.
		  </para>
		<itemizedlist>
		<listitem>
		  <para>
		  <command>All collapsed</command> the info from the "Packet Details" 
		  pane in "all collapsed" state.
		  </para>
		</listitem>
		<listitem>
		  <para>
		  <command>As displayed</command> the info from the "Packet Details" 
		  pane in the current state.
		  </para>
		</listitem>
		<listitem>
		  <para>
		  <command>All expanded</command> the info from the "Packet Details" 
		  pane in "all expanded" state.
		  </para>
		</listitem>
		</itemizedlist>
		</listitem>
		<listitem>
		  <para>
		  <command>Packet bytes</command> enable the output of the packet 
		  bytes, just as in the "Packet Bytes" pane.
		  </para>
		</listitem>
		<listitem>
		  <para>
		  <command>Each packet on a new page</command> put each packet on a 
		  separate page (e.g. when saving/printing to a text file, this will 
		  put a form feed character between the packets).
		  </para>
		</listitem>
	</itemizedlist>
	</para>
  </section>
  
</chapter>
<!-- End of WSUG Chapter IO -->