From 70ce24ded56a5c2fd50b38741e7dca7951c3b888 Mon Sep 17 00:00:00 2001 From: Bill Meier Date: Sat, 18 Dec 2010 18:07:36 +0000 Subject: [PATCH] Revert SVN #35213 based upon comments in the Wireshark-dev list. http://www.wireshark.org/lists/wireshark-dev/201012/msg00206.html svn path=/trunk/; revision=35219 --- docbook/wsdg_src/WSDG_chapter_build_intro.xml | 1088 +---------------- docbook/wsdg_src/WSDG_preface.xml | 80 +- 2 files changed, 85 insertions(+), 1083 deletions(-) diff --git a/docbook/wsdg_src/WSDG_chapter_build_intro.xml b/docbook/wsdg_src/WSDG_chapter_build_intro.xml index 3f92ada4c9..93106cf0b1 100644 --- a/docbook/wsdg_src/WSDG_chapter_build_intro.xml +++ b/docbook/wsdg_src/WSDG_chapter_build_intro.xml @@ -3,1041 +3,67 @@ Introduction - +
- Source overview - - Wireshark consists of the following major parts: - - - - Packet dissection - in the /epan/dissector and /plugin/* directory - - - - - File I/O - using Wireshark’s own wiretap library - - - - - Capture - using the libpcap/winpcap library, in /wiretap - - - - - User interface - using the GTK+ (and corresponding) libraries - - - - - Help - using an external webbrowser and GTK text output - - - - Beside this, some other minor parts and additional helpers exist. - + Source overview + + Wireshark consists of the following major parts: + + + Packet dissection - in the /epan/dissector and /plugin/* directory + + + File I/O - using Wireshark's own wiretap library + + + Capture - using the libpcap/winpcap library, in /wiretap + + + User interface - using the GTK+ (and corresponding) libraries + + + Help - using an external webbrowser and GTK text output + + + Beside this, some other minor parts and additional helpers exist. + + + Currently there's no clean separation of the modules in the code. + However, as the development team switched from Concurrent Versions System + (CVS) to Subversion (SVN) some time ago, + directory cleanup is much easier now. So there's a chance that + the directory structure will become clean in the future. +
- Coding Styleguide -
- Portability - - Wireshark runs on many platforms, and can be compiled with a number of - different compilers; here are some rules for writing code that will work - on multiple platforms. - - - - - Don’t use C++ style comments (comments beginning with // and running - to the end of the line); Wireshark’s dissectors are written in C, and - thus run through C rather than C++ compilers, and not all C compilers - support C++ style comments (GCC does, but IBM’s C compiler for AIX, for - example, doesn’t do so by default). - - - - - In general, don’t use C99 features since some C compilers used to compile - Wireshark don’t support C99 (e.g., Microsoft C). - - - - - Don’t initialize variables in their declaration with non-constant - values. Not all compilers support this. E.g., don’t use - - - guint32 i = somearray[2]; - - use - - guint32 i; - i = somearray[2]; - - instead. - - - - Don’t use zero-length arrays; not all compilers support them. If an - array would have no members, just leave it out. - - - - - Don’t declare variables in the middle of executable code; not all C - compilers support that. Variables should be declared outside a - function, or at the beginning of a function or compound statement. - - - - - Don’t use anonymous unions; not all compilers support them. - Example: - - -typedef struct foo { - guint32 foo; - union { - guint32 foo_l; - guint16 foo_s; - } u; /* have a name here */ -} foo_t; - - - - - Don’t use uchar, u_char, - ushort, u_short, uint, - u_int, - ulong, u_long or - boolean; they aren’t defined on all platforms. - If you want an 8-bit unsigned quantity, use guint8; if you want an - 8-bit character value with the 8th bit not interpreted as a sign bit, - use guchar; if you want a 16-bit unsigned quantity, - use guint16; - if you want a 32-bit unsigned quantity, use guint32; and if you want - an int-sized unsigned quantity, - use guint; if you want a boolean, - use gboolean. Use %d, %u, - %x, and %o to print those types; - don’t use %ld, %lu, - %lx, or %lo, as longs are 64 bits long on - many platforms, but guint32 is 32 bits long. - - - - - Don’t use long to mean signed 32-bit integer, and don’t use - unsigned long to mean unsigned 32-bit integer; - long’s are 64 bits - long on many platforms. Use gint32 for signed 32-bit integers and use - guint32 for unsigned 32-bit integers. - - - - - Don’t use long to mean signed 64-bit integer - and don’t use unsigned - long to mean unsigned 64-bit integer; A long is 32 bits long on - many other platforms. Don’t use long long or - unsigned long long, - either, as not all platforms support them; use gint64 or - guint64, - which will be defined as the appropriate types for 64-bit signed and - unsigned integers. - - - On LLP64 data model systems (notably 64-bit Windows), int and - long - are 32 bits while size_t and ptrdiff_t are 64 bits. - This means that - the following will generate a compiler warning: - - - int i; - i = strlen("hello, sailor"); /* Compiler warning */ - - Normally, you’d just make it a size_t. However, many GLib and Wireshark - functions won’t accept a size_t on LLP64: - - size_t i; - - char greeting[] = "hello, sailor"; - guint byte_after_greet; - - i = strlen(greeting); - byte_after_greet = tvb_get_guint8(tvb, i); /* Compiler warning */ - - Try to use the appropriate data type when you can. When you can’t, you - will have to cast to a compatible data type, e.g., - - - size_t i; - char greeting[] = "hello, sailor"; - guint byte_after_greet; - - i = strlen(greeting); - byte_after_greet = tvb_get_guint8(tvb, (gint) i); /* OK */ - - or - - gint i; - char greeting[] = "hello, sailor"; - guint byte_after_greet; - - i = (gint) strlen(greeting); - byte_after_greet = tvb_get_guint8(tvb, i); /* OK */ - - - See for more - information on the sizes of common types in different data models. - - - - - When printing or displaying the values of 64-bit integral data types, - don’t use %lld, %llu, - %llx, or %llo — not all platforms - support %ll for printing 64-bit integral data types. Instead, for - GLib routines, and routines that use them, such as all the routines in - Wireshark that take format arguments, use G_GINT64_MODIFIER, - for example: - - - proto_tree_add_text(tree, tvb, offset, 8, - "Sequence Number: %" G_GINT64_MODIFIER "u", - sequence_number); - - - - - When specifying an integral constant that doesn’t fit in 32 bits, don’t - use LL at the end of the constant — not all compilers use - LL for - that. Instead, put the constant in a call to the G_GINT64_CONSTANT() - macro, e.g., - - - G_GINT64_CONSTANT(11644473600U) - - rather than - - 11644473600ULL - - - - - Don’t assume that you can scan through a va_list - initialized by va_start() - more than once without closing it with va_end() and re-initalizing it with - va_start(). This applies even if you’re not scanning through it yourself, - but are calling a routine that scans through it, such as vfprintf() or - one of the routines in Wireshark that takes a format and a va_list as an - argument. You must do - - - va_start(ap, format); - call_routine1(xxx, format, ap); - va_end(ap); - va_start(ap, format); - call_routine2(xxx, format, ap); - va_end(ap); - - rather than - - va_start(ap, format); - call_routine1(xxx, format, ap); - call_routine2(xxx, format, ap); - va_end(ap); - - - - - Don’t use a label without a statement following it. For example, - something such as - - - if (...) { - - ... - -done: - } - - will not work with all compilers — you have to do - - if (...) { - - ... - -done: - ; - } - - with some statement, even if it’s a null statement, after the label. - - - - Don’t use bzero(), bcopy(), - or bcmp(); instead, use the ANSI C - routines - - - - - memset() (with zero as the second argument, so that it sets - all the bytes to zero); - - - - - memcpy() or memmove() (note that the first and second - arguments to memcpy() are in the reverse order to the - arguments to bcopy(); note also that bcopy() is typically - guaranteed to work on overlapping memory regions, while - memcpy() isn’t, so if you may be copying from one region to a - region that overlaps it, use memmove(), - not memcpy() — but - memcpy() might be faster as a result of not guaranteeing - correct operation on overlapping memory regions); - - - - - memcmp() (note that memcmp() returns 0, 1, or -1, doing - an ordered comparison, rather than just returning 0 for equal - and 1 for not equal, as bcmp() does). - - - - - Not all platforms necessarily have - bzero()/bcopy()/bcmp(), and - those that do might not declare them in the header file on which they’re - declared on your platform. - - - - - Don’t use index() or rindex(); - instead, use the ANSI C equivalents, - strchr() and strrchr(). Not all platforms necessarily have - index() or rindex(), - and those that do might not declare them in the - header file on which they’re declared on your platform. - - - - - Don’t fetch data from packets by getting a pointer to data in the packet - with tvb_get_ptr(), casting that pointer to a pointer to a structure, - and dereferencing that pointer. That pointer won’t necessarily be aligned - on the proper boundary, which can cause crashes on some platforms (even - if it doesn’t crash on an x86-based PC); furthermore, the data in a - packet is not necessarily in the byte order of the machine on which - Wireshark is running. Use the tvbuff routines to extract individual - items from the packet, or use proto_tree_add_item() and let it extract - the items for you. - - - - - Don’t use structures that overlay packet data, or into which you copy - packet data; the C programming language does not guarantee any - particular alignment of fields within a structure, and even the - extensions that try to guarantee that are compiler-specific and not - necessarily supported by all compilers used to build Wireshark. Using - bitfields in those structures is even worse; the order of bitfields - is not guaranteed. - - - - - Don’t use ntohs(), ntohl(), - htons(), or htonl(); the header - files required to define or declare them differ between platforms, and - you might be able to get away with not including the appropriate header - file on your platform but that might not work on other platforms. - Instead, use g_ntohs(), g_ntohl(), - g_htons(), and g_htonl(); - those are declared by <glib.h>, and you’ll - need to include that anyway, - as Wireshark header files that all dissectors must include use stuff from - <glib.h>. - - - - - Don’t fetch a little-endian value using tvb_get_ntohs() or - tvb_get_ntohl() and then using g_ntohs(), - g_htons(), g_ntohl(), - or g_htonl() on the resulting value — the g_ - routines in question - convert between network byte order (big-endian) and - host byte order, - not little-endian byte order; - not all machines on which Wireshark runs - are little-endian, even though PCs are. Fetch those values using - tvb_get_letohs() and tvb_get_letohl(). - - - - - Don’t put a comma after the last element of an - enum — some compilers may - either warn about it (producing extra noise) or refuse to accept it. - - - - - Don’t include <unistd.h> without protecting it with - - -#ifdef HAVE_UNISTD_H - -... - -#endif - - - and, if you’re including it to get routines such - as close(), - read(), and write() - declared, also #include <io.h> if present: - - -#ifdef HAVE_IO_H -#include <io.h> -#endif - - - in order to declare the Windows C library routines - _close(), _read(), - and _write(). - - Your file must include <glib.h> — which - many of the Wireshark header files include, so you might not have - to include it explicitly — in order to get close(), - read(), write(), etc. mapped - to _close(), _read(), - _write(), etc. - - - - Do not use open(), rename(), - mkdir(), stat(), - unlink(), remove(), - fopen(), freopen() directly. - Instead, use ws_open(), ws_rename(), - ws_mkdir(), ws_stat(), - ws_unlink(), ws_remove(), - ws_fopen(), - ws_freopen(); these wrapper functions change - the path and file name from - UTF8 to UTF16 on Windows allowing the functions to work correctly when the - path or file name contain non-ASCII characters. - - - - - When opening a file with ws_fopen(), - ws_freopen(), or ws_fdopen(), if - the file contains ASCII text, use "r", - "w", "a", - and so on as the open mode; - if it contains binary data, use "rb", - "wb", and so on. On - Windows, if a file is opened in a text mode, writing a byte with the - value of octal 12 (newline) to the file causes two bytes, one with the - value octal 15 (carriage return) and one with the value octal 12, to be - written to the file, and causes bytes with the value octal 15 to be - discarded when reading the file (to translate between C’s UNIX-style - lines that end with newline and Windows’ DEC-style lines that end with - carriage return/line feed). - - - In addition, that also means that when opening or creating a binary - file, you must use ws_open() - (with O_CREAT and possibly O_TRUNC if the - file is to be created if it doesn’t exist), - and OR in the O_BINARY flag. - That flag is not present on most, if not all, UNIX systems, so you must - also do - - -#ifndef O_BINARY -#define O_BINARY 0 -#endif - - to properly define it for UNIX (it’s not necessary on UNIX). - - - - Don’t use forward declarations of static arrays without a specified size - in a fashion such as this: - - -static const value_string foo_vals[]; - -... - -static const value_string foo_vals[] = { - { 0, "Red" }, - { 1, "Green" }, - { 2, "Blue" }, - { 0, NULL } -}; - - - as some compilers will reject the first of those statements. Instead, - initialize the array at the point at which it’s first declared, so that - the size is known. - - - - - Don’t put a comma after the last tuple of an initializer of an array. - - - - - For #define names and enum member names, - prefix the names with a tag so - as to avoid collisions with other names — this might be more of an issue - on Windows, as it appears to #define names such as - DELETE and - OPTIONAL. - - - - - Don’t use the “numbered argument” feature that - many UNIX printf’s - implement, e.g., - - - g_snprintf(add_string, 30, " - (%1$d) (0x%1$04x)", value); - - - as not all UNIX printf’s implement it, - and Windows printf doesn’t appear - to implement it. Use something like - - - g_snprintf(add_string, 30, " - (%d) (0x%04x)", value, value); - - instead. - - - - Don’t use “variadic macros”, such as - - -#define DBG(format, args...) fprintf(stderr, format, ## args) - - - as not all C compilers support them. Use macros that take a fixed - number of arguments, such as - - -#define DBG0(format) fprintf(stderr, format) -#define DBG1(format, arg1) fprintf(stderr, format, arg1) -#define DBG2(format, arg1, arg2) fprintf(stderr, format, arg1, arg2) - ... - - or something such as - -#define DBG(args) printf args - - - - - Don’t use - - - case N ... M: - - as that’s not supported by all compilers. - - - - Use g_snprintf() instead of snprintf(). - snprintf() is not available on all platforms, - so it’s a good idea to use the - g_snprintf() function declared by <glib.h> instead. - - - - - Use mkstemp() instead of tmpnam(). - tmpnam() is insecure and should not be used - any more. Wireshark brings its - own mkstemp() implementation for use on platforms - that lack mkstemp(). - Note: mkstemp() does not accept NULL - as a parameter. - - - - - The pointer returned by a call to tvb_get_ptr() - is not guaranteed to be - aligned on any particular byte boundary; this means that you cannot - safely cast it to any data type other than a pointer to char, - unsigned char, guint8, - or other one-byte data types. You cannot, - for example, safely cast it to a pointer to a structure, and then access - the structure members directly; on some systems, unaligned accesses to - integral data types larger than 1 byte, and floating-point data types, - cause a trap, which will, at best, result in the OS slowly performing an - unaligned access for you, and will, on at least some platforms, cause - the program to be terminated. - - - - - Wireshark supports platforms with GLib 2.4[.x]/GTK+ 2.4[.x] or newer. - If a Glib/GTK+ mechanism is available only in Glib/GTK+ versions - newer than 2.4/2.4 then use #if GTK_CHECK_VERSION(...) - to conditionally - compile code using that mechanism. - - - - - When different code must be used on UN*X and Win32, use a - #if or #ifdef - that tests _WIN32, not WIN32. - Try to write code portably whenever - possible, however; note that there are some routines in Wireshark with - platform-dependent implementations and platform-independent APIs, such - as the routines in epan/filesystem.c, - allowing the code that calls it to - be written portably without #ifdefs. - - - -
-
- String handling - - - - Do not use functions such as strcat() or strcpy(). - A lot of work has been done to remove the existing calls to these functions and - we do not want any new callers of these functions. - - - Instead, use g_snprintf() since that - function will, if used correctly, prevent - buffer overflows for large strings. - - - - - When using a buffer to create a string, do not use a buffer stored on the stack. - I.e., do not use a buffer declared as - - - char buffer[1024]; - - - instead, allocate a buffer dynamically using the string-specific - or plain emem - routines (see doc/README.malloc) such as - - - emem_strbuf_t *strbuf; - strbuf = ep_strbuf_new_label(""); - ep_strbuf_append_printf(strbuf, ... - - or - - char *buffer=NULL; - ... - -#define MAX_BUFFER 1024 - - buffer=ep_alloc(MAX_BUFFER); - buffer[0]='\0'; - ... - g_snprintf(buffer, MAX_BUFFER, ... - - - This avoids corrupting the stack in case there is a bug in your code - that accidentally writes beyond the end of the buffer. - - - - - If you write a routine that will create and return a pointer to a filled-in - string and if that buffer will not be further processed or appended to after - the routine returns (except being added to the proto tree), - do not preallocate the buffer to fill in and pass as a parameter. Instead, - pass a pointer to a pointer to the function and return a pointer to an - emem allocated buffer that will be automatically freed. - (see doc/README.malloc) - - I.e., do not write code such as - -static void -foo_to_str(char *string, ... ) { - <fill in string> -} - ... - char buffer[1024]; - ... - foo_to_str(buffer, ... - proto_tree_add_text(... buffer ... - - instead, write the code as - -static void -foo_to_str(char **buffer, ...) { - -#define MAX_BUFFER x - - *buffer=ep_alloc(MAX_BUFFER); - <fill in *buffer> -} - ... - char *buffer; - ... - foo_to_str(&buffer, ... - proto_tree_add_text(... *buffer ...); - - - - - Allocate buffers by using ep_alloc(). - These buffers are very fast and nice. They are all - automatically freed by calling g_free() when - the dissection of the current packet ends so you - don’t have to worry about doing so - explicitly in order to not leak memory. - Please read doc/README.malloc. - - - - - Don’t use non-ASCII characters in source files; not all compiler - environments will be using the same encoding for non-ASCII characters, - and at least one compiler (Microsoft’s Visual C) will, in environments - with double-byte character encodings, such as many Asian environments, - fail if it sees a byte sequence in a source file that doesn’t correspond - to a valid character. This causes source files using either an ISO - 8859/n single-byte character encoding or UTF-8 to fail to compile. Even - if the compiler doesn’t fail, there is no guarantee that the compiler, - or a developer’s text editor, will interpret the characters the way you - intend them to be interpreted. - - - -
-
- Robustness - - Wireshark is not guaranteed to read only network traces that contain - correctly-formed packets. Wireshark is commonly used to track down networking - problems, and the problems might be due to a buggy protocol implementation - sending out bad packets. - - - Therefore, protocol dissectors not only have to be able to handle - correctly-formed packets without, for example, crashing or looping - infinitely, they also have to be able to handle - incorrectly-formed - packets without crashing or looping infinitely. - - - Here are some suggestions for making dissectors more robust in the face - of incorrectly-formed packets: - - - - - Do NOT use g_assert() - or g_assert_not_reached() in dissectors. - - - NO value in a packet’s data - should be considered “wrong” in the sense - that it’s a problem with the dissector if found; if it cannot do - anything else with a particular value from a packet’s data, the - dissector should put into the protocol tree an indication that the - value is invalid, and should return. The “expert” mechanism should be - used for that purpose. - - - If there is a case where you are checking not for an invalid data item - in the packet, but for a bug in the dissector (for example, an - assumption being made at a particular point in the code about the - internal state of the dissector), use the DISSECTOR_ASSERT() - macro for - that purpose; this will put into the protocol tree an indication that - the dissector has a bug in it, and will not crash the application. - - - - - If you are allocating a chunk of memory to contain data from a packet, - or to contain information derived from data in a packet, and the size of - the chunk of memory is derived from a size field in the packet, make - sure all the data is present in the packet before allocating the buffer. - Doing so means that: - - - - - Wireshark won’t leak that chunk of memory if an attempt to - fetch data not present in the packet throws an exception. - - - - - Wireshark won’t crash trying to allocate an absurdly-large chunk of - memory if the size field has a bogus large value. - - - - - If you’re fetching into such a chunk of memory a string from the buffer, - and the string has a specified size, you can use tvb_get_*_string(), - which will check whether the entire string is present before allocating - a buffer for the string, and will also put a trailing '\0' at the end of - the buffer. - - - If you’re fetching into such a chunk of memory a 2-byte Unicode string - from the buffer, and the string has a specified size, you can use - tvb_get_ephemeral_faked_unicode(), which will check whether the entire - string is present before allocating a buffer for the string, and will also - put a trailing '\0' at the end of the buffer. The resulting string will be - a sequence of single-byte characters; the only Unicode characters that - will be handled correctly are those in the ASCII range. (Wireshark’s - ability to handle non-ASCII strings is limited; it needs to be - improved). - - - If you’re fetching into such a chunk of memory a sequence of bytes from - the buffer, and the sequence has a specified size, you can use - tvb_memdup(), which will check whether the entire sequence is present - before allocating a buffer for it. - - - Otherwise, you can check whether the data is present by using - tvb_ensure_bytes_exist() or by getting a pointer to the data by using - tvb_get_ptr(), although note that there might be problems with using - the pointer from tvb_get_ptr() (see the item on this in the - Portability section above, and the next item below). - - - Note also that you should only fetch string data into a fixed-length - buffer if the code ensures that no more bytes than will fit into the - buffer are fetched (“the protocol ensures” isn’t good enough, as - protocol specifications can’t ensure only packets that conform to the - specification will be transmitted or that only packets for the protocol - in question will be interpreted as packets for that protocol by - Wireshark). If there’s no maximum length of string data to be fetched, - routines such as tvb_get_*_string() are safer, as they allocate a buffer - large enough to hold the string. (Note that some variants of this call - require you to free the string once you’re finished with it). - - - - - If you have gotten a pointer using tvb_get_ptr(), you must make sure - that you do not refer to any data past the length passed as the last - argument to tvb_get_ptr(); while the various - tvb_get...() routines - perform bounds checking and throw an exception if you refer to data not - available in the tvbuff, direct references through a pointer gotten from - tvb_get_ptr() do not do any bounds checking. - - - - - If you have a loop that dissects a sequence of items, each of which has - a length field, with the offset in the tvbuff advanced by the length of - the item, then, if the length field is the total length of the item, and - thus can be zero, you MUST - check for a zero-length item and abort the - loop if you see one. Otherwise, a zero-length item could cause the - dissector to loop infinitely. You should also check that the offset, - after having the length added to it, is greater than the offset before - the length was added to it, if the length field is greater than 24 bits - long, so that, if the length value is very - large and adding it to the - offset causes an overflow, that overflow is detected. - - - - - If you have a - - - for (i = {start}; i < {end}; i++) - - - loop, make sure that the type of the loop index variable is large enough - to hold the maximum {end} variable plus 1; Otherwise the loop index variable - can overflow before it ever reaches its maximum value. In - particular, be very careful when using gint8, - guint8, gint16, or guint16 - variables as loop indices; you almost always want to use an - int/gint - or unsigned int/guint - as the loop index rather than a shorter type. - - - - - If you are fetching a length field from the buffer, corresponding to the - length of a portion of the packet, and subtracting from that length a - value corresponding to the length of, for example, a header in the - packet portion in question, ALWAYS - check that the value of the length - field is greater than or equal to the length you’re subtracting from it, - and report an error in the packet and stop dissecting the packet if it’s - less than the length you’re subtracting from it. Otherwise, the - resulting length value will be negative, which will either cause errors - in the dissector or routines called by the dissector, or, if the value - is interpreted as an unsigned integer, will cause the value to be - interpreted as a very large positive value. - - - - - Any tvbuff offset that is added to as processing is done on a packet - should be stored in a 32-bit variable, such as an int; if you store it - in an 8-bit or 16-bit variable, you run the risk of the variable - overflowing. - - - - - Use g_snprintf() instead of sprintf(). - Prevent yourself from using the sprintf() - function, as it does not test the - length of the given output buffer and might be writing into unintended memory - areas. This function is one of the main causes of security problems like buffer - exploits and many other bugs that are very hard to find. It’s much better to - use the g_snprintf() function declared by - <glib.h> instead. - - - - - You should test your dissector against incorrectly-formed packets. - - - This can be done using the randpkt and editcap utilities that come with the - Wireshark distribution. Testing using randpkt can be done by generating - output at the same layer as your protocol, and forcing Wireshark/TShark - to decode it as your protocol, e.g., if your protocol sits on top of UDP: - - -randpkt -c 50000 -t dns randpkt.pcap -tshark -nVr randpkt.pcap -d udp.port==53,<myproto> - - - Testing using editcap can be done using preexisting capture files and the - “-E” flag, which introduces errors in a capture file. E.g., - - -editcap -E 0.03 infile.pcap outfile.pcap -tshark -nVr outfile.pcap - - - The script tools/fuzz-test.sh is available to help - automate these tests. - - - -
-
- Naming convention - - Wireshark uses the underscore_convention rather than the InterCapConvention for - function names, so new code should probably use underscores rather than - intercaps for functions and variable names. This is especially important if you - are writing code that will be called from outside your code. We are just - trying to keep things consistent for other developers. - -
-
- White space convention - - Please avoid using tab expansions different from 8 column widths, as not all - text editors in use by the developers support this. For a detailed - discussion of tabs, spaces, and indentation, - see - - - When creating a new file, you are free to choose an indentation logic. - Most of the files in Wireshark tend to use 2-space or 4-space - indentation. You are encouraged to write a short comment on the - indentation logic at the beginning (or end) of this new file. - The tabs-vs-spaces document above provides - examples of Emacs and vi modelines for this purpose. - - - See Editor Modeline Generator - for a form which can be used to generate modeline blurbs to your taste that - you can copy and paste into the file that you’re editing. - - - When editing an existing file, try following the existing indentation - logic and even if it very tempting, never ever use a restyler/reindenter - utility on an existing file. If you run across wildly varying - indentation styles within the same file, it might be helpful to send a - note to wireshark-dev for guidance. - -
-
- Compiler warnings - - You should write code that is free of compiler warnings. Such warnings will - often indicate questionable code and sometimes even real bugs, so it’s best - to avoid warnings at all. - - - The compiler flags in the Makefiles are set to “treat warnings as errors”, - so your code won’t even compile when warnings occur. - -
-
- -
- The GLib library - - Glib is used as a basic platform abstraction library; it’s not related to - GUI things. - - - To quote the Glib documentation: -
- - - GLib is a general-purpose utility - library, which provides many useful - data types, macros, type conversions, string utilities, file utilities, - a main loop abstraction, and so on. It works on many UNIX-like platforms, - Windows, OS/2 and BeOS. GLib is released under the GNU Library General - Public License (GNU LGPL). - - -
- - - GLib contains lots of useful things for platform independent development. - See - for details about GLib. - -
+ Coding styleguides + + The coding styleguides for Wireshark can be found in the "Code style" + section of the file doc/README.developer. + + + +
+ The GLib library + + Glib is used as a basic platform abstraction library, it's not related to + GUI things. + + + To quote the Glib documentation: GLib is a general-purpose utility + library, which provides many useful + data types, macros, type conversions, string utilities, file utilities, + a main loop abstraction, and so on. It works on many UNIX-like platforms, + Windows, OS/2 and BeOS. GLib is released under the GNU Library General + Public License (GNU LGPL). + + + GLib contains lot's of useful things for platform independent development. + See + for details about GLib. + +
diff --git a/docbook/wsdg_src/WSDG_preface.xml b/docbook/wsdg_src/WSDG_preface.xml index bd68748339..7c8cded6d8 100644 --- a/docbook/wsdg_src/WSDG_preface.xml +++ b/docbook/wsdg_src/WSDG_preface.xml @@ -5,22 +5,22 @@
Foreword - This book tries to give you a guide to start your own experiments into + This book tries to give you a guide to start your own experiments into the wonderful world of Wireshark development. - Developers who are new to Wireshark often have a hard time getting + Developers who are new to Wireshark often have a hard time getting their development environment up and running. This is especially true for Win32 developers, as a lot of the tools and methods used when building Wireshark are much more common in the UNIX world than on Win32. - The first part of this book will describe how to set up the environment + The first part of this book will describe how to set up the environment needed to develop Wireshark. - The second part of this book will describe how to change the Wireshark + The second part of this book will describe how to change the Wireshark source code. @@ -31,18 +31,18 @@
Who should read this document? - The intended audience of this book is anyone going into the development of + The intended audience of this book is anyone going into the development of Wireshark. - This book is not intended to explain the usage of Wireshark in general. - Please refer the - Wireshark User's Guide + This book is not intended to explain the usage of Wireshark in general. + Please refer the + Wireshark User's Guide about Wireshark usage. - By reading this book, you will learn how to develop Wireshark. It will - hopefully guide you around some common problems that frequently appear for + By reading this book, you will learn how to develop Wireshark. It will + hopefully guide you around some common problems that frequently appear for new (and sometimes even advanced) developers of Wireshark.
@@ -50,7 +50,7 @@
Acknowledgements - The authors would like to thank the whole Wireshark team for their + The authors would like to thank the whole Wireshark team for their assistance. In particular, the authors would like to thank: @@ -67,7 +67,7 @@ - The authors would also like to thank the following people for their + The authors would also like to thank the following people for their helpful feedback on this document: @@ -75,7 +75,7 @@ - And of course a big thank you to the many, many contributors of the + And of course a big thank you to the many, many contributors of the Wireshark development community!
@@ -83,61 +83,37 @@
About this document - This book was developed by + This book was developed by Ulf Lamping. It is written in DocBook/XML. - Portions of this book were originally contained in - the file doc/README.developer whose contributors - were listed as: - - - James Coe <jammer[AT]cin.net> - Gilbert Ramirez <gram[AT]alumni.rice.edu> - Jeff Foster <jfoste[AT]woodward.com> - Olivier Abad <oabad[AT]cybercable.fr> - Laurent Deniel <laurent.deniel[AT]free.fr> - Gerald Combs <gerald[AT]wireshark.org> - Guy Harris <guy[AT]alum.mit.edu> - Ulf Lamping <ulf.lamping[AT]web.de> - - - README.developer was converted to DocBook/XML - and integrated into this book by - Bill Meier <wmeier[AT]newsguy.com> - -
- -
- Notation - - You will find some specially marked parts in this book: + You will find some specially marked parts in this book: This is a warning! - - You should pay attention to a warning, as otherwise data loss might occur. - + + You should pay attention to a warning, as otherwise data loss might occur. + This is a note! - - A note will point you to common mistakes and things that might not be - obvious. - + + A note will point you to common mistakes and things that might not be + obvious. + This is a tip! - - Tips will be helpful for your everyday work developing Wireshark. - + + Tips will be helpful for your everyday work developing Wireshark. +
- +
Where to get the latest copy of this document? - The latest copy of this documentation can always be found at: + The latest copy of this documentation can always be found at: &WiresharkDevsGuidePage; in PDF (A4 and US letter), HTML (single and chunked) and CHM format. @@ -146,7 +122,7 @@
Providing feedback about this document - Should you have any feedback about this document, please send it + Should you have any feedback about this document, please send it to the authors through &WiresharkDevMailList;.