1.\" Copyright (c) 1995-2001 FreeBSD Inc. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 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. 12.\" 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 23.\" SUCH DAMAGE. 24.\" 25.\" 26.Dd December 7, 2001 27.Dt STYLE 9 28.Os 29.Sh NAME 30.Nm style 31.Nd "kernel source file style guide" 32.Sh DESCRIPTION 33This file specifies the preferred style for kernel source files in the 34.Fx 35source tree. 36It is also a guide for preferred userland code style. 37Many of the style rules are implicit in the examples. 38Be careful to check the examples before assuming that 39.Nm 40is silent on an issue. 41.Bd -literal 42/* 43 * Style guide for DragonFly. Based on the CSRG's KNF (Kernel Normal Form). 44 * 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.5 2004/02/05 11:51:54 joerg Exp $ 48 */ 49 50/* 51 * VERY important single-line comments look like this. 52 */ 53 54/* Most single-line comments look like this. */ 55 56/* 57 * Multi-line comments look like this. Make them real sentences. Fill 58 * them so they look like real paragraphs. 59 */ 60 61/* 62 * XXX in a comment indicates code which is incomplete, suboptimal, 63 * or otherwise deserving of further attention. 64 */ 65 66.Ed 67.Pp 68Version control system ID tags should only exist once in a file 69(unlike this one). 70All VCS (version control system) revision identification from files obtained 71from elsewhere should be maintained in comments, including, where applicable, 72multiple IDs showing a file's history. 73In general, keep the IDs intact, including any 74.So Li $ Sc Ns s . 75There is no reason to add 76.Qq Li "From" 77in front of foreign VCS IDs. 78All VCS IDs should generally be placed in comments somewhere near the 79top of the source, typically either before or after the copyright message. 80.Pp 81Leave another blank line before the header files. 82.Pp 83Kernel include files (i.e.\& 84.Pa sys/*.h ) 85come first; normally, include 86.Aq Pa sys/types.h 87OR 88.Aq Pa sys/param.h , 89but not both. 90.Aq Pa sys/types.h 91includes 92.Aq Pa sys/cdefs.h , 93and it is okay to depend on that. 94.Bd -literal 95#include <sys/types.h> /* Non-local includes in angle brackets. */ 96.Ed 97.Pp 98For a network program, put the network include files next. 99.Bd -literal 100#include <net/if.h> 101#include <net/if_dl.h> 102#include <net/route.h> 103#include <netinet/in.h> 104#include <protocols/rwhod.h> 105.Ed 106.Pp 107Do not use files in 108.Pa /usr/include 109for files in the kernel. 110.Pp 111Leave a blank line before the next group, the 112.Pa /usr 113include files, 114which should be sorted alphabetically by name. 115.Bd -literal 116#include <stdio.h> 117.Ed 118.Pp 119Global pathnames are defined in 120.Aq Pa paths.h . 121Pathnames local 122to the program go in 123.Qq Pa pathnames.h 124in the local directory. 125.Bd -literal 126#include <paths.h> 127.Ed 128.Pp 129Leave another blank line before the user include files. 130.Bd -literal 131#include "pathnames.h" /* Local includes in double quotes. */ 132.Ed 133.Pp 134Do not 135.Ic #define 136or declare names in the implementation namespace except 137for implementing application interfaces. 138.Pp 139The names of 140.Dq unsafe 141macros (ones that have side effects), and the names of macros for 142manifest constants, are all in uppercase. 143The expansions of expression-like macros are either a single token 144or have outer parentheses. 145Put a single tab character between the 146.Ic #define 147and the macro name. 148If a macro is an inline expansion of a function, the function name is 149all in lowercase and the macro has the same name all in uppercase. 150.\" XXX the above conflicts with ANSI style where the names are the 151.\" same and you #undef the macro (if any) to get the function. 152.\" It is not followed for MALLOC(), and not very common if inline 153.\" functions are used. 154If a 155macro needs more than a single line, use braces 156.Ql ( \&{ 157and 158.Ql \&} ) . 159Right-justify the 160backslashes; it makes it easier to read. 161If the macro encapsulates a compound statement, enclose it in a 162.Ic do 163loop, 164so that it can safely be used in 165.Ic if 166statements. 167Any final statement-terminating semicolon should be 168supplied by the macro invocation rather than the macro, to make parsing easier 169for pretty-printers and editors. 170.Bd -literal 171#define MACRO(x, y) do { \e 172 variable = (x) + (y); \e 173 (y) += 2; \e 174} while(0) 175.Ed 176.Pp 177Enumeration values are all uppercase. 178.Bd -literal 179enum enumtype { ONE, TWO } et; 180.Ed 181.Pp 182When declaring variables in structures, declare them sorted by use, then 183by size, and then in alphabetical order. 184The first category normally does not apply, but there are exceptions. 185Each one gets its own line. 186Try to make the structure 187readable by aligning the member names using either one or two tabs 188depending upon your judgment. 189You should use one tab if it suffices to align most of the member names. 190Names following extremely long types 191should be separated by a single space. 192.Pp 193Major structures should be declared at the top of the file in which they 194are used, or in separate header files if they are used in multiple 195source files. 196Use of the structures should be by separate declarations 197and should be 198.Ic extern 199if they are declared in a header file. 200.Bd -literal 201struct foo { 202 struct foo *next; /* List of active foo. */ 203 struct mumble amumble; /* Comment for mumble. */ 204 int bar; /* Try to align the comments. */ 205 struct verylongtypename *baz; /* Won't fit in 2 tabs. */ 206}; 207struct foo *foohead; /* Head of global foo list. */ 208.Ed 209.Pp 210Use 211.Xr queue 3 212macros rather than rolling your own lists, whenever possible. 213Thus, 214the previous example would be better written: 215.Bd -literal 216#include <sys/queue.h> 217 218struct foo { 219 LIST_ENTRY(foo) link; /* Use queue macros for foo lists. */ 220 struct mumble amumble; /* Comment for mumble. */ 221 int bar; /* Try to align the comments. */ 222 struct verylongtypename *baz; /* Won't fit in 2 tabs. */ 223}; 224LIST_HEAD(, foo) foohead; /* Head of global foo list. */ 225.Ed 226.Pp 227Avoid using typedefs for structure types. 228This makes it impossible 229for applications to use pointers to such a structure opaquely, which 230is both possible and beneficial when using an ordinary struct tag. 231When convention requires a 232.Ic typedef , 233make its name match the struct tag. 234Avoid typedefs ending in 235.Dq Li _t , 236except as specified in Standard C or by \*[Px]. 237.Bd -literal 238/* Make the structure name match the typedef. */ 239typedef struct bar { 240 int level; 241} BAR; 242typedef int foo; /* This is foo. */ 243typedef const long baz; /* This is baz. */ 244.Ed 245.Pp 246All functions are prototyped somewhere. 247.Pp 248Function prototypes for private functions (i.e. functions not used 249elsewhere) go at the top of the first source module. 250Functions 251local to one source module should be declared 252.Ic static . 253.Pp 254Functions used from other parts of the kernel are prototyped in the 255relevant include file. 256.Pp 257Functions that are used locally in more than one module go into a 258separate header file, e.g.\& 259.Qq Pa extern.h . 260.Pp 261Avoid using the 262.Dv __P 263macro from the include file 264.Aq Pa sys/cdefs.h . 265Code in the DragonFly source tree is not 266expected to be K&R compliant. 267.Pp 268Changes to existing files should be consistent with that file's conventions. 269In general, code can be considered 270.Dq "new code" 271when it makes up about 50% or more of the file(s) involved. 272This is enough 273to break precedents in the existing code and use the current 274.Nm 275guidelines. 276.Pp 277The kernel has a name associated with parameter types, e.g., in the kernel 278use: 279.Bd -literal 280void function(int fd); 281.Ed 282.Pp 283In header files visible to userland applications, prototypes that are 284visible must use either 285.Dq protected 286names (ones beginning with an underscore) 287or no names with the types. 288It is preferable to use protected names. 289E.g., use: 290.Bd -literal 291void function(int); 292.Ed 293.Pp 294or: 295.Bd -literal 296void function(int _fd); 297.Ed 298.Pp 299Prototypes may have an extra space after a tab to enable function names 300to line up: 301.Bd -literal 302static char *function(int _arg, const char *_arg2, struct foo *_arg3, 303 struct bar *_arg4); 304static void usage(void); 305 306/* 307 * All major routines should have a comment briefly describing what 308 * they do. The comment before the "main" routine should describe 309 * what the program does. 310 */ 311int 312main(int argc, char *argv[]) 313{ 314 long num; 315 int ch; 316 char *ep; 317 318.Ed 319.Pp 320For consistency, 321.Xr getopt 3 322should be used to parse options. 323Options 324should be sorted in the 325.Xr getopt 3 326call and the 327.Ic switch 328statement, unless 329parts of the 330.Ic switch 331cascade. 332Elements in a 333.Ic switch 334statement that cascade should have a 335.Li FALLTHROUGH 336comment. 337Numerical arguments should be checked for accuracy. 338Code that cannot be reached should have a 339.Li NOTREACHED 340comment. 341.Bd -literal 342 while ((ch = getopt(argc, argv, "abn:")) != -1) 343 switch (ch) { /* Indent the switch. */ 344 case 'a': /* Don't indent the case. */ 345 aflag = 1; 346 /* FALLTHROUGH */ 347 case 'b': 348 bflag = 1; 349 break; 350 case 'n': 351 num = strtol(optarg, &ep, 10); 352 if (num <= 0 || *ep != '\e0') { 353 warnx("illegal number, -n argument -- %s", 354 optarg); 355 usage(); 356 } 357 break; 358 case '?': 359 default: 360 usage(); 361 /* NOTREACHED */ 362 } 363 argc -= optind; 364 argv += optind; 365.Ed 366.Pp 367Space after keywords 368.Pq Ic if , while , for , return , switch . 369No braces are 370used for control statements with zero or only a single statement unless that 371statement is more than a single line in which case they are permitted. 372Forever loops are done with 373.Ic for Ns 's , 374not 375.Ic while Ns 's . 376.Bd -literal 377 for (p = buf; *p != '\e0'; ++p) 378 ; /* nothing */ 379 for (;;) 380 stmt; 381 for (;;) { 382 z = a + really + long + statement + that + needs + 383 two lines + gets + indented + four + spaces + 384 on + the + second + and + subsequent + lines; 385 } 386 for (;;) { 387 if (cond) 388 stmt; 389 } 390 if (val != NULL) 391 val = realloc(val, newsize); 392.Ed 393.Pp 394Parts of a 395.Ic for 396loop may be left empty. 397Do not put declarations 398inside blocks unless the routine is unusually complicated. 399.Bd -literal 400 for (; cnt < 15; cnt++) { 401 stmt1; 402 stmt2; 403 } 404.Ed 405.Pp 406Indentation used for program block structure is an 8 character tab. 407Second level indents used for line continuation are four spaces. 408If you have to wrap a long statement, put the operator at the end of the 409line. 410.Bd -literal 411 while (cnt < 20 && this_variable_name_is_really_far_too_long && 412 ep != NULL) 413 z = a + really + long + statement + that + needs + 414 two lines + gets + indented + four + spaces + 415 on + the + second + and + subsequent + lines; 416.Ed 417.Pp 418Do not add whitespace at the end of a line, and only use tabs 419followed by spaces 420to form the indentation. 421Do not use more spaces than a tab will produce 422and do not use spaces in front of tabs. 423.Pp 424Closing and opening braces go on the same line as the 425.Ic else . 426Braces that are not necessary may be left out. 427.Bd -literal 428 if (test) 429 stmt; 430 else if (bar) { 431 stmt; 432 stmt; 433 } else 434 stmt; 435.Ed 436.Pp 437No spaces after function names. 438Commas have a space after them. 439No spaces 440after 441.Ql \&( 442or 443.Ql \&[ 444or preceding 445.Ql \&] 446or 447.Ql \&) 448characters. 449.Bd -literal 450 error = function(a1, a2); 451 if (error != 0) 452 exit(error); 453.Ed 454.Pp 455Unary operators do not require spaces, binary operators do. 456Do not use parentheses unless they are required for precedence or unless the 457statement is confusing without them. 458Remember that other people may become 459confused more easily than you. 460Do YOU understand the following? 461.Bd -literal 462 a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; 463 k = !(l & FLAGS); 464.Ed 465.Pp 466Exits should be 0 on success, or according to the predefined 467values in 468.Xr sysexits 3 . 469.Bd -literal 470 exit(EX_OK); /* 471 * Avoid obvious comments such as 472 * "Exit 0 on success." 473 */ 474} 475.Ed 476.Pp 477The function type should be on a line by itself 478preceding the function. 479.Bd -literal 480static char * 481function(int a1, int a2, float fl, int a4) 482{ 483.Ed 484.Pp 485When declaring variables in functions declare them sorted by size, 486then in alphabetical order; multiple ones per line are okay. 487If a line overflows reuse the type keyword. 488.Pp 489Be careful to not obfuscate the code by initializing variables in 490the declarations. 491Use this feature only thoughtfully. 492DO NOT use function calls in initializers. 493.Bd -literal 494 struct foo one, *two; 495 double three; 496 int *four, five; 497 char *six, seven, eight, nine, ten, eleven, twelve; 498 499 four = myfunction(); 500.Ed 501.Pp 502Do not declare functions inside other functions; ANSI C says that 503such declarations have file scope regardless of the nesting of the 504declaration. 505Hiding file declarations in what appears to be a local 506scope is undesirable and will elicit complaints from a good compiler. 507.Pp 508Casts are not followed by a space. 509Note that 510.Xr indent 1 511does not understand this rule. 512.Pp 513For the purposes of formatting, treat 514.Ic return 515and 516.Ic sizeof 517as functions. In other words, they are not 518followed by a space, and their single argument 519should be enclosed in parentheses. 520.Pp 521.Dv NULL 522is the preferred null pointer constant. 523Use 524.Dv NULL 525instead of 526.Vt ( "type *" ) Ns 0 527or 528.Vt ( "type *" ) Ns Dv NULL 529in contexts where the compiler knows the 530type, e.g., in assignments. 531Use 532.Vt ( "type *" ) Ns Dv NULL 533in other contexts, 534in particular for all function args. 535(Casting is essential for 536variadic args and is necessary for other args if the function prototype 537might not be in scope.) 538Test pointers against 539.Dv NULL , 540e.g., use: 541.Pp 542.Bd -literal 543(p = f()) == NULL 544.Ed 545.Pp 546not: 547.Bd -literal 548!(p = f()) 549.Ed 550.Pp 551Do not use 552.Ic \&! 553for tests unless it is a boolean, e.g. use 554.Bd -literal 555if (*p == '\e0') 556.Ed 557.Pp 558not 559.Bd -literal 560if (!*p) 561.Ed 562.Pp 563Routines returning 564.Vt "void *" 565should not have their return values cast 566to any pointer type. 567.Pp 568Use 569.Xr err 3 570or 571.Xr warn 3 , 572do not roll your own. 573.Bd -literal 574 if ((four = malloc(sizeof(struct foo))) == NULL) 575 err(1, (char *)NULL); 576 if ((six = (int *)overflow()) == NULL) 577 errx(1, "number overflowed"); 578 return (eight); 579} 580.Ed 581.Pp 582Avoid old-style function declarations that look like this: 583.Bd -literal 584static char * 585function(a1, a2, fl, a4) 586 int a1, a2; /* Declare ints, too, don't default them. */ 587 float fl; /* Beware double vs. float prototype differences. */ 588 int a4; /* List in order declared. */ 589{ 590.Ed 591.Pp 592Use ANSI function declarations instead. 593Long parameter lists are wrapped with a normal four space indent. 594.Pp 595Variable numbers of arguments should look like this. 596.Bd -literal 597#include <stdarg.h> 598 599void 600vaf(const char *fmt, ...) 601{ 602 va_list ap; 603 604 va_start(ap, fmt); 605 STUFF; 606 va_end(ap); 607 /* No return needed for void functions. */ 608} 609 610static void 611usage(void) 612{ 613 /* Insert an empty line if the function has no local variables. */ 614.Ed 615.Pp 616Use 617.Xr printf 3 , 618not 619.Xr fputs 3 , 620.Xr puts 3 , 621.Xr putchar 3 , 622whatever; it is faster and usually cleaner, not 623to mention avoiding stupid bugs. 624.Pp 625Usage statements should look like the manual pages 626.Sx SYNOPSIS . 627The usage statement should be structured in the following order: 628.Bl -enum 629.It 630Options without operands come first, 631in alphabetical order, 632inside a single set of brackets 633.Ql ( \&[ 634and 635.Ql \&] ) . 636.It 637Options with operands come next, 638also in alphabetical order, 639with each option and its argument inside its own pair of brackets. 640.It 641Required arguments 642(if any) 643are next, 644listed in the order they should be specified on the command line. 645.It 646Finally, 647any optional arguments should be listed, 648listed in the order they should be specified, 649and all inside brackets. 650.El 651.Pp 652A bar 653.Pq Ql \&| 654separates 655.Dq either-or 656options/arguments, 657and multiple options/arguments which are specified together are 658placed in a single set of brackets. 659.Bd -literal -offset 4n 660"usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en" 661"usage: f [-a | -b] [-c [-dEe] [-n number]]\en" 662.Ed 663.Bd -literal 664 (void)fprintf(stderr, "usage: f [-ab]\en"); 665 exit(EX_USAGE); 666} 667.Ed 668.Pp 669Note that the manual page options description should list the options in 670pure alphabetical order. 671That is, without regard to whether an option takes arguments or not. 672The alphabetical ordering should take into account the case ordering 673shown above. 674.Pp 675New core kernel code should be reasonably compliant with the 676.Nm 677guides. 678The guidelines for third-party maintained modules and device drivers are more 679relaxed but at a minimum should be internally consistent with their style. 680.Pp 681Stylistic changes (including whitespace changes) are hard on the source 682repository and are to be avoided without good reason. 683Code that is approximately 684.Fx 685KNF 686.Nm 687compliant in the repository must not diverge from compliance. 688.Pp 689Whenever possible, code should be run through a code checker 690(e.g., 691.Xr lint 1 692or 693.Nm gcc Fl Wall ) 694and produce minimal warnings. 695.Sh SEE ALSO 696.Xr indent 1 , 697.Xr lint 1 , 698.Xr err 3 , 699.Xr sysexits 3 , 700.Xr warn 3 701.Sh HISTORY 702This man page is largely based on the 703.Pa src/admin/style/style 704file from the 705.Bx 4.4 Lite2 706release, with occasional updates to reflect the current practice and 707desire of the 708.Fx 709project. 710