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 $
47 * $DragonFly: src/share/man/man9/style.9,v 1.2 2003/06/17 04:37:01 dillon Exp $
51 * VERY important single-line comments look like this.
54 /* Most single-line comments look like this. */
57 * Multi-line comments look like this. Make them real sentences. Fill
58 * them so they look like real paragraphs.
62 After any copyright header, there is a blank line, and the
65 Version control system ID tags should only exist once in a file
67 Non-C/C++ source files follow the example above, while C/C++ source files
69 All VCS (version control system) revision identification from files obtained
70 from elsewhere should be maintained, including, where applicable, multiple IDs
71 showing a file's history.
72 In general, keep the IDs intact, including any
74 There is no reason to add
76 in front of foreign VCS IDs.
79 VCS IDs should be indented by a tab if in a comment.
81 #include <sys/cdefs.h>
82 __RCSID("@(#)style 1.14 (Berkeley) 4/28/95");
83 __FBSDID("$FreeBSD: src/share/man/man9/style.9,v 1.32.2.19 2002/04/14 19:28:03 asmodai Exp $");
86 Leave another blank line before the header files.
88 Kernel include files (i.e.\&
90 come first; normally, include
98 and it is okay to depend on that.
100 #include <sys/types.h> /* Non-local includes in angle brackets. */
103 For a network program, put the network include files next.
106 #include <net/if_dl.h>
107 #include <net/route.h>
108 #include <netinet/in.h>
109 #include <protocols/rwhod.h>
114 for files in the kernel.
116 Leave a blank line before the next group, the
119 which should be sorted alphabetically by name.
124 Global pathnames are defined in
129 in the local directory.
134 Leave another blank line before the user include files.
136 #include "pathnames.h" /* Local includes in double quotes. */
141 or declare names in the implementation namespace except
142 for implementing application interfaces.
146 macros (ones that have side effects), and the names of macros for
147 manifest constants, are all in uppercase.
148 The expansions of expression-like macros are either a single token
149 or have outer parentheses.
150 Put a single tab character between the
153 If a macro is an inline expansion of a function, the function name is
154 all in lowercase and the macro has the same name all in uppercase.
155 .\" XXX the above conflicts with ANSI style where the names are the
156 .\" same and you #undef the macro (if any) to get the function.
157 .\" It is not followed for MALLOC(), and not very common if inline
158 .\" functions are used.
160 macro needs more than a single line, use braces
165 backslashes; it makes it easier to read.
166 If the macro encapsulates a compound statement, enclose it in a
169 so that it can safely be used in
172 Any final statement-terminating semicolon should be
173 supplied by the macro invocation rather than the macro, to make parsing easier
174 for pretty-printers and editors.
176 #define MACRO(x, y) do { \e
177 variable = (x) + (y); \e
182 Enumeration values are all uppercase.
184 enum enumtype { ONE, TWO } et;
187 When declaring variables in structures, declare them sorted by use, then
188 by size, and then in alphabetical order.
189 The first category normally does not apply, but there are exceptions.
190 Each one gets its own line.
191 Try to make the structure
192 readable by aligning the member names using either one or two tabs
193 depending upon your judgment.
194 You should use one tab if it suffices to align most of the member names.
195 Names following extremely long types
196 should be separated by a single space.
198 Major structures should be declared at the top of the file in which they
199 are used, or in separate header files if they are used in multiple
201 Use of the structures should be by separate declarations
204 if they are declared in a header file.
207 struct foo *next; /* List of active foo. */
208 struct mumble amumble; /* Comment for mumble. */
209 int bar; /* Try to align the comments. */
210 struct verylongtypename *baz; /* Won't fit in 2 tabs. */
212 struct foo *foohead; /* Head of global foo list. */
217 macros rather than rolling your own lists, whenever possible.
219 the previous example would be better written:
221 #include <sys/queue.h>
224 LIST_ENTRY(foo) link; /* Use queue macros for foo lists. */
225 struct mumble amumble; /* Comment for mumble. */
226 int bar; /* Try to align the comments. */
227 struct verylongtypename *baz; /* Won't fit in 2 tabs. */
229 LIST_HEAD(, foo) foohead; /* Head of global foo list. */
232 Avoid using typedefs for structure types.
233 This makes it impossible
234 for applications to use pointers to such a structure opaquely, which
235 is both possible and beneficial when using an ordinary struct tag.
236 When convention requires a
238 make its name match the struct tag.
239 Avoid typedefs ending in
241 except as specified in Standard C or by \*[Px].
243 /* Make the structure name match the typedef. */
247 typedef int foo; /* This is foo. */
248 typedef const long baz; /* This is baz. */
251 All functions are prototyped somewhere.
253 Function prototypes for private functions (i.e. functions not used
254 elsewhere) go at the top of the first source module.
256 local to one source module should be declared
259 Functions used from other parts of the kernel are prototyped in the
260 relevant include file.
262 Functions that are used locally in more than one module go into a
263 separate header file, e.g.\&
268 macro from the include file
271 file in general is (to be) compilable with a K&R Old Testament compiler.
274 macro in new code is discouraged, although modifications
275 to existing files should be consistent with that file's conventions.
277 In general code can be considered
279 when it makes up about 50% or more of the file(s) involved.
281 to break precedents in the existing code and use the current
285 The kernel has a name associated with parameter types, e.g., in the kernel
288 void function(int fd);
291 In header files visible to userland applications, prototypes that are
292 visible must use either
294 names (ones beginning with an underscore)
295 or no names with the types.
296 It is preferable to use protected names.
304 void function(int _fd);
307 Prototypes may have an extra space after a tab to enable function names
310 static char *function(int _arg, const char *_arg2, struct foo *_arg3,
312 static void usage(void);
315 * All major routines should have a comment briefly describing what
316 * they do. The comment before the "main" routine should describe
317 * what the program does.
320 main(int argc, char *argv[])
330 should be used to parse options.
332 should be sorted in the
342 statement that cascade should have a
345 Numerical arguments should be checked for accuracy.
346 Code that cannot be reached should have a
350 while ((ch = getopt(argc, argv, "abn:")) != -1)
351 switch (ch) { /* Indent the switch. */
352 case 'a': /* Don't indent the case. */
359 num = strtol(optarg, &ep, 10);
360 if (num <= 0 || *ep != '\e0') {
361 warnx("illegal number, -n argument -- %s",
376 .Pq Ic if , while , for , return , switch .
378 used for control statements with zero or only a single statement unless that
379 statement is more than a single line in which case they are permitted.
380 Forever loops are done with
385 for (p = buf; *p != '\e0'; ++p)
390 z = a + really + long + statement + that + needs +
391 two lines + gets + indented + four + spaces +
392 on + the + second + and + subsequent + lines;
399 val = realloc(val, newsize);
404 loop may be left empty.
405 Do not put declarations
406 inside blocks unless the routine is unusually complicated.
408 for (; cnt < 15; cnt++) {
414 Indentation is an 8 character tab.
415 Second level indents are four spaces.
416 If you have to wrap a long statement, put the operator at the end of the
419 while (cnt < 20 && this_variable_name_is_too_long_for_its_own_good &&
421 z = a + really + long + statement + that + needs +
422 two lines + gets + indented + four + spaces +
423 on + the + second + and + subsequent + lines;
426 Do not add whitespace at the end of a line, and only use tabs
428 to form the indentation.
429 Do not use more spaces than a tab will produce
430 and do not use spaces in front of tabs.
432 Closing and opening braces go on the same line as the
434 Braces that are not necessary may be left out.
445 No spaces after function names.
446 Commas have a space after them.
458 error = function(a1, a2);
463 Unary operators do not require spaces, binary operators do.
464 Do not use parentheses unless they are required for precedence or unless the
465 statement is confusing without them.
466 Remember that other people may
467 confuse easier than you.
468 Do YOU understand the following?
470 a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
474 Exits should be 0 on success, or according to the predefined
479 * Avoid obvious comments such as
480 * "Exit 0 on success."
485 The function type should be on a line by itself
486 preceding the function.
489 function(int a1, int a2, float fl, int a4)
493 When declaring variables in functions declare them sorted by size,
494 then in alphabetical order; multiple ones per line are okay.
495 If a line overflows reuse the type keyword.
497 Be careful to not obfuscate the code by initializing variables in
499 Use this feature only thoughtfully.
500 DO NOT use function calls in initializers.
502 struct foo one, *two;
505 char *six, seven, eight, nine, ten, eleven, twelve;
510 Do not declare functions inside other functions; ANSI C says that
511 such declarations have file scope regardless of the nesting of the
513 Hiding file declarations in what appears to be a local
514 scope is undesirable and will elicit complaints from a good compiler.
518 are not followed by a space.
521 does not understand this rule.
524 is the preferred null pointer constant.
528 .Vt ( "type *" ) Ns 0
530 .Vt ( "type *" ) Ns Dv NULL
531 in contexts where the compiler knows the
532 type, e.g., in assignments.
534 .Vt ( "type *" ) Ns Dv NULL
536 in particular for all function args.
537 (Casting is essential for
538 variadic args and is necessary for other args if the function prototype
539 might not be in scope.)
540 Test pointers against
555 for tests unless it is a boolean, e.g. use
567 should not have their return values cast
574 do not roll your own.
576 if ((four = malloc(sizeof(struct foo))) == NULL)
577 err(1, (char *)NULL);
578 if ((six = (int *)overflow()) == NULL)
579 errx(1, "number overflowed");
584 Old-style function declarations look like this:
587 function(a1, a2, fl, a4)
588 int a1, a2; /* Declare ints, too, don't default them. */
589 float fl; /* Beware double vs. float prototype differences. */
590 int a4; /* List in order declared. */
594 Use ANSI function declarations unless you explicitly need K&R compatibility.
595 Long parameter lists are wrapped with a normal four space indent.
597 Variable numbers of arguments should look like this.
602 vaf(const char *fmt, ...)
609 /* No return needed for void functions. */
615 /* Insert an empty line if the function has no local variables. */
624 whatever; it is faster and usually cleaner, not
625 to mention avoiding stupid bugs.
627 Usage statements should look like the manual pages
629 The usage statement should be structured in the following order:
632 Options without operands come first,
633 in alphabetical order,
634 inside a single set of brackets
639 Options with operands come next,
640 also in alphabetical order,
641 with each option and its argument inside its own pair of brackets.
646 listed in the order they should be specified on the command line.
649 any optional arguments should be listed,
650 listed in the order they should be specified,
651 and all inside brackets.
659 and multiple options/arguments which are specified together are
660 placed in a single set of brackets.
661 .Bd -literal -offset 4n
662 "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en"
663 "usage: f [-a | -b] [-c [-dEe] [-n number]]\en"
666 (void)fprintf(stderr, "usage: f [-ab]\en");
671 Note that the manual page options description should list the options in
672 pure alphabetical order.
673 That is, without regard to whether an option takes arguments or not.
674 The alphabetical ordering should take into account the case ordering
677 New core kernel code should be reasonably compliant with the
680 The guidelines for third-party maintained modules and device drivers are more
681 relaxed but at a minimum should be internally consistent with their style.
683 Stylistic changes (including whitespace changes) are hard on the source
684 repository and are to be avoided without good reason.
685 Code that is approximately
689 compliant in the repository must not diverge from compliance.
691 Whenever possible, code should be run through a code checker
696 and produce minimal warnings.
704 This man page is largely based on the
705 .Pa src/admin/style/style
708 release, with occasional updates to reflect the current practice and