Lines Matching +full:a +full:- +full:c
6 This is a short document describing the preferred coding style for the
12 First off, I'd suggest printing out a copy of the GNU coding standards,
13 and NOT read it. Burn them, it's a great symbolic gesture.
19 --------------
27 a block of control starts and ends. Especially when you've been looking
28 at your screen for 20 straight hours, you'll find it a lot easier to see
31 Now, some people will claim that having 8-character indentations makes
32 the code move too far to the right, and makes it hard to read on a
33 80-character terminal screen. The answer to that is that if you need
37 In short, 8-char indents make things easier to read, and have the added
41 The preferred way to ease multiple indentation levels in a switch statement is
43 instead of ``double-indenting`` the ``case`` labels. E.g.:
45 .. code-block:: c
64 Don't put multiple statements on a single line unless you have
67 .. code-block:: c
74 .. code-block:: c
81 .. code-block:: c
88 Don't put multiple assignments on a single line either. Kernel coding style
95 Get a decent editor and don't leave whitespace at the end of lines.
99 ----------------------------------
104 The preferred limit on the length of a single line is 80 columns.
111 are placed substantially to the right. A very commonly used style
112 is to align descendants to a function open parenthesis.
114 These same rules are applied to function headers with a long argument list.
116 However, never break user-visible strings such as printk messages because
121 ----------------------------
123 The other issue that always comes up in C styling is the placement of
129 .. code-block:: c
135 This applies to all non-function statement blocks (if, switch, for,
138 .. code-block:: c
154 .. code-block:: c
162 is ... well ... inconsistent, but all right-thinking people know that
163 (a) K&R are **right** and (b) K&R are right. Besides, functions are
164 special anyway (you can't nest them in C).
166 Note that the closing brace is empty on a line of its own, **except** in
167 the cases where it is followed by a continuation of the same statement,
168 ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
171 .. code-block:: c
174 body of do-loop
179 .. code-block:: c
191 Also, note that this brace-placement also minimizes the number of empty
193 supply of new-lines on your screen is not a renewable resource (think
194 25-line terminal screens here), you have more empty lines to put
197 Do not unnecessarily use braces where a single statement will do.
199 .. code-block:: c
206 .. code-block:: none
213 This does not apply if only one branch of a conditional statement is a single
216 .. code-block:: c
225 Also, use braces when a loop contains more than a single simple statement:
227 .. code-block:: c
238 function-versus-keyword usage. Use a space after (most) keywords. The
244 So use a space after these keywords::
250 .. code-block:: c
258 .. code-block:: c
263 When declaring pointer data or a function that returns a pointer type, the
267 .. code-block:: c
277 = + - < > * / % | & ^ <= >= == != ? :
281 & * + - ~ ! sizeof typeof alignof __attribute__ defined
285 ++ --
289 ++ --
291 and no space around the ``.`` and ``->`` structure member operators.
297 putting a line of code there, such as if you leave a blank line. As a result,
301 optionally strip the trailing whitespace for you; however, if applying a series
307 ---------
309 C is a Spartan language, and your naming conventions should follow suit.
310 Unlike Modula-2 and Pascal programmers, C programmers do not use cute
311 names like ThisVariableIsATemporaryCounter. A C programmer would call that
315 HOWEVER, while mixed-case names are frowned upon, descriptive names for
316 global variables are a must. To call a global function ``foo`` is a
320 have descriptive names, as do global functions. If you have a function
324 Encoding the type of a function into the name (so-called Hungarian
325 notation) is asinine - the compiler knows the types anyway and can check
330 Calling it ``loop_counter`` is non-productive, if there is no chance of it
331 being mis-understood. Similarly, ``tmp`` can be just about any type of
332 variable that is used to hold a temporary value.
335 problem, which is called the function-growth-hormone-imbalance syndrome.
353 Exceptions for introducing new usage is to maintain a userspace ABI/API,
360 -----------
363 It's a **mistake** to use typedef for structures and pointers. When you see a
365 .. code-block:: c
368 vps_t a;
373 .. code-block:: c
375 struct virtual_container *a;
377 you can actually tell what ``a`` is.
382 (a) totally opaque objects (where the typedef is actively used to **hide**
402 Again - there needs to be a **reason** for this. If something is
407 but if there is a clear reason for why it under certain circumstances
409 ``unsigned long``, then by all means go ahead and use a typedef.
411 (c) when you use sparse to literally create a **new** type for
412 type-checking.
417 Although it would only take a short amount of time for the eyes and
421 Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their
423 permitted -- although they are not mandatory in new code of your
437 EVER use a typedef unless you can clearly match one of those rules.
439 In general, a pointer, or a struct that has elements that can reasonably
440 be directly accessed should **never** be a typedef.
444 ------------
450 The maximum length of a function is inversely proportional to the
451 complexity and indentation level of that function. So, if you have a
453 case-statement, where you have to do lots of small things for a lot of
454 different cases, it's OK to have a longer function.
456 However, if you have a complex function, and you suspect that a
457 less-than-gifted first-year high-school student might not even
460 descriptive names (you can ask the compiler to in-line them if you think
461 it's performance-critical, and it will probably do a better job of it
465 shouldn't exceed 5-10, or you're doing something wrong. Re-think the
466 function, and split it into smaller pieces. A human brain can
475 .. code-block:: c
484 Although this is not required by the C language, it is preferred in Linux
485 because it is a simple way to add valuable information for the reader.
492 -----------------------------------
497 The goto statement comes in handy when a function exits from multiple
502 example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``.
503 Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to
509 - unconditional statements are easier to understand and follow
510 - nesting is reduced
511 - errors by not updating individual exit points when making
513 - saves the compiler work to optimize redundant code away ;)
515 .. code-block:: c
517 int fun(int a)
524 return -ENOMEM;
539 A common type of bug to be aware of is ``one err bugs`` which look like this:
541 .. code-block:: c
544 kfree(foo->bar);
552 .. code-block:: c
555 kfree(foo->bar);
564 -------------
566 Comments are good, but there is also a danger of over-commenting. NEVER
567 try to explain HOW your code works in a comment: it's much better to
568 write the code so that the **working** is obvious, and it's a waste of
572 Also, try to avoid putting comments inside a function body: if the
574 you should probably go back to chapter 6 for a while. You can make
580 When commenting the kernel API functions, please use the kernel-doc format.
581 See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
582 ``scripts/kernel-doc`` for details.
584 The preferred style for long (multi-line) comments is:
586 .. code-block:: c
589 * This is the preferred style for multi-line
593 * Description: A column of asterisks on the left side,
594 * with beginning and ending almost-blank lines.
597 For files in net/ and drivers/net/ the preferred style for long (multi-line)
598 comments is a little different.
600 .. code-block:: c
606 * but there is no initial almost-blank line.
611 multiple data declarations). This leaves you room for a small comment on each
615 9) You've made a mess of it
616 ---------------------------
618 That's OK, we all do. You've probably been told by your long-time Unix
619 user helper that ``GNU emacs`` automatically formats the C sources for
622 typing - an infinite number of monkeys typing into GNU emacs would never
623 make a good program).
628 .. code-block:: none
630 (defun c-lineup-arglist-tabs-only (ignored)
632 (let* ((anchor (c-langelem-pos c-syntactic-element))
633 (column (c-langelem-2nd-pos c-syntactic-element))
634 (offset (- (1+ column) anchor))
635 (steps (floor offset c-basic-offset)))
637 c-basic-offset)))
639 (dir-locals-set-class-variables
640 'linux-kernel
641 '((c-mode . (
642 (c-basic-offset . 8)
643 (c-label-minimum-indentation . 0)
644 (c-offsets-alist . (
645 (arglist-close . c-lineup-arglist-tabs-only)
646 (arglist-cont-nonempty .
647 (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
648 (arglist-intro . +)
649 (brace-list-intro . +)
650 (c . c-lineup-C-comments)
651 (case-label . 0)
652 (comment-intro . c-lineup-comment)
653 (cpp-define-intro . +)
654 (cpp-macro . -1000)
655 (cpp-macro-cont . +)
656 (defun-block-intro . +)
657 (else-clause . 0)
658 (func-decl-cont . +)
660 (inher-cont . c-lineup-multi-inher)
661 (knr-argdecl-intro . 0)
662 (label . -1000)
664 (statement-block-intro . +)
665 (statement-case-intro . +)
666 (statement-cont . +)
669 (indent-tabs-mode . t)
670 (show-trailing-whitespace . t)
673 (dir-locals-set-directory-class
674 (expand-file-name "~/src/linux-trees")
675 'linux-kernel)
677 This will make emacs go better with the kernel coding style for C
678 files below ``~/src/linux-trees``.
683 Now, again, GNU indent has the same brain-dead settings that GNU emacs
684 has, which is why you need to give it a few command line options.
688 options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use
691 ``indent`` has a lot of options, and especially when it comes to comment
692 re-formatting you may want to take a look at the man page. But
693 remember: ``indent`` is not a fix for bad programming.
695 Note that you can also use the ``clang-format`` tool to help you with
696 these rules, to quickly re-format parts of your code automatically,
700 See the file :ref:`Documentation/process/clang-format.rst <clangformat>`
705 -------------------------------
708 the indentation is somewhat different. Lines under a ``config`` definition
718 logging of avc messages output). Does not do system-call
730 Documentation/kbuild/kconfig-language.rst.
734 -------------------
736 Data structures that have visibility outside the single-threaded
743 users to have access to the data structure in parallel - and not having
745 because they slept or did something else for a while.
747 Note that locking is **not** a replacement for reference counting.
749 counting is a memory management technique. Usually both are needed, and
757 Examples of this kind of ``multi-level-reference-counting`` can be found in
762 have a reference count on it, you almost certainly have a bug.
766 -------------------------
770 .. code-block:: c
781 Macros with multiple statements should be enclosed in a do - while block:
783 .. code-block:: c
785 #define macrofun(a, b, c) \
787 if (a == 5) \
788 do_this(b, c); \
795 .. code-block:: c
800 return -EBUGGERED; \
803 is a **very** bad idea. It looks like a function call but exits the ``calling``
806 2) macros that depend on having a local variable with a magic name:
808 .. code-block:: c
812 might look like a good thing, but it's confusing as hell when one reads the
815 3) macros with arguments that are used as l-values: FOO(x) = y; will
822 .. code-block:: c
830 .. code-block:: c
839 ret is a common name for a local variable - __foo_ret is less likely
847 ----------------------------
850 of kernel messages to make a good impression. Do not use incorrect
854 Kernel messages do not have to be terminated with a period.
858 There are a number of driver model diagnostic macros in <linux/device.h>
861 dev_info(), and so forth. For messages that aren't associated with a
865 Coming up with good debugging messages can be quite a challenge; and once
866 you have them, they can be a huge help for remote troubleshooting. However
867 debug message printing is handled differently than printing other non-debug
871 and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to
874 Many subsystems have Kconfig debug options to turn on -DDEBUG in the
876 when a debug message should be unconditionally printed, such as if it is
877 already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
882 ---------------------
887 about them. :ref:`Documentation/core-api/memory-allocation.rst
890 The preferred form for passing a size of a struct is the following:
892 .. code-block:: c
897 introduces an opportunity for a bug when the pointer variable type is changed
898 but the corresponding sizeof that is passed to a memory allocator is not.
900 Casting the return value which is a void pointer is redundant. The conversion
901 from void pointer to any other pointer type is guaranteed by the C programming
906 .. code-block:: c
910 The preferred form for allocating a zeroed array is the following:
912 .. code-block:: c
919 These generic allocation functions all emit a stack dump on failure when used
924 ----------------------
926 There appears to be a common misperception that gcc has a magic "make me
928 appropriate (for example as a means of replacing macros, see Chapter 12), it
929 very often is not. Abundant use of the inline keyword leads to a much bigger
930 kernel, which in turn slows the system as a whole down, due to a bigger
932 available for the pagecache. Just think about it; a pagecache miss causes a
933 disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles
936 A reasonable rule of thumb is to not put inline at functions that have more
938 a parameter is known to be a compiletime constant, and as a result of this
940 function away at compile time. For a good example of this later case, see
944 only once is always a win since there is no space tradeoff. While this is
946 help, and the maintenance issue of removing the inline when a second user
952 ------------------------------------
955 most common is a value indicating whether the function succeeded or
956 failed. Such a value can be represented as an error-code integer
957 (-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
958 non-zero = success).
960 Mixing up these two sorts of representations is a fertile source of
961 difficult-to-find bugs. If the C language included a strong distinction
966 If the name of a function is an action or an imperative command,
967 the function should return an error-code integer. If the name
968 is a predicate, the function should return a "succeeded" boolean.
970 For example, ``add work`` is a command, and the add_work() function returns 0
971 for success or -EBUSY for failure. In the same way, ``PCI device present`` is
972 a predicate, and the pci_dev_present() function returns 1 if it succeeds in
973 finding a matching device or 0 if it doesn't.
979 Functions whose return value is the actual result of a computation, rather
981 this rule. Generally they indicate failure by returning some out-of-range
987 --------------
992 !! construction is not needed, which eliminates a class of bugs.
998 appropriate. Use of bool is encouraged to improve readability and is often a
1005 If a structure has many true/false values, consider consolidating them into a
1010 into a single bitwise 'flags' argument and 'flags' can often be a more
1011 readable alternative if the call-sites have naked true/false constants.
1016 18) Don't re-invent the kernel macros
1017 -------------------------------------
1019 The header file include/linux/kernel.h contains a number of macros that
1024 .. code-block:: c
1030 .. code-block:: c
1032 #define sizeof_field(t, f) (sizeof(((t*)0)->f))
1040 ------------------------------------
1046 .. code-block:: c
1048 -*- mode: c -*-
1052 .. code-block:: c
1056 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
1062 .. code-block:: c
1074 -------------------
1076 In architecture-specific code, you may need to use inline assembly to interface
1078 However, don't use inline assembly gratuitously when C can do the job. You can
1079 and should poke hardware from C when possible.
1083 that inline assembly can use C parameters.
1085 Large, non-trivial assembly functions should go in .S files, with corresponding
1086 C prototypes defined in C header files. The C prototypes for assembly
1093 When writing a single inline assembly statement containing multiple
1094 instructions, put each instruction on a separate line in a separate quoted
1098 .. code-block:: c
1106 ---------------------------
1108 Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
1110 use such conditionals in a header file defining functions for use in those .c
1111 files, providing no-op stub versions in the #else case, and then call those
1112 functions unconditionally from .c files. The compiler will avoid generating
1118 out part or all of the expression into a separate helper function and apply the
1121 If you have a function or variable which may potentially go unused in a
1124 a preprocessor conditional. (However, if a function or variable *always* goes
1127 Within code, where possible, use the IS_ENABLED macro to convert a Kconfig
1128 symbol into a C boolean expression, and use it in a normal C conditional:
1130 .. code-block:: c
1136 The compiler will constant-fold the conditional away, and include or exclude
1138 overhead. However, this approach still allows the C compiler to see the code
1143 At the end of any non-trivial #if or #ifdef block (more than a few lines),
1144 place a comment after the #endif on the same line, noting the conditional
1147 .. code-block:: c
1155 ----------------------
1157 The C Programming Language, Second Edition
1160 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
1164 Addison-Wesley, Inc., 1999.
1165 ISBN 0-201-61586-X.
1167 GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
1171 language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
1173 Kernel :ref:`process/coding-style.rst <codingstyle>`, by greg@kroah.com at OLS 2002: