WSUG: Convert the ``File I/O'' chapter to AsciiDoc.

Leave most of the content intact for now. Remove images for
no-longer-supported versions of GTK+. Add an example for building the
Guides to README.cmake.

Change-Id: Id9e6a308c91b594d1fb7f107d7b9b28074a92a8b
Reviewed-on: https://code.wireshark.org/review/3931
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot <buildbot-no-reply@wireshark.org>
Reviewed-by: Gerald Combs <gerald@wireshark.org>

1 files changed, 928 insertions, 0 deletions

diff --git a/docbook/wsug_src/WSUG_chapter_io.asciidoc b/docbook/wsug_src/WSUG_chapter_io.asciidoc
new file mode 100644
index 0000000000..adaf72a65c
--- /dev/null
+++ b/docbook/wsug_src/WSUG_chapter_io.asciidoc
@@ -0,0 +1,928 @@
+++++++++++++++++++++++++++++++++++++++
+<!-- WSUG Chapter IO -->
+++++++++++++++++++++++++++++++++++++++
+
+[[ChapterIO]]
+
+== File Input, Output, and Printing
+
+[[ChIOIntroductionSection]]
+
+=== Introduction
+
+This chapter will describe input and output of capture data.
+
+* Open capture files in various capture file formats
+
+* Save/Export capture files in various capture file formats
+
+* Merge capture files together
+
+* Import text files containing hex dumps of packets
+
+* Print packets
+
+[[ChIOOpenSection]]
+
+=== Open capture files
+
+Wireshark can read in previously saved capture files. To read them, simply
+select the menu:File[Open] menu or toolbar item. Wireshark will then pop up
+the ``File Open'' dialog box, which is discussed in more detail in <<ChIOOpen>>.
+
+[TIP]
+.It's convenient to use drag-and-drop
+====
+You can open a file by simply dragging it in your file manager and dropping it
+onto Wireshark's main window. However, drag-and-drop may not be available in all
+desktop environments.
+====
+
+If you haven't previously saved the current capture file you will be asked to
+do so to prevent data loss. This warning can be disabled in the preferences.
+
+In addition to its native file format (pcapng), Wireshark can read and write
+capture files from a large number of other packet capture programs as well. See
+<<ChIOInputFormatsSection>> for the list of capture formats Wireshark
+understands.
+
+[[ChIOOpen]]
+
+==== The ``Open Capture File'' dialog box
+
+The ``Open Capture File'' dialog box allows you to search for a capture file
+containing previously captured packets for display in Wireshark. The following
+sections show some examples of the Wireshark ``Open File'' dialog box. The
+appearance of this dialog depends on the system. However, the functionality
+should be the same across systems.
+
+Common dialog behaviour on all systems:
+
+* Select files and directories.
+
+* Click the button:[Open] or button:[OK] button to accept your selected file and
+  open it.
+
+* Click the button:[Cancel] button to go back to Wireshark and not load a capture file.
+
+Wireshark extensions to the standard behaviour of these dialogs:
+
+* View file preview information such as the filesize and the number of packets
+  in a selected a capture file.
+
+* Specify a display filter with the button:[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 button:[Filter] button causes Wireshark to pop up the ``Filters''
+  dialog box (which is discussed further in <<ChWorkDisplayFilterSection>>).
++
+// XXX - we need a better description of these read filters
+
+* 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 <<ChAdvNameResolutionSection>>.
+
+[TIP]
+.Save a lot of time loading huge capture files
+====
+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.
+====
+
+[[ChIOOpenFileDialogWin32]]
+
+.``Open'' on Microsoft Windows
+image::wsug_graphics/ws-open-win32.png[]
+
+This is the common Windows file open dialog - plus some Wireshark extensions.
+
+Specific for this dialog:
+
+* The button:[Help] button will lead you to this section of this ``User's Guide''.
+
+[[ChIOOpenFileDialog]]
+
+.``Open'' - Linux and UNIX
+image::wsug_graphics/ws-open-gtk24.png[]
+
+This is the common Gimp/GNOME file open dialog plus some Wireshark extensions.
+
+Specific for this dialog:
+
+* The button:[+] button allows you to add a directory selected in the
+  right-hand pane to the favorites list on the left. These changes are
+  persistent.
+
+* The button:[-] button allows you to remove a selected directory from the list.
+  Some items (such as ``Desktop'') cannot be removed from the favorites list.
+
+* If Wireshark doesn't recognize the selected file as a capture file it will
+  grey out the button:[Open] button.
+
+// XXX Add OS X
+
+
+[[ChIOInputFormatsSection]]
+
+
+==== Input File Formats
+
+The following file formats from other capture tools can be opened by Wireshark:
+
+* pcapng. A flexible, etensible successor to the libpcap format. Wireshark 1.8 and later
+  save files as pcapng by default. Versions prior to 1.8 used libpcap.
+
+* libpcap. The default format used by the _libpcap_ packet capture library. Used
+  by _tcpdump, _Snort_, _Nmap_, _Ntop_, and many other tools.
+
+* Oracle (previously Sun) _snoop_ and _atmsnoop_
+
+* Finisar (previously Shomiti) _Surveyor_ captures
+
+* Microsoft _Network Monitor_ captures
+
+* Novell _LANalyzer_ captures
+
+* AIX _iptrace_ captures
+
+* Cinco Networks NetXray captures
+
+* Network Associates Windows-based Sniffer and Sniffer Pro captures
+
+* Network General/Network Associates DOS-based Sniffer (compressed or uncompressed) captures
+
+* AG Group/WildPackets EtherPeek/TokenPeek/AiroPeek/EtherHelp/PacketGrabber captures
+
+* RADCOM's WAN/LAN Analyzer captures
+
+* Network Instruments Observer version 9 captures
+
+* Lucent/Ascend router debug output
+
+* HP-UX's nettl
+
+* Toshiba's ISDN routers dump output
+
+* ISDN4BSD _i4btrace_ utility
+
+* traces from the EyeSDN USB S0
+
+* IPLog format from the Cisco Secure Intrusion Detection System
+
+* pppd logs (pppdump format)
+
+* the output from VMS's TCPIPtrace/TCPtrace/UCX$TRACE utilities
+
+* the text output from the DBS Etherwatch VMS utility
+
+* Visual Networks' Visual UpTime traffic capture
+
+* the output from CoSine L2 debug
+
+* the output from Accellent's 5Views LAN agents
+
+* Endace Measurement Systems' ERF format captures
+
+* Linux Bluez Bluetooth stack hcidump -w traces
+
+* Catapult DCT2000 .out files
+
+* Gammu generated text output from Nokia DCT3 phones in Netmonitor mode
+
+* IBM Series (OS/400) Comm traces (ASCII &amp; UNICODE)
+
+* Juniper Netscreen snoop captures
+
+* Symbian OS btsnoop captures
+
+* Tamosoft CommView captures
+
+* Textronix K12xx 32bit .rf5 format captures
+
+* Textronix K12 text file format captures
+
+* Apple PacketLogger captures
+
+* Captures from Aethra Telecommunications' PC108 software for their test instruments
+
+New file formats are added from time to time.
+
+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 such as PPP or IEEE 802.11 from
+all file formats.
+
+[[ChIOSaveSection]]
+
+=== Saving captured packets
+
+You can save captured packets simply by using the menu:File[Save As...] menu
+item. You can choose which packets to save and which file format to be used.
+
+Not all information will be saved in a capture file. For example, most file
+formats don't record the number of dropped packets. See
+<<ChAppFilesCaptureFilesSection>> for details.
+
+[[ChIOSaveAs]]
+
+==== The ``Save Capture File As'' dialog box
+
+The ``Save Capture File As'' dialog box allows you to save the current capture
+to a file. The following sections show some examples of this dialog box. The
+appearance of this dialog depends on the system. However, the functionality
+should be the same across systems.
+
+[[ChIOSaveAsFileWin32]]
+
+.``Save'' on Microsoft Windows
+image::wsug_graphics/ws-save-as-win32.png[]
+
+This is the common Windows file save dialog with some additional Wireshark extensions.
+
+Specific behavior for this dialog:
+
+* If available, the ``Help'' button will lead you to this section of this "User's Guide".
+
+* 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.
+
+[[ChIOSaveAsFile2]]
+
+.``Save'' on Linux and UNIX
+image::wsug_graphics/ws-save-as-gtk24.png[]
+
+This is the common Gimp/GNOME file save dialog with additional Wireshark extensions.
+
+Specific for this dialog:
+
+* Clicking on the + at "Browse for other folders" will allow you to browse files and folders in your file system.
+
+// XXX Add OS X
+
+With this dialog box, you can perform the following actions:
+
+. Type in the name of the file you wish to save the captured packets in, as a
+  standard file name in your file system.
+
+. Select the directory to save the file into.
+
+. Select the range of the packets to be saved. See <<ChIOPacketRangeSection>>.
+
+. 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
+  <<ChIOOutputFormatsSection>>.
+
+Some capture formats may not be available depending on the packet types captured.
+
+[TIP]
+.Wireshark can convert file formats
+====
+You can convert capture files from one format to another by reading in a capture
+file and writing it out using a different format.
+====
+
+. Click the button:[Save] or button:[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 button:[OK]
+  on that error dialog box you can try again.
+
+. Click on the button:[Cancel] button to go back to Wireshark without saving any
+  packets.
+
+[[ChIOOutputFormatsSection]]
+
+==== Output File Formats
+
+Wireshark can save the packet data in its native file format (pcapng) and in the
+file formats of other protocol analyzers so other tools can read the capture
+data.
+
+
+[WARNING]
+.Different file formats have different time stamp accuracies
+====
+Saving from the currently used file format to a different format may reduce the
+time stamp accuracy; see the <<ChAdvTimestamps>> for details.
+====
+
+The following file formats can be saved by Wireshark (with the known file extensions):
+
+* pcapng ($$*$$.pcapng). A flexible, etensible successor to the libpcap format.
+  Wireshark 1.8 and later save files as pcapng by default. Versions prior to 1.8
+  used libpcap.
+
+* libpcap, tcpdump and various other tools using tcpdump's capture format ($$*$$.pcap,$$*$$.cap,$$*$$.dmp)
+
+* Accellent 5Views ($$*$$.5vw)
+
+* HP-UX's nettl ($$*$$.TRC0,$$*$$.TRC1)
+
+* Microsoft Network Monitor - NetMon ($$*$$.cap)
+
+* Network Associates Sniffer - DOS ($$*$$.cap,$$*$$.enc,$$*$$.trc,*fdc,$$*$$.syc)
+
+* Network Associates Sniffer - Windows ($$*$$.cap)
+
+* Network Instruments Observer version 9 ($$*$$.bfr)
+
+* Novell LANalyzer ($$*$$.tr1)
+
+* Oracle (previously Sun) snoop ($$*$$.snoop,$$*$$.cap)
+
+* Visual Networks Visual UpTime traffic ($$*.*$$)
+
+New file formats are added from time to time.
+
+Whether or not the above tools will be more helpful than Wireshark is a different question ;-)
+
+
+[NOTE]
+.Third party protocol analyzers may require specific file extensions
+====
+Wireshark examines a file's contents to determine its type. Some other protocol
+analyzers only look at a filename extensions. For example, you might need to use
+the `.cap` extension in order to open a file using _Sniffer_.
+====
+
+[[ChIOMergeSection]]
+
+=== Merging capture files
+
+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).
+
+There are three ways to merge capture files using Wireshark:
+
+* Use the menu:File[Merge] menu to open the ``Merge'' dialog. See
+  <<ChIOMergeDialog>>. This menu item will be disabled unless you have loaded a
+  capture file.
+
+* Use _drag-and-drop_ 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 the existing capture.
+
+* Use the `mergecap` tool, a command line tool to merge capture files.
+  This tool provides the most options to merge capture files. See
+  <<AppToolsmergecap>> for details.
+
+[[ChIOMergeDialog]]
+
+==== The ``Merge with Capture File'' dialog box
+
+This dialog box let you select a file to be merged into the currently loaded
+file. If your current data has not been saved you will be asked to save it
+first.
+
+Most controls of this dialog will work the same way as described in the ``Open
+Capture File'' dialog box, see <<ChIOOpen>>.
+
+Specific controls of this merge dialog are:
+
+_Prepend packets to existing file_::
+Prepend the packets from the selected file before the currently loaded packets.
+
+_Merge packets chronologically_::
+Merge both the packets from the selected and currently loaded file in chronological order.
+
+_Append packets to existing file_::
+Append the packets from the selected file after the currently loaded packets.
+
+
+[[ChIOMergeFileTab]]
+
+.The system specific ``Merge Capture File As'' dialog box
+
+[[ChIOMergeFileWin32]]
+
+.``Merge'' on Microsoft Windows
+image::wsug_graphics/ws-merge-win32.png[]
+
+This is the common Windows file open dialog with additional Wireshark extensions.
+
+[[ChIOMergeFile2]]
+
+.``Merge'' on Linux and UNIX
+image::wsug_graphics/ws-merge-gtk24.png[]
+
+This is the common Gimp/GNOME file open dialog with additional Wireshark extensions.
+
+
+[[ChIOImportSection]]
+
+=== Import hex dump
+
+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.
+
+Wireshark understands a hexdump of the form generated by `od -Ax -tx1 -v`. 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:
+
+----
+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 ........
+----
+
+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. Byte and hex numbers can be uppercase or
+lowercase. Any text before the offset is ignored, including email forwarding
+characters '&gt;'. Any lines of text between the bytestring lines are 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 preceded 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.)
+
+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.
+
+[[ChIOImportDialog]]
+
+==== The ``Import from Hex Dump'' dialog box
+
+This dialog box lets you select a text file, containing a hex dump of packet
+data, to be imported and set import parameters.
+
+[[ChIOFileImportDialog]]
+
+.The ``Import from Hex Dump'' dialog
+image::wsug_graphics/ws-file-import.png[]
+
+Specific controls of this import dialog are split in two sections:
+
+Input:: Determine which input file has to be imported and how it is to be
+interpreted.
+
+Import:: Determine how the data is to be imported.
+
+The input parameters are as follows:
+
+_Filename / Browse_::
+Enter the name of the text file to import. You can use _Browse_ to browse for a
+file.
+
+_Offsets_::
+Select the radix of the offsets given in the text file to import. This is
+usually hexadecimal, but decimal and octal are also supported.
+
+_Date/Time_::
+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.
+
+_Format_::
+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
+`strptime(3)`.
+
+The import parameters are as follows:
+
+_Encapsulation type_::
+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
+Wireshark understands, so as to pass the capture file contents to the right
+dissector.
+
+_Dummy header_::
+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.
+
+_Maximum frame length_::
+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 65535 bytes.
+
+Once all input and import parameters are setup click button:[OK] to start the
+import. If your current data wasn't saved before you will be asked to save it
+first.
+
+When completed there will be a new capture file loaded with the frames imported
+from the text file.
+
+[[ChIOFileSetSection]]
+
+=== File Sets
+
+When using the "Multiple Files" option while doing a capture (see:
+<<ChCapCaptureFiles>>), the capture data is spread over several capture files,
+called a file set.
+
+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.
+
+.How does Wireshark detect the files of a file set?
+****
+A filename in a file set uses the format Prefix_Number_DateTimeSuffix which
+might look something like `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.
+
+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.
+
+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.
+****
+
+The following features in the menu:File[File Set] submenu are available to work
+with file sets in a convenient way:
+
+*  The ``List Files'' dialog box will list the files Wireshark has recognized as
+   being part of the current file set.
+
+*  button:[Next File] closes the current and opens the next file in the file
+   set.
+
+*  button:[Previous File] closes the current and opens the previous file in the
+   file set.
+
+[[ChIOFileSetListDialog]]
+
+==== The ``List Files'' dialog box
+
+.The "List Files" dialog box
+image::wsug_graphics/ws-file-set-dialog.png[]
+
+Each line contains information about a file of the file set:
+
+*  _Filename_ 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.
+
+*  _Created_ the creation time of the file
+
+*  _Last Modified_ the last time the file was modified
+
+*  _Size_ the size of the file
+
+The last line will contain info about the currently used directory where all of
+the files in the file set can be found.
+
+The content of this dialog box is updated each time a capture file is
+opened/closed.
+
+The button:[Close] button will, well, close the dialog box.
+
+[[ChIOExportSection]]
+
+=== Exporting data
+
+Wireshark provides several ways and formats to export packet data. This section
+describes general ways to export data from the main Wireshark application. There
+are more specialized functions to export specific data which are described
+elsewhere.
+
+// XXX - add detailed descriptions of the output formats and some sample output, too.
+
+// XXX Most of this content is no longer relevant in the current GTK+ UI, much less Qt.
+
+[[ChIOExportPlainDialog]]
+
+==== The ``Export as Plain Text File'' dialog box
+
+[[ChIOExportPlain]]
+
+Export packet data into a plain ASCII text file, much like the format used to print packets.
+
+[TIP]
+====
+If you would like to be able to import any previously exported packets from a
+plain text file it is recommended that you:
+
+*  Add the ``Absolute date and time'' column.
+
+*  Temporarily hide all other columns.
+
+*  Disable the menu:Edit[Preferences,Protocols,Data] ``Show not dissected data
+   on new Packet Bytes pane'' preference. More details are provided in
+   <<ChCustPreferencesSection>>
+
+*  Include the packet summary line.
+
+*  Exclude column headings.
+
+*  Exclude packet details.
+
+*  Include the packet bytes.
+====
+
+.The ``Export as Plain Text File'' dialog box
+image::wsug_graphics/ws-export-plain.png[]
+
+*  The ``Export to file:'' frame chooses the file to export the packet data to.
+
+*  The ``Packet Range'' frame is described in <<ChIOPacketRangeSection>>.
+
+*  The ``Packet Details'' frame is described in <<ChIOPacketFormatSection>>.
+
+[[ChIOExportPSDialog]]
+
+==== The ``Export as PostScript File'' dialog box
+
+.The "Export as PostScript File" dialog box
+image::wsug_graphics/ws-export-ps.png[]
+
+*  _Export to file:_ frame chooses the file to export the packet data to.
+
+*  The _Packet Range_ frame is described in <<ChIOPacketRangeSection>>.
+
+*  The _Packet Details_ frame is described in <<ChIOPacketFormatSection>>.
+
+[[ChIOExportCSVDialog]]
+
+==== The "Export as CSV (Comma Separated Values) File" dialog box
+
+// XXX - add screenshot
+
+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>-->
+
+*  _Export to file:_ frame chooses the file to export the packet data to.
+
+*  The _Packet Range_ frame is described in <<ChIOPacketRangeSection>>.
+
+[[ChIOExportCArraysDialog]]
+
+==== The "Export as C Arrays (packet bytes) file" dialog box
+
+// XXX - add screenshot
+
+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>
+
+*  _Export to file:_ frame chooses the file to export the packet data to.
+
+*  The _Packet Range_ frame is described in <<ChIOPacketRangeSection>>.
+
+[[ChIOExportPSMLDialog]]
+
+==== The "Export as PSML File" dialog box
+
+Export packet data into PSML. This is an XML based format including only the
+packet summary. The PSML file specification is available at:
+link:$$http://www.nbee.org/doku.php?id=netpdl:psml_specification$$[].
+
+.The "Export as PSML File" dialog box
+image::wsug_graphics/ws-export-psml.png[]
+
+*  _Export to file:_ frame chooses the file to export the packet data to.
+
+*  The _Packet Range_ frame is described in <<ChIOPacketRangeSection>>.
+
+There's no such thing as a packet details frame for PSML export, as the packet
+format is defined by the PSML specification.
+
+[[ChIOExportPDMLDialog]]
+
+==== The "Export as PDML File" dialog box
+
+Export packet data into PDML. This is an XML based format including the packet
+details. The PDML file specification is available at:
+link:$$http://www.nbee.org/doku.php?id=netpdl:pdml_specification$$[].
+
+[NOTE]
+====
+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.
+====
+
+.The "Export as PDML File" dialog box
+image::wsug_graphics/ws-export-pdml.png[]
+
+*  _Export to file:_ frame chooses the file to export the packet data to.
+
+*  The _Packet Range_ frame is described in <<ChIOPacketRangeSection>>.
+
+There's no such thing as a packet details frame for PDML export, as the packet
+format is defined by the PDML specification.
+
+[[ChIOExportSelectedDialog]]
+
+==== The "Export selected packet bytes" dialog box
+
+Export the bytes selected in the "Packet Bytes" pane into a raw binary file.
+
+.The "Export Selected Packet Bytes" dialog box
+image::wsug_graphics/ws-export-selected.png[]
+
+*  _Name:_ the filename to export the packet data to.
+
+*  The _Save in folder:_ field lets you select the folder to save to (from some predefined folders).
+
+*  _Browse for other folders_ provides a flexible way to choose a folder.
+
+[[ChIOExportObjectsDialog]]
+
+==== The "Export Objects" dialog box
+
+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.
+
+.The "Export Objects" dialog box
+image::wsug_graphics/ws-export-objects.png[]
+
+*  _Packet num:_ The packet number in which this object was found. In some
+   cases, there can be multiple objects in the same packet.
+
+*  _Hostname:_ The hostname of the server that sent the object as a response to
+   an HTTP request.
+
+*  _Content Type:_ The HTTP content type of this object.
+
+*  _Bytes:_ The size of this object in bytes.
+
+*  _Filename:_ 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.
+
+*  _Help:_ Opens this section in the user's guide.
+
+*  _Close:_ Closes this dialog.
+
+*  _Save As:_ 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.
+
+*  _Save All:_ 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).
+
+[[ChIOPrintSection]]
+
+=== Printing packets
+
+To print packets, select the menu:File[Print...] menu item. When you
+do this Wireshark pops up the ``Print'' dialog box as shown in
+<<ChIOPrintDialogBox>>.
+
+==== The ``Print'' dialog box
+
+[[ChIOPrintDialogBox]]
+
+.The ``Print'' dialog box
+image::wsug_graphics/ws-print.png[]
+
+The following fields are available in the Print dialog box: _Printer_::
+This field contains a pair of mutually exclusive radio buttons:
+
+* _Plain Text_ specifies that the packet print should be in plain text.
+
+* _PostScript_ specifies that the packet print process should use PostScript to
+  generate a better print output on PostScript aware printers.
+
+* _Output to file:_ specifies that printing be done to a file, using the
+  filename entered in the field or selected with the browse button.
++
+This field is where you enter the _file_ 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.
+
+* _Print command_ specifies that a command be used for printing.
++
+[NOTE]
+.Note!
+====
+These _Print command_ fields are not available on windows platforms.
+====
++
+This field specifies the command to use for printing. It is typically `lpr`. 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:
++
+----
+$ lpr -Pmypostscript
+----
++
+This field is greyed out if _Output to file:_ is checked above.
+
+_Packet Range_::
+Select the packets to be printed, see <<ChIOPacketRangeSection>>
+
+_Packet Format_::
+Select the output format of the packets to be printed. You can choose, how each
+packet is printed, see <<ChIOPacketFormatFrame>>
+
+[[ChIOPacketRangeSection]]
+
+=== The ``Packet Range'' frame
+
+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.
+
+[[ChIOPacketRangeFrame]]
+
+.The ``Packet Range'' frame
+image::wsug_graphics/ws-packet-range.png[]
+
+If the button:[Captured] button is set (default), all packets from the selected rule
+will be processed. If the button:[Displayed] button is set, only the currently
+displayed packets are taken into account to the selected rule.
+
+* _All packets_ will process all packets.
+
+* _Selected packet only_ process only the selected packet.
+
+* _Marked packets only_ process only the marked packets.
+
+* _From first to last marked packet_ process the packets from the first to the
+  last marked one.
+
+* _Specify a packet range_ process a user specified range of packets, e.g.
+  specifying _5,10-15,20-_ 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.
+
+[[ChIOPacketFormatSection]]
+
+=== The Packet Format frame
+
+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.
+
+[[ChIOPacketFormatFrame]]
+
+.The ``Packet Format'' frame
+image::wsug_graphics/ws-packet-format.png[]
+
+* _Packet summary line_ enable the output of the summary line, just as in the
+  ``Packet List'' pane.
+
+* _Packet details_ enable the output of the packet details tree.
+
+* _All collapsed_ the info from the ``Packet Details'' pane in ``all collapsed''
+  state.
+
+* _As displayed_ the info from the ``Packet Details'' pane in the current state.
+
+* _All expanded_ the info from the ``Packet Details'' pane in ``all expanded''
+  state.
+
+* _Packet bytes_ enable the output of the packet bytes, just as in the ``Packet
+  Bytes'' pane.
+
+* _Each packet on a new page_ 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).
+
+++++++++++++++++++++++++++++++++++++++
+<!-- End of WSUG Chapter IO -->
+++++++++++++++++++++++++++++++++++++++
\ No newline at end of file