Archive-Team
/
zfs
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 103 Wiki Activity

cstyle.1: modernise 

Also remove note about the OS/Net consolidation, now the illumos gate

Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Closes #12125
This commit is contained in:
наб 2021-05-26 17:50:17 +02:00 committed by Brian Behlendorf
parent f6ce806298
commit 475ee3bc2b
1 changed files with 126 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
man/man1/cstyle.1
View File

@ -20,148 +20,142 @@
.\" .\"
.\" CDDL HEADER END .\" CDDL HEADER END
.\" .\"
.TH CSTYLE 1 "Aug 24, 2020" OpenZFS .Dd May 26, 2021
.SH NAME .Dt CSTYLE 1
.I cstyle .Os
\- check for some common stylistic errors in C source files .
.SH SYNOPSIS .Sh NAME
\fBcstyle [-chpvCP] [-o constructs] [file...]\fP .Nm cstyle
.LP .Nd check for some common stylistic errors in C source files
.SH DESCRIPTION .Sh SYNOPSIS
.IX "OS-Net build tools" "cstyle" "" "\fBcstyle\fP" .Nm
.LP .Op Fl chpvCP
.I cstyle .Op Fl o Ar construct Ns Op , Ns Ar construct Ns …
inspects C source files (*.c and *.h) for common stylistic errors. It .Op Ar file…
attempts to check for the cstyle documented in .Sh DESCRIPTION
\fIhttp://www.cis.upenn.edu/~lee/06cse480/data/cstyle.ms.pdf\fP. .Nm
inspects C source files (*.c and *.h) for common stylistic errors.
It attempts to check for the cstyle documented in
.Lk http://www.cis.upenn.edu/~lee/06cse480/data/cstyle.ms.pdf .
Note that there is much in that document that Note that there is much in that document that
.I cannot .Em cannot
be checked for; just because your code is \fBcstyle(1)\fP clean does not be checked for; just because your code is
mean that you've followed Sun's C style. \fICaveat emptor\fP. .Nm Ns -clean
.LP does not mean that you've followed Sun's C style.
.SH OPTIONS .Em Caveat emptor .
.LP .
.Sh OPTIONS
The following options are supported: The following options are supported:
.TP 4 .Bl -tag -width "-c"
.B \-c .It Fl c
Check continuation line indentation inside of functions. Sun's C style Check continuation line indentation inside of functions.
Sun's C style
states that all statements must be indented to an appropriate tab stop, states that all statements must be indented to an appropriate tab stop,
and any continuation lines after them must be indented \fIexactly\fP four and any continuation lines after them must be indented
spaces from the start line. This option enables a series of checks .Em exactly
designed to find continuation line problems within functions only. The four spaces from the start line.
checks have some limitations; see CONTINUATION CHECKING, below. This option enables a series of checks designed to find
.LP continuation line problems within functions only.
.TP 4 The checks have some limitations; see
.B \-h .Sy CONTINUATION CHECKING ,
Performs heuristic checks that are sometimes wrong. Not generally used. below.
.LP .It Fl h
.TP 4 Performs heuristic checks that are sometimes wrong.
.B \-p Not generally used.
Performs some of the more picky checks. Includes ANSI #else and #endif .It Fl p
rules, and tries to detect spaces after casts. Used as part of the Performs some of the more picky checks.
putback checks. Includes ANSI
.LP .Sy #else
.TP 4 and
.B \-v .Sy #endif
rules, and tries to detect spaces after casts.
Used as part of the putback checks.
.It Fl v
Verbose output; includes the text of the line of error, and, for Verbose output; includes the text of the line of error, and, for
\fB-c\fP, the first statement in the current continuation block. .Fl c ,
.LP the first statement in the current continuation block.
.TP 4 .It Fl C
.B \-C
Ignore errors in header comments (i.e. block comments starting in the Ignore errors in header comments (i.e. block comments starting in the
first column). Not generally used. first column).
.LP Not generally used.
.TP 4 .It Fl P
.B \-P Check for use of non-POSIX types.
Check for use of non-POSIX types. Historically, types like "u_int" and Historically, types like
"u_long" were used, but they are now deprecated in favor of the POSIX .Sy u_int
types uint_t, ulong_t, etc. This detects any use of the deprecated and
types. Used as part of the putback checks. .Sy u_long
.LP were used, but they are now deprecated in favor of the POSIX
.TP 4 types
.B \-o \fIconstructs\fP .Sy uint_t ,
Allow a comma-separated list of additional constructs. Available .Sy ulong_t ,
constructs include: etc.
.LP This detects any use of the deprecated types.
.TP 10 Used as part of the putback checks.
.B doxygen .It Fl o Ar construct Ns Op , Ns Ar construct Ns …
Allow doxygen-style block comments (\fB/**\fP and \fB/*!\fP) Available constructs include:
.LP .Bl -tag -compact -width "doxygen"
.TP 10 .It Sy doxygen
.B splint Allow doxygen-style block comments
Allow splint-style lint comments (\fB/*@...@*/\fP) .Pq Sy /** No and Sy /*!\& .
.LP .It Sy splint
.SH NOTES Allow splint-style lint comments
.LP .Pq Sy /*@...@*/ .
The cstyle rule for the OS/Net consolidation is that all new files must .El
be \fB-pP\fP clean. For existing files, the following invocations are .El
run against both the old and new files: .
.LP .Sh CONTINUATION CHECKING
.TP 4
\fBcstyle file\fB
.LP
.TP 4
\fBcstyle -p file\fB
.LP
.TP 4
\fBcstyle -pP file\fB
.LP
If the old file gave no errors for one of the invocations, the new file
must also give no errors. This way, files can only become more clean.
.LP
.SH CONTINUATION CHECKING
.LP
The continuation checker is a reasonably simple state machine that knows The continuation checker is a reasonably simple state machine that knows
something about how C is laid out, and can match parenthesis, etc. over something about how C is laid out, and can match parenthesis, etc. over
multiple lines. It does have some limitations: multiple lines.
.LP It does have some limitations:
.TP 4 .Bl -enum
.B 1. .It
Preprocessor macros which cause unmatched parenthesis will confuse the Preprocessor macros which cause unmatched parenthesis will confuse the
checker for that line. To fix this, you'll need to make sure that each checker for that line.
branch of the #if statement has balanced parenthesis. To fix this, you'll need to make sure that each branch of the
.LP .Sy #if
.TP 4 statement has balanced parenthesis.
.B 2. .It
Some \fBcpp\fP macros do not require ;s after them. Any such macros Some
*must* be ALL_CAPS; any lower case letters will cause bad output. .Xr cpp 1
.LP macros do not require \fB;\fPs after them.
Any such macros
.Em must
be ALL_CAPS; any lower case letters will cause bad output.
.Pp
The bad output will generally be corrected after the next \fB;\fP, The bad output will generally be corrected after the next \fB;\fP,
\fB{\fP, or \fB}\fP. .Sy { ,
.LP or
Some continuation error messages deserve some additional explanation .Sy } .
.LP .El
.TP 4 Some continuation error messages deserve some additional explanation:
.B .Bl -tag -width Ds
multiple statements continued over multiple lines .It Sy multiple statements continued over multiple lines
A multi-line statement which is not broken at statement A multi-line statement which is not broken at statement boundaries.
boundaries. For example: For example:
.RS 4 .Bd -literal
.HP 4
if (this_is_a_long_variable == another_variable) a = if (this_is_a_long_variable == another_variable) a =
.br
b + c; b + c;
.LP .Ed
Will trigger this error. Instead, do: .Pp
.HP 8 Will trigger this error.
Instead, do:
.Bd -literal
if (this_is_a_long_variable == another_variable) if (this_is_a_long_variable == another_variable)
.br
a = b + c; a = b + c;
.RE .Ed
.LP .It Sy empty if/for/while body not on its own line
.TP 4
.B
empty if/for/while body not on its own line
For visibility, empty bodies for if, for, and while statements should be For visibility, empty bodies for if, for, and while statements should be
on their own line. For example: on their own line.
.RS 4 For example:
.HP 4 .Bd -literal
while (do_something(&x) == 0); while (do_something(&x) == 0);
.LP .Ed
Will trigger this error. Instead, do: .Pp
.HP 8 Will trigger this error.
Instead, do:
.Bd -literal
while (do_something(&x) == 0) while (do_something(&x) == 0)
.br
; ;
.RE .Ed
.El