1# checksrc 2 3This is the tool we use within the curl project to scan C source code and 4check that it adheres to our [Source Code Style guide](CODE_STYLE.md). 5 6## Usage 7 8 checksrc.pl [options] [file1] [file2] ... 9 10## Command line options 11 12`-W[file]` skip that file and exclude it from being checked. Helpful 13when, for example, one of the files is generated. 14 15`-D[dir]` directory name to prepend to file names when accessing them. 16 17`-h` shows the help output, that also lists all recognized warnings 18 19## What does `checksrc` warn for? 20 21`checksrc` does not check and verify the code against the entire style guide. 22The script is an effort to detect the most common mistakes and syntax mistakes 23that contributors make before they get accustomed to our code style. Heck, 24many of us regulars do the mistakes too and this script helps us keep the code 25in shape. 26 27 checksrc.pl -h 28 29Lists how to use the script and it lists all existing warnings it has and 30problems it detects. At the time of this writing, the existing `checksrc` 31warnings are: 32 33- `ASSIGNWITHINCONDITION`: Assignment within a conditional expression. The 34 code style mandates the assignment to be done outside of it. 35 36- `ASTERISKNOSPACE`: A pointer was declared like `char* name` instead of the 37 more appropriate `char *name` style. The asterisk should sit next to the 38 name. 39 40- `ASTERISKSPACE`: A pointer was declared like `char * name` instead of the 41 more appropriate `char *name` style. The asterisk should sit right next to 42 the name without a space in between. 43 44- `BADCOMMAND`: There is a bad `checksrc` instruction in the code. See the 45 **Ignore certain warnings** section below for details. 46 47- `BANNEDFUNC`: A banned function was used. The functions sprintf, vsprintf, 48 strcat, strncat, gets are **never** allowed in curl source code. 49 50- `BRACEELSE`: '} else' on the same line. The else is supposed to be on the 51 following line. 52 53- `BRACEPOS`: wrong position for an open brace (`{`). 54 55- `BRACEWHILE`: more than once space between end brace and while keyword 56 57- `COMMANOSPACE`: a comma without following space 58 59- `COPYRIGHT`: the file is missing a copyright statement 60 61- `CPPCOMMENTS`: `//` comment detected, that is not C89 compliant 62 63- `DOBRACE`: only use one space after do before open brace 64 65- `EMPTYLINEBRACE`: found empty line before open brace 66 67- `EQUALSNOSPACE`: no space after `=` sign 68 69- `EQUALSNULL`: comparison with `== NULL` used in if/while. We use `!var`. 70 71- `EXCLAMATIONSPACE`: space found after exclamations mark 72 73- `FOPENMODE`: `fopen()` needs a macro for the mode string, use it 74 75- `INDENTATION`: detected a wrong start column for code. Note that this 76 warning only checks some specific places and will certainly miss many bad 77 indentations. 78 79- `LONGLINE`: A line is longer than 79 columns. 80 81- `MULTISPACE`: Multiple spaces were found where only one should be used. 82 83- `NOSPACEEQUALS`: An equals sign was found without preceding space. We prefer 84 `a = 2` and *not* `a=2`. 85 86- `NOTEQUALSZERO`: check found using `!= 0`. We use plain `if(var)`. 87 88- `ONELINECONDITION`: do not put the conditional block on the same line as `if()` 89 90- `OPENCOMMENT`: File ended with a comment (`/*`) still "open". 91 92- `PARENBRACE`: `){` was used without sufficient space in between. 93 94- `RETURNNOSPACE`: `return` was used without space between the keyword and the 95 following value. 96 97- `SEMINOSPACE`: There was no space (or newline) following a semicolon. 98 99- `SIZEOFNOPAREN`: Found use of sizeof without parentheses. We prefer 100 `sizeof(int)` style. 101 102- `SNPRINTF` - Found use of `snprintf()`. Since we use an internal replacement 103 with a different return code etc, we prefer `msnprintf()`. 104 105- `SPACEAFTERPAREN`: there was a space after open parenthesis, `( text`. 106 107- `SPACEBEFORECLOSE`: there was a space before a close parenthesis, `text )`. 108 109- `SPACEBEFORECOMMA`: there was a space before a comma, `one , two`. 110 111- `SPACEBEFOREPAREN`: there was a space before an open parenthesis, `if (`, 112 where one was not expected 113 114- `SPACESEMICOLON`: there was a space before semicolon, ` ;`. 115 116- `TABS`: TAB characters are not allowed 117 118- `TRAILINGSPACE`: Trailing whitespace on the line 119 120- `TYPEDEFSTRUCT`: we frown upon (most) typedefed structs 121 122- `UNUSEDIGNORE`: a `checksrc` inlined warning ignore was asked for but not 123 used, that is an ignore that should be removed or changed to get used. 124 125### Extended warnings 126 127Some warnings are quite computationally expensive to perform, so they are 128turned off by default. To enable these warnings, place a `.checksrc` file in 129the directory where they should be activated with commands to enable the 130warnings you are interested in. The format of the file is to enable one 131warning per line like so: `enable <EXTENDEDWARNING>` 132 133Currently these are the extended warnings which can be enabled: 134 135- `COPYRIGHTYEAR`: the current changeset has not updated the copyright year in 136 the source file 137 138- `STRERROR`: use of banned function strerror() 139 140- `STDERR`: use of banned variable `stderr` 141 142## Ignore certain warnings 143 144Due to the nature of the source code and the flaws of the `checksrc` tool, 145there is sometimes a need to ignore specific warnings. `checksrc` allows a few 146different ways to do this. 147 148### Inline ignore 149 150You can control what to ignore within a specific source file by providing 151instructions to `checksrc` in the source code itself. See examples below. The 152instruction can ask to ignore a specific warning a specific number of times or 153you ignore all of them until you mark the end of the ignored section. 154 155Inline ignores are only done for that single specific source code file. 156 157Example 158 159 /* !checksrc! disable LONGLINE all */ 160 161This will ignore the warning for overly long lines until it is re-enabled with: 162 163 /* !checksrc! enable LONGLINE */ 164 165If the enabling is not performed before the end of the file, it will be enabled 166automatically for the next file. 167 168You can also opt to ignore just N violations so that if you have a single long 169line you just cannot shorten and is agreed to be fine anyway: 170 171 /* !checksrc! disable LONGLINE 1 */ 172 173... and the warning for long lines will be enabled again automatically after 174it has ignored that single warning. The number `1` can of course be changed to 175any other integer number. It can be used to make sure only the exact intended 176instances are ignored and nothing extra. 177 178### Directory wide ignore patterns 179 180This is a method we have transitioned away from. Use inline ignores as far as 181possible. 182 183Make a `checksrc.skip` file in the directory of the source code with the 184false positive, and include the full offending line into this file. 185