Ethereal Developer's Guide

Draft 0.0.2 (15684) for Ethereal 0.10.11

Ulf Lamping


Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any later version published by the Free Software Foundation.

All logos and trademarks in this document are property of their respective owner.


Table of Contents

Preface
1. Foreword
2. Who should read this document?
3. Acknowledgements
4. About this document
5. Where to get the latest copy of this document?
6. Providing feedback about this document
I. Ethereal Build Environment
1. Introduction
1.1. Introduction
1.2. What is Ethereal?
1.3. Platforms Ethereal runs on
1.3.1. Unix
1.3.2. Linux
1.3.3. Microsoft Windows
1.4. Development and maintenance of Ethereal
1.4.1. Programming language(s) used
1.4.2. Open Source Software
1.5. Releases and distributions
1.5.1. Binary distributions
1.5.2. Source code distributions
1.6. Reporting problems and getting help
1.6.1. Website
1.6.2. Wiki
1.6.3. FAQ
1.6.4. Mailing Lists
1.6.5. Bug database
1.6.6. Reporting Problems
1.6.7. Reporting Crashes on UNIX/Linux platforms
1.6.8. Reporting Crashes on Windows platforms
1.7. Other sources of developer information
2. Tools
2.1. Introduction
2.2. Installation
2.2.1. UNIX
2.2.2. Win32 native
2.2.3. Win32 Cygwin
2.3. Win32: Recommended tools
2.4. bash
2.4.1. UNIX: GNU bash
2.4.2. Win32 native: -
2.5. C compiler
2.5.1. UNIX: GCC (GNU compiler collection)
2.5.2. Win32 native: Microsoft Visual Studio version 6 C compiler
2.5.3. Win32 native: Microsoft Visual Studio .NET (and alike) C compilers
2.6. Debugger
2.6.1. UNIX: GDB (GNU project debugger)
2.6.2. UNIX: DDD (GNU Data Display Debugger)
2.6.3. Win32 native: Microsoft Visual Studio debugger
2.6.4. Win32 native: Microsoft Debugging Tools for Windows
2.7. make
2.7.1. Unix: GNU Make
2.7.2. Win32 native: nmake from MSVC
2.7.3. Win32 native: nmake from microsoft.com
2.8. python
2.8.1. UNIX: python
2.8.2. Win32 native: python
2.9. perl
2.9.1. UNIX: perl
2.9.2. Win32 native: perl
2.10. sed
2.10.1. UNIX: sed
2.10.2. Win32 native: sed
2.11. yacc (bison)
2.11.1. UNIX: bison
2.11.2. Win32 native: bison
2.12. lexx (flex)
2.12.1. UNIX: flex
2.12.2. Win32 native: flex
2.13. Subversion (SVN) client (optional)
2.13.1. UNIX: svn
2.13.2. Win32 native: TortoiseSVN
2.14. diff (optional)
2.14.1. UNIX: GNU diff
2.14.2. Win32 native: diff
2.15. patch (optional)
2.15.1. UNIX: patch
2.15.2. Win32 native: patch
2.16. Win32: GNU wget (optional)
2.17. Win32: NSIS (optional)
2.18. Obsolete: CVS client
2.19. Win32: Verify installed tools
3. Libraries
3.1. Introduction
3.2. Binary library formats
3.2.1. Unix
3.2.2. Win32: MSVC V6
3.2.3. Win32: MSVC 2003
3.2.4. Win32: cygwin gcc
3.3. Win32: Automated library download
3.3.1. Update of a previous download
3.4. GTK+ / GLib / GDK / Pango / ATK / GNU gettext / GNU libiconv
3.4.1. Unix
3.4.2. Win32 MSVC
3.5. Net SNMP (previously known as "ucd-snmp")
3.5.1. Unix
3.5.2. Win32 MSVC
3.6. GNU ADNS (optional)
3.6.1. Unix
3.6.2. Win32 MSVC
3.7. PCRE(optional)
3.7.1. Unix
3.7.2. Win32 MSVC
3.8. zlib (optional)
3.8.1. Unix
3.8.2. Win32 MSVC
3.9. libpcap/WinPcap (optional)
3.9.1. Unix: libpcap
3.9.2. Win32 MSVC: WinPcap
3.10. Win32: GTK WIMP (optional) for GTK 2.x only
4. Work with the Ethereal sources
4.1. Introduction
4.2. The Ethereal Subversion repository
4.3. The web interface to the Subversion repository
4.4. Obtain the Ethereal sources
4.4.1. Anonymous Subversion access
4.4.2. Anonymous Subversion web interface
4.4.3. Nightly snapshots
4.4.4. Released sources
4.5. Update the Ethereal sources
4.5.1. ... with Anonymous Subversion access
4.5.2. ... from zip files
4.6. Build Ethereal for the first time
4.6.1. Unix
4.6.2. Win32 native
4.7. Run generated Ethereal for the first time
4.8. Debug your generated Ethereal
4.8.1. Win32 native
4.9. Make changes to the Ethereal sources
4.10. Commit changed sources
4.10.1. What is a diff file (a patch)?
4.10.2. Generate a patch
4.10.3. Some tips for a good patch
4.10.4. Sending your patch to the developer mailing list
4.11. Apply a patch from someone else
4.12. Add a new file to the Subversion repository
4.13. Binary packaging
4.13.1. Debian: .deb packages
4.13.2. Red Hat: .rpm packages
4.13.3. Win32: NSIS .exe installer
II. Ethereal Development (incomplete)
5. How Ethereal Works
5.1. Introduction
5.2. Overview
5.3. Capturing packets
5.4. Capture Files
5.5. Dissect packets
6. Introduction
6.1. Source overview
6.2. Coding styleguides
6.3. The GLib library
7. Packet capturing
7.1. How to add a new capture type to libpcap
8. Packet dissection
8.1. How it works
8.2. Adding a basic dissector
8.2.1. Setting up the dissector
8.2.2. Dissecting the details of the protocol
8.2.3. Improving the dissection information
8.3. How to handle transformed data
8.4. How to reassemble split packets
8.4.1. How to reassemble split UDP packets
8.5. How to tap protocols
8.6. How to produce protocol stats
8.7. How to use conversations
9. User Interface
9.1. Introduction
9.2. The GTK library
9.2.1. GTK Version 1.x
9.2.2. GTK Version 2.x
9.2.3. Compatibility between 1.x and 2.x
9.2.4. GTK resources on the web
9.3. GUI Reference documents
9.4. Adding/Extending Dialogs
9.5. Widget naming
9.6. Common GTK programming pitfalls
9.6.1. Usage of gtk_widget_show() / gtk_widget_show_all()
A. This Document's License (GPL)

List of Figures

5.1. Ethereal function blocks.

List of Tables

2.1. The mandatory tools
2.2. The optional tools
4.1. Some useful diff options

List of Examples

8.1. Basic Plugin setup.
8.2. Plugin Initialisation.
8.3. Plugin Handoff.
8.4. Plugin Dissection.
8.5. Makefile.nmake for Windows.
8.6. Makefile.am for unix/linux.
8.7. Plugin Packet Dissection.
8.8. Plugin Registering data structures.
8.9. Plugin Registering data structures.
8.10. Plugin data structure globals.
8.11. Plugin starting to dissect the packets.
8.12. Plugin wrapping up the packet dissection.
8.13. Naming the packet types.
8.14. Adding Names to the protocol.
8.15. Adding Flags to the protocol.
8.16. Enhancing the display.
8.17. Decompressing data packets for dissection.
8.18. Reassembling fragments - Part 1
8.19. Reassembling fragments part 2
8.20. Reassembling fragments - Initialisation
8.21. Reassembling fragments - Data
8.22. Initialising a tap
8.23. Calling a protocol tap
8.24. Initialising a stats interface
8.25. Initialising a stats session
8.26. Generating the stats