Artifactspublic-v0

curl

master
ply4 git calls29 ms290 KiB3 cachedprotocol v2
195 lines6.8 KiBRaw

checksrc

This is the tool we use within the curl project to scan C source code and check that it adheres to our Source Code Style guide.

Usage

checksrc.pl [options] [file1] [file2] ...

Command line options

-W[file] skip that file and exclude it from being checked. Helpful when, for example, one of the files is generated.

-D[dir] directory name to prepend to filenames when accessing them.

-h shows the help output, that also lists all recognized warnings

What does checksrc warn for?

checksrc does not check and verify the code against the entire style guide. The script is an effort to detect the most common mistakes and syntax mistakes that contributors make before they get accustomed to our code style. Heck, many of us regulars do the mistakes too and this script helps us keep the code in shape.

checksrc.pl -h

Lists how to use the script and it lists all existing warnings it has and problems it detects. At the time of this writing, the existing checksrc warnings are:

  • ASSIGNWITHINCONDITION: Assignment within a conditional expression. The code style mandates the assignment to be done outside of it.

  • ASTERISKNOSPACE: A pointer was declared like char* name instead of the more appropriate char *name style. The asterisk should sit next to the name.

  • ASTERISKSPACE: A pointer was declared like char * name instead of the more appropriate char *name style. The asterisk should sit right next to the name without a space in between.

  • BADCOMMAND: There is a bad checksrc instruction in the code. See the Ignore certain warnings section below for details.

  • BANNEDFUNC: A banned function was used. The functions sprintf, vsprintf, strcat, strncat, gets are never allowed in curl source code.

  • BRACEELSE: '} else' on the same line. The else is supposed to be on the following line.

  • BRACEPOS: wrong position for an open brace ({).

  • BRACEWHILE: more than once space between end brace and while keyword

  • COMMANOSPACE: a comma without following space

  • COPYRIGHT: the file is missing a copyright statement

  • CPPCOMMENTS: // comment detected, that is not C89 compliant

  • DOBRACE: only use one space after do before open brace

  • EMPTYLINEBRACE: found empty line before open brace

  • EQUALSNOSPACE: no space after = sign

  • EQUALSNULL: comparison with == NULL used in if/while. We use !var.

  • EXCLAMATIONSPACE: space found after exclamations mark

  • FOPENMODE: curlx_fopen(), curlx_freopen() need a macro for the mode string, use it

  • INDENTATION: detected a wrong start column for code. Note that this warning only checks some specific places and can certainly miss many bad indentations.

  • LONGLINE: A line is longer than 79 columns.

  • MULTISPACE: Multiple spaces were found where only one should be used.

  • NOSPACEEQUALS: An equals sign was found without preceding space. We prefer a = 2 and not a=2.

  • NOTEQUALSZERO: check found using != 0. We use plain if(var).

  • ONELINECONDITION: do not put the conditional block on the same line as if()

  • OPENCOMMENT: File ended with a comment (/*) still "open".

  • PARENBRACE: ){ was used without sufficient space in between.

  • RETURNNOSPACE: return was used without space between the keyword and the following value.

  • SEMINOSPACE: There was no space (or newline) following a semicolon.

  • SIZEOFNOPAREN: Found use of sizeof without parentheses. We prefer sizeof(int) style.

  • SNPRINTF - Found use of snprintf(). Since we use an internal replacement with a different return code etc, we prefer curl_msnprintf().

  • SPACEAFTERPAREN: there was a space after open parenthesis, ( text.

  • SPACEBEFORECLOSE: there was a space before a close parenthesis, text ).

  • SPACEBEFORECOMMA: there was a space before a comma, one , two.

  • SPACEBEFOREPAREN: there was a space before an open parenthesis, if (, where one was not expected

  • SPACESEMICOLON: there was a space before semicolon, ;.

  • TABS: TAB characters are not allowed

  • TRAILINGSPACE: Trailing whitespace on the line

  • TYPEDEFSTRUCT: we frown upon (most) typedefed structs

  • UNUSEDIGNORE: a checksrc inlined warning ignore was asked for but not used, that is an ignore that should be removed or changed to get used.

  • USESAFEFREE: there was a curlx_free(var) call made right before assigning NULL to var. We prefer replacing that with curlx_safefree(), which is doing these two operations in a single call.

Extended warnings

Some warnings are computationally expensive to perform, so they are turned off by default. To enable these warnings, place a .checksrc file in the directory where they should be activated with commands to enable the warnings you are interested in. The format of the file is to enable one warning per line like so: enable <EXTENDEDWARNING>

Currently these are the extended warnings which can be enabled:

  • COPYRIGHTYEAR: the current changeset has not updated the copyright year in the source file

  • PRINTFZ: use of banned printf masks %zd, %zu or %zx

  • STDERR: use of banned variable stderr

Ignore certain warnings

Due to the nature of the source code and the flaws of the checksrc tool, there is sometimes a need to ignore specific warnings. checksrc allows a few different ways to do this.

Inline ignore

You can control what to ignore within a specific source file by providing instructions to checksrc in the source code itself. See examples below. The instruction can ask to ignore a specific warning a specific number of times or you ignore all of them until you mark the end of the ignored section.

Inline ignores are only done for that single specific source code file.

Example

/* !checksrc! disable LONGLINE all */

This ignores the warning for overly long lines until it is re-enabled with:

/* !checksrc! enable LONGLINE */

If the enabling is not performed before the end of the file, it is enabled again automatically for the next file.

You can also opt to ignore N violations so that if you have a single long line you cannot shorten and is agreed to be fine anyway:

/* !checksrc! disable LONGLINE 1 */

... and the warning for long lines is enabled again automatically after it has ignored that single warning. The number 1 can of course be changed to any other integer number. It can be used to make sure only the exact intended instances are ignored and nothing extra.

Directory wide ignore patterns

This is a method we have transitioned away from. Use inline ignores as far as possible.

Make a checksrc.skip file in the directory of the source code with the false positive, and include the full offending line into this file.

1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
4SPDX-License-Identifier: curl
5-->
7# checksrc
9This is the tool we use within the curl project to scan C source code and
10check that it adheres to our [Source Code Style guide](CODE_STYLE.md).
12## Usage
14 checksrc.pl [options] [file1] [file2] ...
16## Command line options
18`-W[file]` skip that file and exclude it from being checked. Helpful
19when, for example, one of the files is generated.
21`-D[dir]` directory name to prepend to filenames when accessing them.
23`-h` shows the help output, that also lists all recognized warnings
25## What does `checksrc` warn for?
27`checksrc` does not check and verify the code against the entire style guide.
28The script is an effort to detect the most common mistakes and syntax mistakes
29that contributors make before they get accustomed to our code style. Heck,
30many of us regulars do the mistakes too and this script helps us keep the code
31in shape.
33 checksrc.pl -h
35Lists how to use the script and it lists all existing warnings it has and
36problems it detects. At the time of this writing, the existing `checksrc`
37warnings are:
39- `ASSIGNWITHINCONDITION`: Assignment within a conditional expression. The
40 code style mandates the assignment to be done outside of it.
42- `ASTERISKNOSPACE`: A pointer was declared like `char* name` instead of the
43 more appropriate `char *name` style. The asterisk should sit next to the
44 name.
46- `ASTERISKSPACE`: A pointer was declared like `char * name` instead of the
47 more appropriate `char *name` style. The asterisk should sit right next to
48 the name without a space in between.
50- `BADCOMMAND`: There is a bad `checksrc` instruction in the code. See the
51 **Ignore certain warnings** section below for details.
53- `BANNEDFUNC`: A banned function was used. The functions sprintf, vsprintf,
54 strcat, strncat, gets are **never** allowed in curl source code.
56- `BRACEELSE`: '} else' on the same line. The else is supposed to be on the
57 following line.
59- `BRACEPOS`: wrong position for an open brace (`{`).
61- `BRACEWHILE`: more than once space between end brace and while keyword
63- `COMMANOSPACE`: a comma without following space
65- `COPYRIGHT`: the file is missing a copyright statement
67- `CPPCOMMENTS`: `//` comment detected, that is not C89 compliant
69- `DOBRACE`: only use one space after do before open brace
71- `EMPTYLINEBRACE`: found empty line before open brace
73- `EQUALSNOSPACE`: no space after `=` sign
75- `EQUALSNULL`: comparison with `== NULL` used in if/while. We use `!var`.
77- `EXCLAMATIONSPACE`: space found after exclamations mark
79- `FOPENMODE`: `curlx_fopen()`, `curlx_freopen()` need a macro for the mode
80 string, use it
82- `INDENTATION`: detected a wrong start column for code. Note that this
83 warning only checks some specific places and can certainly miss many bad
84 indentations.
86- `LONGLINE`: A line is longer than 79 columns.
88- `MULTISPACE`: Multiple spaces were found where only one should be used.
90- `NOSPACEEQUALS`: An equals sign was found without preceding space. We prefer
91 `a = 2` and *not* `a=2`.
93- `NOTEQUALSZERO`: check found using `!= 0`. We use plain `if(var)`.
95- `ONELINECONDITION`: do not put the conditional block on the same line as `if()`
97- `OPENCOMMENT`: File ended with a comment (`/*`) still "open".
99- `PARENBRACE`: `){` was used without sufficient space in between.
101- `RETURNNOSPACE`: `return` was used without space between the keyword and the
102 following value.
104- `SEMINOSPACE`: There was no space (or newline) following a semicolon.
106- `SIZEOFNOPAREN`: Found use of sizeof without parentheses. We prefer
107 `sizeof(int)` style.
109- `SNPRINTF` - Found use of `snprintf()`. Since we use an internal replacement
110 with a different return code etc, we prefer `curl_msnprintf()`.
112- `SPACEAFTERPAREN`: there was a space after open parenthesis, `( text`.
114- `SPACEBEFORECLOSE`: there was a space before a close parenthesis, `text )`.
116- `SPACEBEFORECOMMA`: there was a space before a comma, `one , two`.
118- `SPACEBEFOREPAREN`: there was a space before an open parenthesis, `if (`,
119 where one was not expected
121- `SPACESEMICOLON`: there was a space before semicolon, ` ;`.
123- `TABS`: TAB characters are not allowed
125- `TRAILINGSPACE`: Trailing whitespace on the line
127- `TYPEDEFSTRUCT`: we frown upon (most) typedefed structs
129- `UNUSEDIGNORE`: a `checksrc` inlined warning ignore was asked for but not
130 used, that is an ignore that should be removed or changed to get used.
132- `USESAFEFREE`: there was a `curlx_free(var)` call made right before assigning
133 NULL to `var`. We prefer replacing that with `curlx_safefree()`, which is
134 doing these two operations in a single call.
136### Extended warnings
138Some warnings are computationally expensive to perform, so they are turned off
139by default. To enable these warnings, place a `.checksrc` file in the directory
140where they should be activated with commands to enable the warnings you are
141interested in. The format of the file is to enable one warning per line like
142so: `enable <EXTENDEDWARNING>`
144Currently these are the extended warnings which can be enabled:
146- `COPYRIGHTYEAR`: the current changeset has not updated the copyright year in
147 the source file
149- `PRINTFZ`: use of banned printf masks `%zd`, `%zu` or `%zx`
151- `STDERR`: use of banned variable `stderr`
153## Ignore certain warnings
155Due to the nature of the source code and the flaws of the `checksrc` tool,
156there is sometimes a need to ignore specific warnings. `checksrc` allows a few
157different ways to do this.
159### Inline ignore
161You can control what to ignore within a specific source file by providing
162instructions to `checksrc` in the source code itself. See examples below. The
163instruction can ask to ignore a specific warning a specific number of times or
164you ignore all of them until you mark the end of the ignored section.
166Inline ignores are only done for that single specific source code file.
168Example
170 /* !checksrc! disable LONGLINE all */
172This ignores the warning for overly long lines until it is re-enabled with:
174 /* !checksrc! enable LONGLINE */
176If the enabling is not performed before the end of the file, it is enabled
177again automatically for the next file.
179You can also opt to ignore N violations so that if you have a single long line
180you cannot shorten and is agreed to be fine anyway:
182 /* !checksrc! disable LONGLINE 1 */
184... and the warning for long lines is enabled again automatically after it has
185ignored that single warning. The number `1` can of course be changed to any
186other integer number. It can be used to make sure only the exact intended
187instances are ignored and nothing extra.
189### Directory wide ignore patterns
191This is a method we have transitioned away from. Use inline ignores as far as
192possible.
194Make a `checksrc.skip` file in the directory of the source code with the
195false positive, and include the full offending line into this file.
Diagnostics4 git calls · 29 ms
CallStatusSizeTime029 ms
discover200152 B7 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=7
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit7 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=7
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=7
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2003.2 KiB · hit19 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=19
git.response.bytes=3242
git.response.cache=HIT
git.response.duration_ms=19
git.fetch.wants=2f3a4bda45546fc284be88637eeaee662b648090
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=3242
git.pkt.payload.max=3221
git.sideband.band1.bytes=3220
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e2d1b95dd3cf3a
Request
2d1cad9d…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format