1 .\" Copyright (c) 1995-2001 FreeBSD Inc.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .Nd "kernel source file style guide"
33 This file specifies the preferred style for kernel source files in the
36 It is also a guide for preferred userland code style.
37 Many of the style rules are implicit in the examples.
38 Be careful to check the examples before assuming that
40 is silent on an issue.
43 * Style guide for FreeBSD. Based on the CSRG's KNF (Kernel Normal Form).
45 * @(#)style 1.14 (Berkeley) 4/28/95
46 * $FreeBSD: src/share/man/man9/style.9,v 1.32.2.19 2002/04/14 19:28:03 asmodai Exp $
50 * VERY important single-line comments look like this.
53 /* Most single-line comments look like this. */
56 * Multi-line comments look like this. Make them real sentences. Fill
57 * them so they look like real paragraphs.
61 After any copyright header, there is a blank line, and the
64 Version control system ID tags should only exist once in a file
66 Non-C/C++ source files follow the example above, while C/C++ source files
68 All VCS (version control system) revision identification from files obtained
69 from elsewhere should be maintained, including, where applicable, multiple IDs
70 showing a file's history.
71 In general, keep the IDs intact, including any
73 There is no reason to add
75 in front of foreign VCS IDs.
78 VCS IDs should be indented by a tab if in a comment.
80 #include <sys/cdefs.h>
81 __RCSID("@(#)style 1.14 (Berkeley) 4/28/95");
82 __FBSDID("$FreeBSD: src/share/man/man9/style.9,v 1.32.2.19 2002/04/14 19:28:03 asmodai Exp $");
85 Leave another blank line before the header files.
87 Kernel include files (i.e.\&
89 come first; normally, include
97 and it is okay to depend on that.
99 #include <sys/types.h> /* Non-local includes in angle brackets. */
102 For a network program, put the network include files next.
105 #include <net/if_dl.h>
106 #include <net/route.h>
107 #include <netinet/in.h>
108 #include <protocols/rwhod.h>
113 for files in the kernel.
115 Leave a blank line before the next group, the
118 which should be sorted alphabetically by name.
123 Global pathnames are defined in
128 in the local directory.
133 Leave another blank line before the user include files.
135 #include "pathnames.h" /* Local includes in double quotes. */
140 or declare names in the implementation namespace except
141 for implementing application interfaces.
145 macros (ones that have side effects), and the names of macros for
146 manifest constants, are all in uppercase.
147 The expansions of expression-like macros are either a single token
148 or have outer parentheses.
149 Put a single tab character between the
152 If a macro is an inline expansion of a function, the function name is
153 all in lowercase and the macro has the same name all in uppercase.
154 .\" XXX the above conflicts with ANSI style where the names are the
155 .\" same and you #undef the macro (if any) to get the function.
156 .\" It is not followed for MALLOC(), and not very common if inline
157 .\" functions are used.
159 macro needs more than a single line, use braces
164 backslashes; it makes it easier to read.
165 If the macro encapsulates a compound statement, enclose it in a
168 so that it can safely be used in
171 Any final statement-terminating semicolon should be
172 supplied by the macro invocation rather than the macro, to make parsing easier
173 for pretty-printers and editors.
175 #define MACRO(x, y) do { \e
176 variable = (x) + (y); \e
181 Enumeration values are all uppercase.
183 enum enumtype { ONE, TWO } et;
186 When declaring variables in structures, declare them sorted by use, then
187 by size, and then in alphabetical order.
188 The first category normally does not apply, but there are exceptions.
189 Each one gets its own line.
190 Try to make the structure
191 readable by aligning the member names using either one or two tabs
192 depending upon your judgment.
193 You should use one tab if it suffices to align most of the member names.
194 Names following extremely long types
195 should be separated by a single space.
197 Major structures should be declared at the top of the file in which they
198 are used, or in separate header files if they are used in multiple
200 Use of the structures should be by separate declarations
203 if they are declared in a header file.
206 struct foo *next; /* List of active foo. */
207 struct mumble amumble; /* Comment for mumble. */
208 int bar; /* Try to align the comments. */
209 struct verylongtypename *baz; /* Won't fit in 2 tabs. */
211 struct foo *foohead; /* Head of global foo list. */
216 macros rather than rolling your own lists, whenever possible.
218 the previous example would be better written:
220 #include <sys/queue.h>
223 LIST_ENTRY(foo) link; /* Use queue macros for foo lists. */
224 struct mumble amumble; /* Comment for mumble. */
225 int bar; /* Try to align the comments. */
226 struct verylongtypename *baz; /* Won't fit in 2 tabs. */
228 LIST_HEAD(, foo) foohead; /* Head of global foo list. */
231 Avoid using typedefs for structure types.
232 This makes it impossible
233 for applications to use pointers to such a structure opaquely, which
234 is both possible and beneficial when using an ordinary struct tag.
235 When convention requires a
237 make its name match the struct tag.
238 Avoid typedefs ending in
240 except as specified in Standard C or by \*[Px].
242 /* Make the structure name match the typedef. */
246 typedef int foo; /* This is foo. */
247 typedef const long baz; /* This is baz. */
250 All functions are prototyped somewhere.
252 Function prototypes for private functions (i.e. functions not used
253 elsewhere) go at the top of the first source module.
255 local to one source module should be declared
258 Functions used from other parts of the kernel are prototyped in the
259 relevant include file.
261 Functions that are used locally in more than one module go into a
262 separate header file, e.g.\&
267 macro from the include file
270 file in general is (to be) compilable with a K&R Old Testament compiler.
273 macro in new code is discouraged, although modifications
274 to existing files should be consistent with that file's conventions.
276 In general code can be considered
278 when it makes up about 50% or more of the file(s) involved.
280 to break precedents in the existing code and use the current
284 The kernel has a name associated with parameter types, e.g., in the kernel
287 void function(int fd);
290 In header files visible to userland applications, prototypes that are
291 visible must use either
293 names (ones beginning with an underscore)
294 or no names with the types.
295 It is preferable to use protected names.
303 void function(int _fd);
306 Prototypes may have an extra space after a tab to enable function names
309 static char *function(int _arg, const char *_arg2, struct foo *_arg3,
311 static void usage(void);
314 * All major routines should have a comment briefly describing what
315 * they do. The comment before the "main" routine should describe
316 * what the program does.
319 main(int argc, char *argv[])
329 should be used to parse options.
331 should be sorted in the
341 statement that cascade should have a
344 Numerical arguments should be checked for accuracy.
345 Code that cannot be reached should have a
349 while ((ch = getopt(argc, argv, "abn:")) != -1)
350 switch (ch) { /* Indent the switch. */
351 case 'a': /* Don't indent the case. */
358 num = strtol(optarg, &ep, 10);
359 if (num <= 0 || *ep != '\e0') {
360 warnx("illegal number, -n argument -- %s",
375 .Pq Ic if , while , for , return , switch .
377 used for control statements with zero or only a single statement unless that
378 statement is more than a single line in which case they are permitted.
379 Forever loops are done with
384 for (p = buf; *p != '\e0'; ++p)
389 z = a + really + long + statement + that + needs +
390 two lines + gets + indented + four + spaces +
391 on + the + second + and + subsequent + lines;
398 val = realloc(val, newsize);
403 loop may be left empty.
404 Do not put declarations
405 inside blocks unless the routine is unusually complicated.
407 for (; cnt < 15; cnt++) {
413 Indentation is an 8 character tab.
414 Second level indents are four spaces.
415 If you have to wrap a long statement, put the operator at the end of the
418 while (cnt < 20 && this_variable_name_is_too_long_for_its_own_good &&
420 z = a + really + long + statement + that + needs +
421 two lines + gets + indented + four + spaces +
422 on + the + second + and + subsequent + lines;
425 Do not add whitespace at the end of a line, and only use tabs
427 to form the indentation.
428 Do not use more spaces than a tab will produce
429 and do not use spaces in front of tabs.
431 Closing and opening braces go on the same line as the
433 Braces that are not necessary may be left out.
444 No spaces after function names.
445 Commas have a space after them.
457 error = function(a1, a2);
462 Unary operators do not require spaces, binary operators do.
463 Do not use parentheses unless they are required for precedence or unless the
464 statement is confusing without them.
465 Remember that other people may
466 confuse easier than you.
467 Do YOU understand the following?
469 a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
473 Exits should be 0 on success, or according to the predefined
478 * Avoid obvious comments such as
479 * "Exit 0 on success."
484 The function type should be on a line by itself
485 preceding the function.
488 function(int a1, int a2, float fl, int a4)
492 When declaring variables in functions declare them sorted by size,
493 then in alphabetical order; multiple ones per line are okay.
494 If a line overflows reuse the type keyword.
496 Be careful to not obfuscate the code by initializing variables in
498 Use this feature only thoughtfully.
499 DO NOT use function calls in initializers.
501 struct foo one, *two;
504 char *six, seven, eight, nine, ten, eleven, twelve;
509 Do not declare functions inside other functions; ANSI C says that
510 such declarations have file scope regardless of the nesting of the
512 Hiding file declarations in what appears to be a local
513 scope is undesirable and will elicit complaints from a good compiler.
517 are not followed by a space.
520 does not understand this rule.
523 is the preferred null pointer constant.
527 .Vt ( "type *" ) Ns 0
529 .Vt ( "type *" ) Ns Dv NULL
530 in contexts where the compiler knows the
531 type, e.g., in assignments.
533 .Vt ( "type *" ) Ns Dv NULL
535 in particular for all function args.
536 (Casting is essential for
537 variadic args and is necessary for other args if the function prototype
538 might not be in scope.)
539 Test pointers against
554 for tests unless it is a boolean, e.g. use
566 should not have their return values cast
573 do not roll your own.
575 if ((four = malloc(sizeof(struct foo))) == NULL)
576 err(1, (char *)NULL);
577 if ((six = (int *)overflow()) == NULL)
578 errx(1, "number overflowed");
583 Old-style function declarations look like this:
586 function(a1, a2, fl, a4)
587 int a1, a2; /* Declare ints, too, don't default them. */
588 float fl; /* Beware double vs. float prototype differences. */
589 int a4; /* List in order declared. */
593 Use ANSI function declarations unless you explicitly need K&R compatibility.
594 Long parameter lists are wrapped with a normal four space indent.
596 Variable numbers of arguments should look like this.
601 vaf(const char *fmt, ...)
608 /* No return needed for void functions. */
614 /* Insert an empty line if the function has no local variables. */
623 whatever; it is faster and usually cleaner, not
624 to mention avoiding stupid bugs.
626 Usage statements should look like the manual pages
628 The usage statement should be structured in the following order:
631 Options without operands come first,
632 in alphabetical order,
633 inside a single set of brackets
638 Options with operands come next,
639 also in alphabetical order,
640 with each option and its argument inside its own pair of brackets.
645 listed in the order they should be specified on the command line.
648 any optional arguments should be listed,
649 listed in the order they should be specified,
650 and all inside brackets.
658 and multiple options/arguments which are specified together are
659 placed in a single set of brackets.
660 .Bd -literal -offset 4n
661 "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en"
662 "usage: f [-a | -b] [-c [-dEe] [-n number]]\en"
665 (void)fprintf(stderr, "usage: f [-ab]\en");
670 Note that the manual page options description should list the options in
671 pure alphabetical order.
672 That is, without regard to whether an option takes arguments or not.
673 The alphabetical ordering should take into account the case ordering
676 New core kernel code should be reasonably compliant with the
679 The guidelines for third-party maintained modules and device drivers are more
680 relaxed but at a minimum should be internally consistent with their style.
682 Stylistic changes (including whitespace changes) are hard on the source
683 repository and are to be avoided without good reason.
684 Code that is approximately
688 compliant in the repository must not diverge from compliance.
690 Whenever possible, code should be run through a code checker
695 and produce minimal warnings.
703 This man page is largely based on the
704 .Pa src/admin/style/style
707 release, with occasional updates to reflect the current practice and