Lines Matching +full:use +full:- +full:case
19 --------------
31 Now, some people will claim that having 8-character indentations makes
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
42 to align the ``switch`` and its subordinate ``case`` labels in the same column
43 instead of ``double-indenting`` the ``case`` labels. E.g.:
45 .. code-block:: c
48 case 'G':
49 case 'g':
52 case 'M':
53 case 'm':
56 case 'K':
57 case 'k':
67 .. code-block:: c
72 Don't use commas to avoid using braces:
74 .. code-block:: c
81 .. code-block:: c
99 ----------------------------------
116 However, never break user-visible strings such as printk messages because
121 ----------------------------
129 .. code-block:: c
135 This applies to all non-function statement blocks (if, switch, for,
138 .. code-block:: c
141 case KOBJ_ADD:
143 case KOBJ_REMOVE:
145 case KOBJ_CHANGE:
151 However, there is one special case, namely functions: they have the
154 .. code-block:: c
162 is ... well ... inconsistent, but all right-thinking people know that
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
214 statement; in the latter case use braces in both branches:
216 .. code-block:: c
225 Also, use braces when a loop contains more than a single simple statement:
227 .. code-block:: c
237 Linux kernel style for use of spaces depends (mostly) on
238 function-versus-keyword usage. Use a space after (most) keywords. The
244 So use a space after these keywords::
246 if, switch, case, for, do, while
250 .. code-block:: c
258 .. code-block:: c
264 preferred use of ``*`` is adjacent to the data name or function name and not
267 .. code-block:: c
274 Use one space around (on each side of) most binary and ternary operators,
277 = + - < > * / % | & ^ <= >= == != ? :
281 & * + - ~ ! sizeof typeof alignof __attribute__ defined
285 ++ --
289 ++ --
291 and no space around the ``.`` and ``->`` structure member operators.
307 ---------
310 Unlike Modula-2 and Pascal programmers, C programmers do not use cute
315 HOWEVER, while mixed-case names are frowned upon, descriptive names for
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
335 problem, which is called the function-growth-hormone-imbalance syndrome.
360 -----------
362 Please don't use things like ``vps_t``.
363 It's a **mistake** to use typedef for structures and pointers. When you see a
365 .. code-block:: c
373 .. code-block:: c
402 Again - there needs to be a **reason** for this. If something is
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.
419 some people object to their use anyway.
421 Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their
423 permitted -- although they are not mandatory in new code of your
429 (e) Types safe for use in userspace.
432 require C99 types and cannot use the ``u32`` form above. Thus, we
433 use __u32 and similar types in all structures which are shared
437 EVER use a typedef unless you can clearly match one of those rules.
444 ------------
453 case-statement, where you have to do lots of small things for a lot of
457 less-than-gifted first-year high-school student might not even
459 maximum limits all the more closely. Use helper functions with
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
475 .. code-block:: c
490 Do not use the ``extern`` keyword with function declarations as this makes
494 <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.…
502 - storage class (below, ``static __always_inline``, noting that ``__always_inline``
504 - storage class attributes (here, ``__init`` -- i.e. section declarations, but also
506 - return type (here, ``void *``)
507 - return type attributes (here, ``__must_check``)
508 - function name (here, ``action``)
509 - function parameters (here, ``(enum magic value, size_t size, u8 count, char *fmt, ...)``,
511 - function parameter attributes (here, ``__printf(4, 5)``)
512 - function behavior attributes (here, ``__malloc``)
527 -----------------------------------
538 Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to
544 - unconditional statements are easier to understand and follow
545 - nesting is reduced
546 - errors by not updating individual exit points when making
548 - saves the compiler work to optimize redundant code away ;)
550 .. code-block:: c
559 return -ENOMEM;
576 .. code-block:: c
579 kfree(foo->bar);
587 .. code-block:: c
590 kfree(foo->bar);
599 -------------
601 Comments are good, but there is also a danger of over-commenting. NEVER
615 When commenting the kernel API functions, please use the kernel-doc format.
616 See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
617 ``scripts/kernel-doc`` for details.
619 The preferred style for long (multi-line) comments is:
621 .. code-block:: c
624 * This is the preferred style for multi-line
626 * Please use it consistently.
629 * with beginning and ending almost-blank lines.
632 For files in net/ and drivers/net/ the preferred style for long (multi-line)
635 .. code-block:: c
641 * but there is no initial almost-blank line.
645 types. To this end, use just one data declaration per line (no commas for
647 item, explaining its use.
651 ---------------------------
653 That's OK, we all do. You've probably been told by your long-time Unix
657 typing - an infinite number of monkeys typing into GNU emacs would never
660 So, you can either get rid of GNU emacs, or change it to use saner
663 .. code-block:: none
665 (defun c-lineup-arglist-tabs-only (ignored)
667 (let* ((anchor (c-langelem-pos c-syntactic-element))
668 (column (c-langelem-2nd-pos c-syntactic-element))
669 (offset (- (1+ column) anchor))
670 (steps (floor offset c-basic-offset)))
672 c-basic-offset)))
674 (dir-locals-set-class-variables
675 'linux-kernel
676 '((c-mode . (
677 (c-basic-offset . 8)
678 (c-label-minimum-indentation . 0)
679 (c-offsets-alist . (
680 (arglist-close . c-lineup-arglist-tabs-only)
681 (arglist-cont-nonempty .
682 (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
683 (arglist-intro . +)
684 (brace-list-intro . +)
685 (c . c-lineup-C-comments)
686 (case-label . 0)
687 (comment-intro . c-lineup-comment)
688 (cpp-define-intro . +)
689 (cpp-macro . -1000)
690 (cpp-macro-cont . +)
691 (defun-block-intro . +)
692 (else-clause . 0)
693 (func-decl-cont . +)
695 (inher-cont . c-lineup-multi-inher)
696 (knr-argdecl-intro . 0)
697 (label . -1000)
699 (statement-block-intro . +)
700 (statement-case-intro . +)
701 (statement-cont . +)
704 (indent-tabs-mode . t)
705 (show-trailing-whitespace . t)
708 (dir-locals-set-directory-class
709 (expand-file-name "~/src/linux-trees")
710 'linux-kernel)
713 files below ``~/src/linux-trees``.
716 everything is lost: use ``indent``.
718 Now, again, GNU indent has the same brain-dead settings that GNU emacs
723 options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use
727 re-formatting you may want to take a look at the man page. But
730 Note that you can also use the ``clang-format`` tool to help you with
731 these rules, to quickly re-format parts of your code automatically,
735 See the file :ref:`Documentation/process/clang-format.rst <clangformat>`
740 -------------------------------
753 logging of avc messages output). Does not do system-call
765 Documentation/kbuild/kconfig-language.rst.
769 -------------------
771 Data structures that have visibility outside the single-threaded
778 users to have access to the data structure in parallel - and not having
792 Examples of this kind of ``multi-level-reference-counting`` can be found in
801 -------------------------
805 .. code-block:: c
812 may be named in lower case.
816 Macros with multiple statements should be enclosed in a do - while block:
818 .. code-block:: c
830 .. code-block:: c
835 return -EBUGGERED; \
843 .. code-block:: c
850 3) macros with arguments that are used as l-values: FOO(x) = y; will
857 .. code-block:: c
865 .. code-block:: c
874 ret is a common name for a local variable - __foo_ret is less likely
882 ----------------------------
885 of kernel messages to make a good impression. Do not use incorrect
886 contractions like ``dont``; use ``do not`` or ``don't`` instead. Make the
894 which you should use to make sure messages are matched to the right device
902 debug message printing is handled differently than printing other non-debug
909 Many subsystems have Kconfig debug options to turn on -DDEBUG in the
912 already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
917 ---------------------
922 about them. :ref:`Documentation/core-api/memory-allocation.rst
927 .. code-block:: c
941 .. code-block:: c
947 .. code-block:: c
955 without __GFP_NOWARN so there is no use in emitting an additional failure
959 ----------------------
962 faster" speedup option called ``inline``. While the use of inlines can be
964 very often is not. Abundant use of the inline keyword leads to a much bigger
975 function away at compile time. For a good example of this later case, see
987 ------------------------------------
991 failed. Such a value can be represented as an error-code integer
992 (-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
993 non-zero = success).
996 difficult-to-find bugs. If the C language included a strong distinction
1002 the function should return an error-code integer. If the name
1006 for success or -EBUSY for failure. In the same way, ``PCI device present`` is
1016 this rule. Generally they indicate failure by returning some out-of-range
1017 result. Typical examples would be functions that return pointers; they use
1022 --------------
1032 bool function return types and stack variables are always fine to use whenever
1033 appropriate. Use of bool is encouraged to improve readability and is often a
1036 Do not use bool if cache line layout or size of the value matters, as its size
1038 optimized for alignment and size should not use bool.
1046 readable alternative if the call-sites have naked true/false constants.
1048 Otherwise limited use of bool in structures and arguments can improve
1051 18) Don't re-invent the kernel macros
1052 -------------------------------------
1055 you should use, rather than explicitly coding some variant of them yourself.
1059 .. code-block:: c
1063 Similarly, if you need to calculate the size of some structure member, use
1065 .. code-block:: c
1067 #define sizeof_field(t, f) (sizeof(((t*)0)->f))
1075 ------------------------------------
1081 .. code-block:: c
1083 -*- mode: c -*-
1087 .. code-block:: c
1091 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
1097 .. code-block:: c
1103 includes markers for indentation and mode configuration. People may use their
1109 -------------------
1111 In architecture-specific code, you may need to use inline assembly to interface
1113 However, don't use inline assembly gratuitously when C can do the job. You can
1118 that inline assembly can use C parameters.
1120 Large, non-trivial assembly functions should go in .S files, with corresponding
1122 functions should use ``asmlinkage``.
1133 .. code-block:: c
1141 ---------------------------
1143 Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
1145 use such conditionals in a header file defining functions for use in those .c
1146 files, providing no-op stub versions in the #else case, and then call those
1162 Within code, where possible, use the IS_ENABLED macro to convert a Kconfig
1163 symbol into a C boolean expression, and use it in a normal C conditional:
1165 .. code-block:: c
1171 The compiler will constant-fold the conditional away, and include or exclude
1175 references, etc). Thus, you still have to use an #ifdef if the code inside the
1178 At the end of any non-trivial #if or #ifdef block (more than a few lines),
1182 .. code-block:: c
1190 ---------------------------
1202 Use WARN() rather than BUG()
1206 BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably
1211 internal corruptions with no way of continuing may still use BUG(), but need
1214 Use WARN_ON_ONCE() rather than WARN() or WARN_ON()
1226 WARN*() is intended for unexpected, this-should-never-happen situations.
1228 during normal operation. These are not pre- or post-condition asserts, for
1239 panic_on_warn users is not a valid reason to avoid the judicious use
1245 Use BUILD_BUG_ON() for compile-time assertions
1248 The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a
1249 compile-time assertion that has no effect at runtime.
1252 ----------------------
1257 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
1261 Addison-Wesley, Inc., 1999.
1262 ISBN 0-201-61586-X.
1264 GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
1268 language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
1270 Kernel :ref:`process/coding-style.rst <codingstyle>`, by greg@kroah.com at OLS 2002: