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]` whitelists that file and excludes 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 21checksrc does not check and verify the code against the entire style guide, 22but the script is instead an effort to detect the most common mistakes and 23syntax mistakes that contributors make before they get accustomed to our code 24style. Heck, many of us regulars do the mistakes too and this script helps us 25keep the code in 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- `BADCOMMAND`: There's a bad !checksrc! instruction in the code. See the 34 **Ignore certain warnings** section below for details. 35 36- `BANNEDFUNC`: A banned function was used. The functions sprintf, vsprintf, 37 strcat, strncat, gets are **never** allowed in curl source code. 38 39- `BRACEELSE`: '} else' on the same line. The else is supposed to be on the 40 following line. 41 42- `BRACEPOS`: wrong position for an open brace (`{`). 43 44- `COMMANOSPACE`: a comma without following space 45 46- `COPYRIGHT`: the file is missing a copyright statement! 47 48- `CPPCOMMENTS`: `//` comment detected, that's not C89 compliant 49 50- `FOPENMODE`: `fopen()` needs a macro for the mode string, use it 51 52- `INDENTATION`: detected a wrong start column for code. Note that this warning 53 only checks some specific places and will certainly miss many bad 54 indentations. 55 56- `LONGLINE`: A line is longer than 79 columns. 57 58- `PARENBRACE`: `){` was used without sufficient space in between. 59 60- `RETURNNOSPACE`: `return` was used without space between the keyword and the 61 following value. 62 63- `SPACEAFTERPAREN`: there was a space after open parenthesis, `( text`. 64 65- `SPACEBEFORECLOSE`: there was a space before a close parenthesis, `text )`. 66 67- `SPACEBEFORECOMMA`: there was a space before a comma, `one , two`. 68 69- `SPACEBEFOREPAREN`: there was a space before an open parenthesis, `if (`, 70 where one was not expected 71 72- `SPACESEMILCOLON`: there was a space before semicolon, ` ;`. 73 74- `TABS`: TAB characters are not allowed! 75 76- `TRAILINGSPACE`: Trailing white space on the line 77 78- `UNUSEDIGNORE`: a checksrc inlined warning ignore was asked for but not used, 79 that's an ignore that should be removed or changed to get used. 80 81## Ignore certain warnings 82 83Due to the nature of the source code and the flaws of the checksrc tool, there 84is sometimes a need to ignore specific warnings. checksrc allows a few 85different ways to do this. 86 87### Inline ignore 88 89You can control what to ignore within a specific source file by providing 90instructions to checksrc in the source code itself. You need a magic marker 91that is `!checksrc!` followed by the instruction. The instruction can ask to 92ignore a specific warning N number of times or you ignore all of them until 93you mark the end of the ignored section. 94 95Inline ignores are only done for that single specific source code file. 96 97Example 98 99 /* !checksrc! disable LONGLINE all */ 100 101This will ignore the warning for overly long lines until it is re-enabled with: 102 103 /* !checksrc! enable LONGLINE */ 104 105If the enabling isn't performed before the end of the file, it will be enabled 106automatically for the next file. 107 108You can also opt to ignore just N violations so that if you have a single long 109line you just can't shorten and is agreed to be fine anyway: 110 111 /* !checksrc! disable LONGLINE 1 */ 112 113... and the warning for long lines will be enabled again automatically after 114it has ignored that single warning. The number `1` can of course be changed to 115any other integer number. It can be used to make sure only the exact intended 116instances are ignored and nothing extra. 117 118### Directory wide ignore patterns 119 120This is a method we've transitioned away from. Use inline ignores as far as 121possible. 122 123Make a `checksrc.whitelist` file in the directory of the source code with the 124false positive, and include the full offending line into this file. 125