table of contents
other sections
STYLE(9) | Kernel Developer's Manual | STYLE(9) |
NAME¶
style
—
kernel source file style guide
DESCRIPTION¶
This file specifies the preferred style for kernel source files in the FreeBSD source tree. It is also a guide for the preferred userland code style. Many of the style rules are implicit in the examples. Be careful to check the examples before assuming thatstyle
is silent on an issue.
/* * Style guide for FreeBSD. Based on the CSRG's KNF (Kernel Normal Form). * * @(#)style 1.14 (Berkeley) 4/28/95 * $FreeBSD: releng/10.1/share/man/man9/style.9 217087 2011-01-07 08:34:12Z trasz $ */ /* * VERY important single-line comments look like this. */ /* Most single-line comments look like this. */ /* * Multi-line comments look like this. Make them real sentences. Fill * them so they look like real paragraphs. */
/*- * Copyright (c) 1984-2025 John Q. Public * All rights reserved. * * Long, boring license goes here, but trimmed for brevity */
/*-
”. If you desire to flag
indent(1) to not reformat a comment that starts
in the first column which is not a license or copyright notice, change the
dash to a star for those comments. Comments starting in columns other than the
first are never considered license statements.
After any copyright header, there is a blank line, and the
$FreeBSD$
for non C/C++ language source files. Version
control system ID tags should only exist once in a file (unlike in this one).
Non-C/C++ source files follow the example above, while C/C++ source files
follow the one below. All VCS (version control system) revision identification
in files obtained from elsewhere should be maintained, including, where
applicable, multiple IDs showing a file's history. In general, do not edit
foreign IDs or their infrastructure. Unless otherwise wrapped (such as
“#if defined(LIBC_SCCS)
”), enclose both
in “#if 0 ... #endif
” to hide any
uncompilable bits and to keep the IDs out of object files. Only add
“From:
” in front of foreign VCS IDs if
the file is renamed.
#if 0 #ifndef lint static char sccsid[] = "@(#)style 1.14 (Berkeley) 4/28/95"; #endif /* not lint */ #endif #include <sys/cdefs.h> __FBSDID("$FreeBSD: releng/10.1/share/man/man9/style.9 217087 2011-01-07 08:34:12Z trasz $");
<sys/types.h>
OR
<sys/param.h>
,
but not both.
<sys/types.h>
includes
<sys/cdefs.h>
,
and it is okay to depend on that.
#include <sys/types.h> /* Non-local includes in angle brackets. */
#include <net/if.h> #include <net/if_dl.h> #include <net/route.h> #include <netinet/in.h> #include <protocols/rwhod.h>
#include <stdio.h>
<paths.h>
.
Pathnames local to the program go in
“pathnames.h” in the local
directory.
#include <paths.h>
#include "pathnames.h" /* Local includes in double quotes. */
#define
or declare names in the
implementation namespace except for implementing application interfaces.
The names of “unsafe” macros (ones that have side effects), and
the names of macros for manifest constants, are all in uppercase. The
expansions of expression-like macros are either a single token or have outer
parentheses. Put a single tab character between the
#define
and the macro name. If a macro is
an inline expansion of a function, the function name is all in lowercase and
the macro has the same name all in uppercase. Right-justify the backslashes;
it makes it easier to read. If the macro encapsulates a compound statement,
enclose it in a do
loop, so that it can
safely be used in if
statements. Any final
statement-terminating semicolon should be supplied by the macro invocation
rather than the macro, to make parsing easier for pretty-printers and editors.
#define MACRO(x, y) do { \ variable = (x) + (y); \ (y) += 2; \ } while (0)
#ifdef
or
#if
, a comment may be added following the
matching #endif
or
#else
to permit the reader to easily
discern where conditionally compiled code regions end. This comment should be
used only for (subjectively) long regions, regions greater than 20 lines, or
where a series of nested #ifdef 's
may be
confusing to the reader. Exceptions may be made for cases where code is
conditionally not compiled for the purposes of
lint(1), even though the uncompiled region may be
small. The comment should be separated from the
#endif
or
#else
by a single space. For short
conditionally compiled regions, a closing comment should not be used.
The comment for #endif
should match the
expression used in the corresponding #if
or
#ifdef
. The comment for
#else
and
#elif
should match the inverse of the
expression(s) used in the preceding #if
and/or #elif
statements. In the comments,
the subexpression “defined(FOO)
” is
abbreviated as “FOO
”. For the purposes
of comments, “#ifndef
FOO
” is treated as
“#if
!defined(FOO)
”.
#ifdef KTRACE #include <sys/ktrace.h> #endif #ifdef COMPAT_43 /* A large region here, or other conditional code. */ #else /* !COMPAT_43 */ /* Or here. */ #endif /* COMPAT_43 */ #ifndef COMPAT_43 /* Yet another large region here, or other conditional code. */ #else /* COMPAT_43 */ /* Or here. */ #endif /* !COMPAT_43 */
enum enumtype { ONE, TWO } et;
typedef
-names other than the one being
declared.) Separate these identifiers from asterisks using a single space.
When declaring variables in structures, declare them sorted by use, then by size
(largest to smallest), and then in alphabetical order. The first category
normally does not apply, but there are exceptions. Each one gets its own line.
Try to make the structure readable by aligning the member names using either
one or two tabs depending upon your judgment. You should use one tab only if
it suffices to align at least 90% of the member names. Names following
extremely long types should be separated by a single space.
Major structures should be declared at the top of the file in which they are
used, or in separate header files if they are used in multiple source files.
Use of the structures should be by separate declarations and should be
extern
if they are declared in a header
file.
struct foo { struct foo *next; /* List of active foo. */ struct mumble amumble; /* Comment for mumble. */ int bar; /* Try to align the comments. */ struct verylongtypename *baz; /* Won't fit in 2 tabs. */ }; struct foo *foohead; /* Head of global foo list. */
#include <sys/queue.h> struct foo { LIST_ENTRY(foo) link; /* Use queue macros for foo lists. */ struct mumble amumble; /* Comment for mumble. */ int bar; /* Try to align the comments. */ struct verylongtypename *baz; /* Won't fit in 2 tabs. */ }; LIST_HEAD(, foo) foohead; /* Head of global foo list. */
typedef
, make its
name match the struct tag. Avoid typedefs ending in
“_t
”, except as specified in Standard C
or by POSIX.
/* Make the structure name match the typedef. */ typedef struct bar { int level; } BAR; typedef int foo; /* This is foo. */ typedef const long baz; /* This is baz. */
static
.
Functions used from other parts of the kernel are prototyped in the relevant
include file. Function prototypes should be listed in a logical order,
preferably alphabetical unless there is a compelling reason to use a different
ordering.
Functions that are used locally in more than one module go into a separate
header file, e.g. “extern.h”.
Do not use the __P
macro.
In general code can be considered “new code” when it makes up
about 50% or more of the file(s) involved. This is enough to break precedents
in the existing code and use the current
style
guidelines.
The kernel has a name associated with parameter types, e.g., in the kernel use:
void function(int fd);
void function(int);
void function(int _fd);
static char *function(int _arg, const char *_arg2, struct foo *_arg3, struct bar *_arg4); static void usage(void); /* * All major routines should have a comment briefly describing what * they do. The comment before the "main" routine should describe * what the program does. */ int main(int argc, char *argv[]) { char *ep; long num; int ch;
switch
statement, unless parts of the
switch
cascade. Elements in a
switch
statement that cascade should have a
FALLTHROUGH
comment. Numerical arguments should be
checked for accuracy. Code which is unreachable for non-obvious reasons may be
marked /* NOTREACHED
*/.
while ((ch = getopt(argc, argv, "abNn:")) != -1) switch (ch) { /* Indent the switch. */ case 'a': /* Don't indent the case. */ aflag = 1; /* Indent case body one tab. */ /* FALLTHROUGH */ case 'b': bflag = 1; break; case 'N': Nflag = 1; break; case 'n': num = strtol(optarg, &ep, 10); if (num <= 0 || *ep != '\0') { warnx("illegal number, -n argument -- %s", optarg); usage(); } break; case '?': default: usage(); } argc -= optind; argv += optind;
if
,
while
,
for
,
return
,
switch
). No braces
(‘{
’ and
‘}
’) are used for control statements
with zero or only a single statement unless that statement is more than a
single line in which case they are permitted. Forever loops are done with
for
's, not
while
's.
for (p = buf; *p != '\0'; ++p) ; /* nothing */ for (;;) stmt; for (;;) { z = a + really + long + statement + that + needs + two + lines + gets + indented + four + spaces + on + the + second + and + subsequent + lines; } for (;;) { if (cond) stmt; } if (val != NULL) val = realloc(val, newsize);
for
loop may be left empty. Do not
put declarations inside blocks unless the routine is unusually complicated.
for (; cnt < 15; cnt++) { stmt1; stmt2; }
while (cnt < 20 && this_variable_name_is_too_long && ep != NULL) z = a + really + long + statement + that + needs + two + lines + gets + indented + four + spaces + on + the + second + and + subsequent + lines;
else
. Braces that are not necessary may be
left out.
if (test) stmt; else if (bar) { stmt; stmt; } else stmt;
(
’ or
‘[
’ or preceding
‘]
’ or
‘)
’ characters.
error = function(a1, a2); if (error != 0) exit(error);
a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; k = !(l & FLAGS);
exit(0); /* * Avoid obvious comments such as * "Exit 0 on success." */ }
static char * function(int a1, int a2, float fl, int a4) {
struct foo one, *two; double three; int *four, five; char *six, seven, eight, nine, ten, eleven, twelve; four = myfunction();
sizeof
's are not followed by a
space. Note that indent(1) does not understand
this rule. sizeof
's are written with
parenthesis always. The redundant parenthesis rules do not apply to
sizeof
(var)
instances.
NULL
is the preferred null pointer constant.
Use NULL
instead of
(type *)0 or (type
*)NULL
in contexts where the compiler
knows the type, e.g., in assignments. Use (type
*)NULL
in other contexts, in
particular for all function args. (Casting is essential for variadic args and
is necessary for other args if the function prototype might not be in scope.)
Test pointers against NULL
, e.g., use:
(p = f()) == NULL
!(p = f())
!
for tests unless it is a
boolean, e.g. use:
if (*p == '\0')
if (!*p)
return
statements should be
enclosed in parentheses.
Use err(3) or warn(3),
do not roll your own.
if ((four = malloc(sizeof(struct foo))) == NULL) err(1, (char *)NULL); if ((six = (int *)overflow()) == NULL) errx(1, "number overflowed"); return (eight); }
static char * function(a1, a2, fl, a4) int a1, a2; /* Declare ints, too, don't default them. */ float fl; /* Beware double vs. float prototype differences. */ int a4; /* List in order declared. */ {
#include <stdarg.h> void vaf(const char *fmt, ...) { va_list ap; va_start(ap, fmt); STUFF; va_end(ap); /* No return needed for void functions. */ } static void usage() { /* Insert an empty line if the function has no local variables. */
- Options without operands come first, in alphabetical order, inside a
single set of brackets (‘
[
’ and ‘]
’). - Options with operands come next, also in alphabetical order, with each option and its argument inside its own pair of brackets.
- Required arguments (if any) are next, listed in the order they should be specified on the command line.
- Finally, any optional arguments should be listed, listed in the order they should be specified, and all inside brackets.
|
’) separates
“either-or” options/arguments, and multiple options/arguments
which are specified together are placed in a single set of brackets.
"usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n" "usage: f [-a | -b] [-c [-dEe] [-n number]]\n"
(void)fprintf(stderr, "usage: f [-ab]\n"); exit(1); }
style
guides. The guidelines for
third-party maintained modules and device drivers are more relaxed but at a
minimum should be internally consistent with their style.
Stylistic changes (including whitespace changes) are hard on the source
repository and are to be avoided without good reason. Code that is
approximately FreeBSD KNF
style
compliant in the repository must not
diverge from compliance.
Whenever possible, code should be run through a code checker (e.g.,
lint(1) or gcc
-Wall
) and produce minimal warnings.
SEE ALSO¶
indent(1), lint(1), err(3), warn(3), style.Makefile(5)HISTORY¶
This manual page is largely based on the src/admin/style/style file from the 4.4BSD-Lite2 release, with occasional updates to reflect the current practice and desire of the FreeBSD project. src/admin/style/style is a codification by the CSRG of the programming style of Ken Thompson and Dennis Ritchie in Version 6 AT&T UNIX.January 7, 2010 | Debian |