@@ -36,37 +36,37 @@ and ask!
36
36
37
37
## How to add new code and to update existing code
38
38
39
- 0 ) Check that there isn't a pull request already opened for the changes you
39
+ 1 ) Check that there isn't a pull request already opened for the changes you
40
40
intend to make.
41
41
42
42
1 ) [ Fork] ( https://help.github.com/articles/fork-a-repo/ ) the Tcpdump
43
43
[ repository] ( https://github.com/the-tcpdump-group/tcpdump ) .
44
44
45
- 2 ) The easiest way to test your changes on multiple operating systems and
45
+ 1 ) The easiest way to test your changes on multiple operating systems and
46
46
architectures is to let the upstream CI test your pull request (more on
47
47
this below).
48
48
49
- 3 ) Setup your git working copy
49
+ 1 ) Setup your git working copy
50
50
```
51
51
git clone https://github.com/<username>/tcpdump.git
52
52
cd tcpdump
53
53
git remote add upstream https://github.com/the-tcpdump-group/tcpdump
54
54
git fetch upstream
55
55
```
56
56
57
- 4 ) Do a ` touch .devel ` in your working directory.
57
+ 1 ) Do a ` touch .devel ` in your working directory.
58
58
Currently, the effect is
59
59
* add (via ` configure ` , in ` Makefile ` ) some warnings options (` -Wall ` ,
60
60
` -Wmissing-prototypes ` , ` -Wstrict-prototypes ` , ...) to the compiler if it
61
61
supports these options,
62
62
* have the ` Makefile ` support ` make depend ` and the ` configure ` script run it.
63
63
64
- 5 ) Configure and build
64
+ 1 ) Configure and build
65
65
```
66
66
./configure && make -s && make check
67
67
```
68
68
69
- 6 ) Add/update tests
69
+ 1 ) Add/update tests
70
70
The ` tests ` directory contains regression tests of the dissection of captured
71
71
packets. Those captured packets were saved running tcpdump with option
72
72
` -w sample.pcap ` . Additional options, such as ` -n ` , are used to create relevant
@@ -96,73 +96,73 @@ and ask!
96
96
It is often useful to have test outputs with different verbosity levels
97
97
(none, ` -v ` , ` -vv ` , ` -vvv ` , etc.) depending on the code.
98
98
99
- 7 ) Test using ` make check ` (current build options) and ` ./build_matrix.sh `
99
+ 1 ) Test using ` make check ` (current build options) and ` ./build_matrix.sh `
100
100
(a multitude of build options, build systems and compilers). If you can,
101
101
test on more than one operating system. Don't send a pull request until
102
102
all tests pass.
103
103
104
- 8 ) Try to rebase your commits to keep the history simple.
104
+ 1 ) Try to rebase your commits to keep the history simple.
105
105
```
106
106
git fetch upstream
107
107
git rebase upstream/master
108
108
```
109
109
(If the rebase fails and you cannot resolve, issue ` git rebase --abort `
110
110
and ask for help in the pull request comment.)
111
111
112
- 9 ) Once 100% happy, put your work into your forked repository using ` git push ` .
112
+ 1 ) Once 100% happy, put your work into your forked repository using ` git push ` .
113
113
114
- 10 ) [ Initiate and send] ( https://help.github.com/articles/using-pull-requests/ )
114
+ 1 ) [ Initiate and send] ( https://help.github.com/articles/using-pull-requests/ )
115
115
a pull request.
116
116
This will trigger the upstream repository CI tests.
117
117
118
118
119
119
## Code style and generic remarks
120
- * A thorough reading of some other printers code is useful.
121
-
122
- * To help learn how tcpdump works or to help debugging:
123
- You can configure and build tcpdump with the instrumentation of functions:
124
- ```
125
- $ ./configure --enable-instrument-functions
126
- $ make -s clean all
127
- ```
128
-
129
- This generates instrumentation calls for entry and exit to functions.
130
- Just after function entry and just before function exit, these
131
- profiling functions are called and print the function names with
132
- indentation and call level.
133
-
134
- If entering in a function, it prints also the calling function name with
135
- file name and line number. There may be a small shift in the line number.
136
-
137
- In some cases, with Clang 11, the file number is unknown (printed '??')
138
- or the line number is unknown (printed '?'). In this case, use GCC.
139
-
140
- If the environment variable INSTRUMENT is
141
- - unset or set to an empty string, print nothing, like with no
142
- instrumentation
143
- - set to "all" or "a", print all the functions names
144
- - set to "global" or "g", print only the global functions names
145
-
146
- This allows to run:
147
- ```
148
- $ INSTRUMENT=a ./tcpdump ...
149
- $ INSTRUMENT=g ./tcpdump ...
150
- $ INSTRUMENT= ./tcpdump ...
151
- ```
152
- or
153
- ```
154
- $ export INSTRUMENT=global
155
- $ ./tcpdump ...
156
- ```
157
-
158
- The library libbfd is used, therefore the binutils-dev package is required.
159
-
160
- * Put the normative reference if any as comments (RFC, etc.).
161
-
162
- * Put the format of packets/headers/options as comments if there is no
120
+ 1 ) A thorough reading of some other printers code is useful.
121
+
122
+ 1 ) To help learn how tcpdump works or to help debugging:
123
+ You can configure and build tcpdump with the instrumentation of functions:
124
+ ```
125
+ $ ./configure --enable-instrument-functions
126
+ $ make -s clean all
127
+ ```
128
+
129
+ This generates instrumentation calls for entry and exit to functions.
130
+ Just after function entry and just before function exit, these
131
+ profiling functions are called and print the function names with
132
+ indentation and call level.
133
+
134
+ If entering in a function, it prints also the calling function name with
135
+ file name and line number. There may be a small shift in the line number.
136
+
137
+ In some cases, with Clang 11, the file number is unknown (printed '??')
138
+ or the line number is unknown (printed '?'). In this case, use GCC.
139
+
140
+ If the environment variable INSTRUMENT is
141
+ - unset or set to an empty string, print nothing, like with no
142
+ instrumentation
143
+ - set to "all" or "a", print all the functions names
144
+ - set to "global" or "g", print only the global functions names
145
+
146
+ This allows to run:
147
+ ```
148
+ $ INSTRUMENT=a ./tcpdump ...
149
+ $ INSTRUMENT=g ./tcpdump ...
150
+ $ INSTRUMENT= ./tcpdump ...
151
+ ```
152
+ or
153
+ ```
154
+ $ export INSTRUMENT=global
155
+ $ ./tcpdump ...
156
+ ```
157
+
158
+ The library libbfd is used, therefore the binutils-dev package is required.
159
+
160
+ 1 ) Put the normative reference if any as comments (RFC, etc.).
161
+
162
+ 1 ) Put the format of packets/headers/options as comments if there is no
163
163
published normative reference.
164
164
165
- * The printer may receive incomplete packet in the buffer, truncated at any
165
+ 1 ) The printer may receive incomplete packet in the buffer, truncated at any
166
166
random position, for example by capturing with ` -s size ` option.
167
167
This means that an attempt to fetch packet data based on the expected
168
168
format of the packet may run the risk of overrunning the buffer.
@@ -319,11 +319,11 @@ and ask!
319
319
DLCI, if the address is a valid Q.922 header, and an error indication
320
320
otherwise;
321
321
322
- * ` LINKADDR_EUI64 ` , ` LINKADDR_ATM ` , ` LINKADDR_OTHER ` -
322
+ * ` LINKADDR_EUI64 ` , ` LINKADDR_ATM ` , ` LINKADDR_OTHER ` -
323
323
the string is a sequence of XX:XX:... values for the bytes
324
324
of the address.
325
325
326
- * When defining a structure corresponding to a packet or part of a
326
+ 6 ) When defining a structure corresponding to a packet or part of a
327
327
packet, so that a pointer to packet data can be cast to a pointer to
328
328
that structure and that structure pointer used to refer to fields in
329
329
the packet, use the ` nd_* ` types for the structure members.
@@ -356,20 +356,20 @@ and ask!
356
356
The ` nd_* ` type for a byte in a sequence of bytes is ` nd_byte ` ; an
357
357
* N* -byte sequence should be declared as ` nd_byte[N] ` .
358
358
359
- * Do invalid packet checks in code: Think that your code can receive in input
359
+ 1 ) Do invalid packet checks in code: Think that your code can receive in input
360
360
not only a valid packet but any arbitrary random sequence of octets (packet
361
361
* built malformed originally by the sender or by a fuzz tester,
362
362
* became corrupted in transit or for some other reason).
363
363
364
364
Print with: ` nd_print_invalid(ndo); /* to print " (invalid)" */ `
365
365
366
- * Use ` struct tok ` for indexed strings and print them with
366
+ 1 ) Use ` struct tok ` for indexed strings and print them with
367
367
` tok2str() ` or ` bittok2str() ` (for flags).
368
368
All ` struct tok ` must end with ` { 0, NULL } ` .
369
369
370
- * Avoid empty lines in output of printers.
370
+ 1 ) Avoid empty lines in output of printers.
371
371
372
- * A commit message must have:
372
+ 1 ) A commit message must have:
373
373
```
374
374
First line: Capitalized short summary in the imperative (50 chars or less)
375
375
@@ -381,14 +381,14 @@ and ask!
381
381
the body.
382
382
```
383
383
384
- * Avoid non-ASCII characters in code and commit messages.
384
+ 1 ) Avoid non-ASCII characters in code and commit messages.
385
385
386
- * Use the style of the modified sources.
386
+ 1 ) Use the style of the modified sources.
387
387
388
- * Don't mix declarations and code.
388
+ 1 ) Don't mix declarations and code.
389
389
390
- * tcpdump requires a compiler that supports C99 or later, so C99
390
+ 1 ) tcpdump requires a compiler that supports C99 or later, so C99
391
391
features may be used in code, but C11 or later features should not be
392
392
used.
393
393
394
- * Avoid trailing tabs/spaces
394
+ 1 ) Avoid trailing tabs/spaces
0 commit comments