Debian Codegraph @

CodingStyle

raw
1 The coding conventions of the netsniff-ng toolkit match with the Linux kernel
2 style guidelines. So here we go with a copy of linux/Documentation/CodingStyle
3 written by Linus.
4
5 In general, keep this in mind: (i) simplicity, (ii) brevity, (iii) elegance.
6 You are also obliged to treat documentation files in the same quality as code.
7
8 Daniel Borkmann
9
10 -------------------------------------------------------------------------------
11
12 Linux kernel coding style
13
14 This is a short document describing the preferred coding style for the
15 linux kernel. Coding style is very personal, and I won't _force_ my
16 views on anybody, but this is what goes for anything that I have to be
17 able to maintain, and I'd prefer it for most other things too. Please
18 at least consider the points made here.
19
20 First off, I'd suggest printing out a copy of the GNU coding standards,
21 and NOT read it. Burn them, it's a great symbolic gesture.
22
23 Anyway, here goes:
24
25
26 Chapter 1: Indentation
27
28 Tabs are 8 characters, and thus indentations are also 8 characters.
29 There are heretic movements that try to make indentations 4 (or even 2!)
30 characters deep, and that is akin to trying to define the value of PI to
31 be 3.
32
33 Rationale: The whole idea behind indentation is to clearly define where
34 a block of control starts and ends. Especially when you've been looking
35 at your screen for 20 straight hours, you'll find it a lot easier to see
36 how the indentation works if you have large indentations.
37
38 Now, some people will claim that having 8-character indentations makes
39 the code move too far to the right, and makes it hard to read on a
40 80-character terminal screen. The answer to that is that if you need
41 more than 3 levels of indentation, you're screwed anyway, and should fix
42 your program.
43
44 In short, 8-char indents make things easier to read, and have the added
45 benefit of warning you when you're nesting your functions too deep.
46 Heed that warning.
47
48 The preferred way to ease multiple indentation levels in a switch statement is
49 to align the "switch" and its subordinate "case" labels in the same column
50 instead of "double-indenting" the "case" labels. E.g.:
51
52 switch (suffix) {
53 case 'G':
54 case 'g':
55 mem <<= 30;
56 break;
57 case 'M':
58 case 'm':
59 mem <<= 20;
60 break;
61 case 'K':
62 case 'k':
63 mem <<= 10;
64 /* fall through */
65 default:
66 break;
67 }
68
69
70 Don't put multiple statements on a single line unless you have
71 something to hide:
72
73 if (condition) do_this;
74 do_something_everytime;
75
76 Don't put multiple assignments on a single line either. Kernel coding style
77 is super simple. Avoid tricky expressions.
78
79 Outside of comments, documentation and except in Kconfig, spaces are never
80 used for indentation, and the above example is deliberately broken.
81
82 Get a decent editor and don't leave whitespace at the end of lines.
83
84
85 Chapter 2: Breaking long lines and strings
86
87 Coding style is all about readability and maintainability using commonly
88 available tools.
89
90 The limit on the length of lines is 80 columns and this is a strongly
91 preferred limit.
92
93 Statements longer than 80 columns will be broken into sensible chunks.
94 Descendants are always substantially shorter than the parent and are placed
95 substantially to the right. The same applies to function headers with a long
96 argument list. Long strings are as well broken into shorter strings. The
97 only exception to this is where exceeding 80 columns significantly increases
98 readability and does not hide information.
99
100 void fun(int a, int b, int c)
101 {
102 if (condition)
103 printk(KERN_WARNING "Warning this is a long printk with "
104 "3 parameters a: %u b: %u "
105 "c: %u \n", a, b, c);
106 else
107 next_statement;
108 }
109
110 Chapter 3: Placing Braces and Spaces
111
112 The other issue that always comes up in C styling is the placement of
113 braces. Unlike the indent size, there are few technical reasons to
114 choose one placement strategy over the other, but the preferred way, as
115 shown to us by the prophets Kernighan and Ritchie, is to put the opening
116 brace last on the line, and put the closing brace first, thusly:
117
118 if (x is true) {
119 we do y
120 }
121
122 This applies to all non-function statement blocks (if, switch, for,
123 while, do). E.g.:
124
125 switch (action) {
126 case KOBJ_ADD:
127 return "add";
128 case KOBJ_REMOVE:
129 return "remove";
130 case KOBJ_CHANGE:
131 return "change";
132 default:
133 return NULL;
134 }
135
136 However, there is one special case, namely functions: they have the
137 opening brace at the beginning of the next line, thus:
138
139 int function(int x)
140 {
141 body of function
142 }
143
144 Heretic people all over the world have claimed that this inconsistency
145 is ... well ... inconsistent, but all right-thinking people know that
146 (a) K&R are _right_ and (b) K&R are right. Besides, functions are
147 special anyway (you can't nest them in C).
148
149 Note that the closing brace is empty on a line of its own, _except_ in
150 the cases where it is followed by a continuation of the same statement,
151 ie a "while" in a do-statement or an "else" in an if-statement, like
152 this:
153
154 do {
155 body of do-loop
156 } while (condition);
157
158 and
159
160 if (x == y) {
161 ..
162 } else if (x > y) {
163 ...
164 } else {
165 ....
166 }
167
168 Rationale: K&R.
169
170 Also, note that this brace-placement also minimizes the number of empty
171 (or almost empty) lines, without any loss of readability. Thus, as the
172 supply of new-lines on your screen is not a renewable resource (think
173 25-line terminal screens here), you have more empty lines to put
174 comments on.
175
176 Do not unnecessarily use braces where a single statement will do.
177
178 if (condition)
179 action();
180
181 This does not apply if one branch of a conditional statement is a single
182 statement. Use braces in both branches.
183
184 if (condition) {
185 do_this();
186 do_that();
187 } else {
188 otherwise();
189 }
190
191 3.1: Spaces
192
193 Linux kernel style for use of spaces depends (mostly) on
194 function-versus-keyword usage. Use a space after (most) keywords. The
195 notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
196 somewhat like functions (and are usually used with parentheses in Linux,
197 although they are not required in the language, as in: "sizeof info" after
198 "struct fileinfo info;" is declared).
199
200 So use a space after these keywords:
201 if, switch, case, for, do, while
202 but not with sizeof, typeof, alignof, or __attribute__. E.g.,
203 s = sizeof(struct file);
204
205 Do not add spaces around (inside) parenthesized expressions. This example is
206 *bad*:
207
208 s = sizeof( struct file );
209
210 When declaring pointer data or a function that returns a pointer type, the
211 preferred use of '*' is adjacent to the data name or function name and not
212 adjacent to the type name. Examples:
213
214 char *linux_banner;
215 unsigned long long memparse(char *ptr, char **retptr);
216 char *match_strdup(substring_t *s);
217
218 Use one space around (on each side of) most binary and ternary operators,
219 such as any of these:
220
221 = + - < > * / % | & ^ <= >= == != ? :
222
223 but no space after unary operators:
224 & * + - ~ ! sizeof typeof alignof __attribute__ defined
225
226 no space before the postfix increment & decrement unary operators:
227 ++ --
228
229 no space after the prefix increment & decrement unary operators:
230 ++ --
231
232 and no space around the '.' and "->" structure member operators.
233
234 Do not leave trailing whitespace at the ends of lines. Some editors with
235 "smart" indentation will insert whitespace at the beginning of new lines as
236 appropriate, so you can start typing the next line of code right away.
237 However, some such editors do not remove the whitespace if you end up not
238 putting a line of code there, such as if you leave a blank line. As a result,
239 you end up with lines containing trailing whitespace.
240
241 Git will warn you about patches that introduce trailing whitespace, and can
242 optionally strip the trailing whitespace for you; however, if applying a series
243 of patches, this may make later patches in the series fail by changing their
244 context lines.
245
246
247 Chapter 4: Naming
248
249 C is a Spartan language, and so should your naming be. Unlike Modula-2
250 and Pascal programmers, C programmers do not use cute names like
251 ThisVariableIsATemporaryCounter. A C programmer would call that
252 variable "tmp", which is much easier to write, and not the least more
253 difficult to understand.
254
255 HOWEVER, while mixed-case names are frowned upon, descriptive names for
256 global variables are a must. To call a global function "foo" is a
257 shooting offense.
258
259 GLOBAL variables (to be used only if you _really_ need them) need to
260 have descriptive names, as do global functions. If you have a function
261 that counts the number of active users, you should call that
262 "count_active_users()" or similar, you should _not_ call it "cntusr()".
263
264 Encoding the type of a function into the name (so-called Hungarian
265 notation) is brain damaged - the compiler knows the types anyway and can
266 check those, and it only confuses the programmer. No wonder MicroSoft
267 makes buggy programs.
268
269 LOCAL variable names should be short, and to the point. If you have
270 some random integer loop counter, it should probably be called "i".
271 Calling it "loop_counter" is non-productive, if there is no chance of it
272 being mis-understood. Similarly, "tmp" can be just about any type of
273 variable that is used to hold a temporary value.
274
275 If you are afraid to mix up your local variable names, you have another
276 problem, which is called the function-growth-hormone-imbalance syndrome.
277 See chapter 6 (Functions).
278
279
280 Chapter 5: Typedefs
281
282 Please don't use things like "vps_t".
283
284 It's a _mistake_ to use typedef for structures and pointers. When you see a
285
286 vps_t a;
287
288 in the source, what does it mean?
289
290 In contrast, if it says
291
292 struct virtual_container *a;
293
294 you can actually tell what "a" is.
295
296 Lots of people think that typedefs "help readability". Not so. They are
297 useful only for:
298
299 (a) totally opaque objects (where the typedef is actively used to _hide_
300 what the object is).
301
302 Example: "pte_t" etc. opaque objects that you can only access using
303 the proper accessor functions.
304
305 NOTE! Opaqueness and "accessor functions" are not good in themselves.
306 The reason we have them for things like pte_t etc. is that there
307 really is absolutely _zero_ portably accessible information there.
308
309 (b) Clear integer types, where the abstraction _helps_ avoid confusion
310 whether it is "int" or "long".
311
312 u8/u16/u32 are perfectly fine typedefs, although they fit into
313 category (d) better than here.
314
315 NOTE! Again - there needs to be a _reason_ for this. If something is
316 "unsigned long", then there's no reason to do
317
318 typedef unsigned long myflags_t;
319
320 but if there is a clear reason for why it under certain circumstances
321 might be an "unsigned int" and under other configurations might be
322 "unsigned long", then by all means go ahead and use a typedef.
323
324 (c) when you use sparse to literally create a _new_ type for
325 type-checking.
326
327 (d) New types which are identical to standard C99 types, in certain
328 exceptional circumstances.
329
330 Although it would only take a short amount of time for the eyes and
331 brain to become accustomed to the standard types like 'uint32_t',
332 some people object to their use anyway.
333
334 Therefore, the Linux-specific 'u8/u16/u32/u64' types and their
335 signed equivalents which are identical to standard types are
336 permitted -- although they are not mandatory in new code of your
337 own.
338
339 When editing existing code which already uses one or the other set
340 of types, you should conform to the existing choices in that code.
341
342 (e) Types safe for use in userspace.
343
344 In certain structures which are visible to userspace, we cannot
345 require C99 types and cannot use the 'u32' form above. Thus, we
346 use __u32 and similar types in all structures which are shared
347 with userspace.
348
349 Maybe there are other cases too, but the rule should basically be to NEVER
350 EVER use a typedef unless you can clearly match one of those rules.
351
352 In general, a pointer, or a struct that has elements that can reasonably
353 be directly accessed should _never_ be a typedef.
354
355
356 Chapter 6: Functions
357
358 Functions should be short and sweet, and do just one thing. They should
359 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
360 as we all know), and do one thing and do that well.
361
362 The maximum length of a function is inversely proportional to the
363 complexity and indentation level of that function. So, if you have a
364 conceptually simple function that is just one long (but simple)
365 case-statement, where you have to do lots of small things for a lot of
366 different cases, it's OK to have a longer function.
367
368 However, if you have a complex function, and you suspect that a
369 less-than-gifted first-year high-school student might not even
370 understand what the function is all about, you should adhere to the
371 maximum limits all the more closely. Use helper functions with
372 descriptive names (you can ask the compiler to in-line them if you think
373 it's performance-critical, and it will probably do a better job of it
374 than you would have done).
375
376 Another measure of the function is the number of local variables. They
377 shouldn't exceed 5-10, or you're doing something wrong. Re-think the
378 function, and split it into smaller pieces. A human brain can
379 generally easily keep track of about 7 different things, anything more
380 and it gets confused. You know you're brilliant, but maybe you'd like
381 to understand what you did 2 weeks from now.
382
383 In source files, separate functions with one blank line. If the function is
384 exported, the EXPORT* macro for it should follow immediately after the closing
385 function brace line. E.g.:
386
387 int system_is_up(void)
388 {
389 return system_state == SYSTEM_RUNNING;
390 }
391 EXPORT_SYMBOL(system_is_up);
392
393 In function prototypes, include parameter names with their data types.
394 Although this is not required by the C language, it is preferred in Linux
395 because it is a simple way to add valuable information for the reader.
396
397
398 Chapter 7: Centralized exiting of functions
399
400 Albeit deprecated by some people, the equivalent of the goto statement is
401 used frequently by compilers in form of the unconditional jump instruction.
402
403 The goto statement comes in handy when a function exits from multiple
404 locations and some common work such as cleanup has to be done.
405
406 The rationale is:
407
408 - unconditional statements are easier to understand and follow
409 - nesting is reduced
410 - errors by not updating individual exit points when making
411 modifications are prevented
412 - saves the compiler work to optimize redundant code away ;)
413
414 int fun(int a)
415 {
416 int result = 0;
417 char *buffer = kmalloc(SIZE);
418
419 if (buffer == NULL)
420 return -ENOMEM;
421
422 if (condition1) {
423 while (loop1) {
424 ...
425 }
426 result = 1;
427 goto out;
428 }
429 ...
430 out:
431 kfree(buffer);
432 return result;
433 }
434
435 Chapter 8: Commenting
436
437 Comments are good, but there is also a danger of over-commenting. NEVER
438 try to explain HOW your code works in a comment: it's much better to
439 write the code so that the _working_ is obvious, and it's a waste of
440 time to explain badly written code.
441
442 Generally, you want your comments to tell WHAT your code does, not HOW.
443 Also, try to avoid putting comments inside a function body: if the
444 function is so complex that you need to separately comment parts of it,
445 you should probably go back to chapter 6 for a while. You can make
446 small comments to note or warn about something particularly clever (or
447 ugly), but try to avoid excess. Instead, put the comments at the head
448 of the function, telling people what it does, and possibly WHY it does
449 it.
450
451 When commenting the kernel API functions, please use the kernel-doc format.
452 See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
453 for details.
454
455 Linux style for comments is the C89 "/* ... */" style.
456 Don't use C99-style "// ..." comments.
457
458 The preferred style for long (multi-line) comments is:
459
460 /*
461 * This is the preferred style for multi-line
462 * comments in the Linux kernel source code.
463 * Please use it consistently.
464 *
465 * Description: A column of asterisks on the left side,
466 * with beginning and ending almost-blank lines.
467 */
468
469 It's also important to comment data, whether they are basic types or derived
470 types. To this end, use just one data declaration per line (no commas for
471 multiple data declarations). This leaves you room for a small comment on each
472 item, explaining its use.
473
474
475 Chapter 9: You've made a mess of it
476
477 That's OK, we all do. You've probably been told by your long-time Unix
478 user helper that "GNU emacs" automatically formats the C sources for
479 you, and you've noticed that yes, it does do that, but the defaults it
480 uses are less than desirable (in fact, they are worse than random
481 typing - an infinite number of monkeys typing into GNU emacs would never
482 make a good program).
483
484 So, you can either get rid of GNU emacs, or change it to use saner
485 values. To do the latter, you can stick the following in your .emacs file:
486
487 (defun c-lineup-arglist-tabs-only (ignored)
488 "Line up argument lists by tabs, not spaces"
489 (let* ((anchor (c-langelem-pos c-syntactic-element))
490 (column (c-langelem-2nd-pos c-syntactic-element))
491 (offset (- (1+ column) anchor))
492 (steps (floor offset c-basic-offset)))
493 (* (max steps 1)
494 c-basic-offset)))
495
496 (add-hook 'c-mode-common-hook
497 (lambda ()
498 ;; Add kernel style
499 (c-add-style
500 "linux-tabs-only"
501 '("linux" (c-offsets-alist
502 (arglist-cont-nonempty
503 c-lineup-gcc-asm-reg
504 c-lineup-arglist-tabs-only))))))
505
506 (add-hook 'c-mode-hook
507 (lambda ()
508 (let ((filename (buffer-file-name)))
509 ;; Enable kernel mode for the appropriate files
510 (when (and filename
511 (string-match (expand-file-name "~/src/linux-trees")
512 filename))
513 (setq indent-tabs-mode t)
514 (c-set-style "linux-tabs-only")))))
515
516 This will make emacs go better with the kernel coding style for C
517 files below ~/src/linux-trees.
518
519 But even if you fail in getting emacs to do sane formatting, not
520 everything is lost: use "indent".
521
522 Now, again, GNU indent has the same brain-dead settings that GNU emacs
523 has, which is why you need to give it a few command line options.
524 However, that's not too bad, because even the makers of GNU indent
525 recognize the authority of K&R (the GNU people aren't evil, they are
526 just severely misguided in this matter), so you just give indent the
527 options "-kr -i8" (stands for "K&R, 8 character indents"), or use
528 "scripts/Lindent", which indents in the latest style.
529
530 "indent" has a lot of options, and especially when it comes to comment
531 re-formatting you may want to take a look at the man page. But
532 remember: "indent" is not a fix for bad programming.
533
534
535 Chapter 10: Kconfig configuration files
536
537 For all of the Kconfig* configuration files throughout the source tree,
538 the indentation is somewhat different. Lines under a "config" definition
539 are indented with one tab, while help text is indented an additional two
540 spaces. Example:
541
542 config AUDIT
543 bool "Auditing support"
544 depends on NET
545 help
546 Enable auditing infrastructure that can be used with another
547 kernel subsystem, such as SELinux (which requires this for
548 logging of avc messages output). Does not do system-call
549 auditing without CONFIG_AUDITSYSCALL.
550
551 Features that might still be considered unstable should be defined as
552 dependent on "EXPERIMENTAL":
553
554 config SLUB
555 depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT
556 bool "SLUB (Unqueued Allocator)"
557 ...
558
559 while seriously dangerous features (such as write support for certain
560 filesystems) should advertise this prominently in their prompt string:
561
562 config ADFS_FS_RW
563 bool "ADFS write support (DANGEROUS)"
564 depends on ADFS_FS
565 ...
566
567 For full documentation on the configuration files, see the file
568 Documentation/kbuild/kconfig-language.txt.
569
570
571 Chapter 11: Data structures
572
573 Data structures that have visibility outside the single-threaded
574 environment they are created and destroyed in should always have
575 reference counts. In the kernel, garbage collection doesn't exist (and
576 outside the kernel garbage collection is slow and inefficient), which
577 means that you absolutely _have_ to reference count all your uses.
578
579 Reference counting means that you can avoid locking, and allows multiple
580 users to have access to the data structure in parallel - and not having
581 to worry about the structure suddenly going away from under them just
582 because they slept or did something else for a while.
583
584 Note that locking is _not_ a replacement for reference counting.
585 Locking is used to keep data structures coherent, while reference
586 counting is a memory management technique. Usually both are needed, and
587 they are not to be confused with each other.
588
589 Many data structures can indeed have two levels of reference counting,
590 when there are users of different "classes". The subclass count counts
591 the number of subclass users, and decrements the global count just once
592 when the subclass count goes to zero.
593
594 Examples of this kind of "multi-level-reference-counting" can be found in
595 memory management ("struct mm_struct": mm_users and mm_count), and in
596 filesystem code ("struct super_block": s_count and s_active).
597
598 Remember: if another thread can find your data structure, and you don't
599 have a reference count on it, you almost certainly have a bug.
600
601
602 Chapter 12: Macros, Enums and RTL
603
604 Names of macros defining constants and labels in enums are capitalized.
605
606 #define CONSTANT 0x12345
607
608 Enums are preferred when defining several related constants.
609
610 CAPITALIZED macro names are appreciated but macros resembling functions
611 may be named in lower case.
612
613 Generally, inline functions are preferable to macros resembling functions.
614
615 Macros with multiple statements should be enclosed in a do - while block:
616
617 #define macrofun(a, b, c) \
618 do { \
619 if (a == 5) \
620 do_this(b, c); \
621 } while (0)
622
623 Things to avoid when using macros:
624
625 1) macros that affect control flow:
626
627 #define FOO(x) \
628 do { \
629 if (blah(x) < 0) \
630 return -EBUGGERED; \
631 } while(0)
632
633 is a _very_ bad idea. It looks like a function call but exits the "calling"
634 function; don't break the internal parsers of those who will read the code.
635
636 2) macros that depend on having a local variable with a magic name:
637
638 #define FOO(val) bar(index, val)
639
640 might look like a good thing, but it's confusing as hell when one reads the
641 code and it's prone to breakage from seemingly innocent changes.
642
643 3) macros with arguments that are used as l-values: FOO(x) = y; will
644 bite you if somebody e.g. turns FOO into an inline function.
645
646 4) forgetting about precedence: macros defining constants using expressions
647 must enclose the expression in parentheses. Beware of similar issues with
648 macros using parameters.
649
650 #define CONSTANT 0x4000
651 #define CONSTEXP (CONSTANT | 3)
652
653 The cpp manual deals with macros exhaustively. The gcc internals manual also
654 covers RTL which is used frequently with assembly language in the kernel.
655
656
657 Chapter 13: Printing kernel messages
658
659 Kernel developers like to be seen as literate. Do mind the spelling
660 of kernel messages to make a good impression. Do not use crippled
661 words like "dont"; use "do not" or "don't" instead. Make the messages
662 concise, clear, and unambiguous.
663
664 Kernel messages do not have to be terminated with a period.
665
666 Printing numbers in parentheses (%d) adds no value and should be avoided.
667
668 There are a number of driver model diagnostic macros in <linux/device.h>
669 which you should use to make sure messages are matched to the right device
670 and driver, and are tagged with the right level: dev_err(), dev_warn(),
671 dev_info(), and so forth. For messages that aren't associated with a
672 particular device, <linux/kernel.h> defines pr_debug() and pr_info().
673
674 Coming up with good debugging messages can be quite a challenge; and once
675 you have them, they can be a huge help for remote troubleshooting. Such
676 messages should be compiled out when the DEBUG symbol is not defined (that
677 is, by default they are not included). When you use dev_dbg() or pr_debug(),
678 that's automatic. Many subsystems have Kconfig options to turn on -DDEBUG.
679 A related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the
680 ones already enabled by DEBUG.
681
682
683 Chapter 14: Allocating memory
684
685 The kernel provides the following general purpose memory allocators:
686 kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API
687 documentation for further information about them.
688
689 The preferred form for passing a size of a struct is the following:
690
691 p = kmalloc(sizeof(*p), ...);
692
693 The alternative form where struct name is spelled out hurts readability and
694 introduces an opportunity for a bug when the pointer variable type is changed
695 but the corresponding sizeof that is passed to a memory allocator is not.
696
697 Casting the return value which is a void pointer is redundant. The conversion
698 from void pointer to any other pointer type is guaranteed by the C programming
699 language.
700
701
702 Chapter 15: The inline disease
703
704 There appears to be a common misperception that gcc has a magic "make me
705 faster" speedup option called "inline". While the use of inlines can be
706 appropriate (for example as a means of replacing macros, see Chapter 12), it
707 very often is not. Abundant use of the inline keyword leads to a much bigger
708 kernel, which in turn slows the system as a whole down, due to a bigger
709 icache footprint for the CPU and simply because there is less memory
710 available for the pagecache. Just think about it; a pagecache miss causes a
711 disk seek, which easily takes 5 miliseconds. There are a LOT of cpu cycles
712 that can go into these 5 miliseconds.
713
714 A reasonable rule of thumb is to not put inline at functions that have more
715 than 3 lines of code in them. An exception to this rule are the cases where
716 a parameter is known to be a compiletime constant, and as a result of this
717 constantness you *know* the compiler will be able to optimize most of your
718 function away at compile time. For a good example of this later case, see
719 the kmalloc() inline function.
720
721 Often people argue that adding inline to functions that are static and used
722 only once is always a win since there is no space tradeoff. While this is
723 technically correct, gcc is capable of inlining these automatically without
724 help, and the maintenance issue of removing the inline when a second user
725 appears outweighs the potential value of the hint that tells gcc to do
726 something it would have done anyway.
727
728
729 Chapter 16: Function return values and names
730
731 Functions can return values of many different kinds, and one of the
732 most common is a value indicating whether the function succeeded or
733 failed. Such a value can be represented as an error-code integer
734 (-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure,
735 non-zero = success).
736
737 Mixing up these two sorts of representations is a fertile source of
738 difficult-to-find bugs. If the C language included a strong distinction
739 between integers and booleans then the compiler would find these mistakes
740 for us... but it doesn't. To help prevent such bugs, always follow this
741 convention:
742
743 If the name of a function is an action or an imperative command,
744 the function should return an error-code integer. If the name
745 is a predicate, the function should return a "succeeded" boolean.
746
747 For example, "add work" is a command, and the add_work() function returns 0
748 for success or -EBUSY for failure. In the same way, "PCI device present" is
749 a predicate, and the pci_dev_present() function returns 1 if it succeeds in
750 finding a matching device or 0 if it doesn't.
751
752 All EXPORTed functions must respect this convention, and so should all
753 public functions. Private (static) functions need not, but it is
754 recommended that they do.
755
756 Functions whose return value is the actual result of a computation, rather
757 than an indication of whether the computation succeeded, are not subject to
758 this rule. Generally they indicate failure by returning some out-of-range
759 result. Typical examples would be functions that return pointers; they use
760 NULL or the ERR_PTR mechanism to report failure.
761
762
763 Chapter 17: Don't re-invent the kernel macros
764
765 The header file include/linux/kernel.h contains a number of macros that
766 you should use, rather than explicitly coding some variant of them yourself.
767 For example, if you need to calculate the length of an array, take advantage
768 of the macro
769
770 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
771
772 Similarly, if you need to calculate the size of some structure member, use
773
774 #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
775
776 There are also min() and max() macros that do strict type checking if you
777 need them. Feel free to peruse that header file to see what else is already
778 defined that you shouldn't reproduce in your code.
779
780
781 Chapter 18: Editor modelines and other cruft
782
783 Some editors can interpret configuration information embedded in source files,
784 indicated with special markers. For example, emacs interprets lines marked
785 like this:
786
787 -*- mode: c -*-
788
789 Or like this:
790
791 /*
792 Local Variables:
793 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
794 End:
795 */
796
797 Vim interprets markers that look like this:
798
799 /* vim:set sw=8 noet */
800
801 Do not include any of these in source files. People have their own personal
802 editor configurations, and your source files should not override them. This
803 includes markers for indentation and mode configuration. People may use their
804 own custom mode, or may have some other magic method for making indentation
805 work correctly.
806
807
808
809 Appendix I: References
810
811 The C Programming Language, Second Edition
812 by Brian W. Kernighan and Dennis M. Ritchie.
813 Prentice Hall, Inc., 1988.
814 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
815 URL: http://cm.bell-labs.com/cm/cs/cbook/
816
817 The Practice of Programming
818 by Brian W. Kernighan and Rob Pike.
819 Addison-Wesley, Inc., 1999.
820 ISBN 0-201-61586-X.
821 URL: http://cm.bell-labs.com/cm/cs/tpop/
822
823 GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
824 gcc internals and indent, all available from http://www.gnu.org/manual/
825
826 WG14 is the international standardization working group for the programming
827 language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
828
829 Kernel CodingStyle, by [email protected] at OLS 2002:
830 http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
831
832 --
833 Last updated on 2007-July-13.