aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorAlan Stern <stern@rowland.harvard.edu>2006-09-29 05:01:21 -0400
committerLinus Torvalds <torvalds@g5.osdl.org>2006-09-29 12:18:22 -0400
commitc16a02d6f5fcfe05dc6fd40aa80a8e1d055300db (patch)
tree9335cbe024a12723395a92f5aeca7111700a0766 /Documentation
parentfdf8cb0909b531f9ae8f9b9d7e4eb35ba3505f07 (diff)
[PATCH] Add section on function return values to CodingStyle
This patch (as776) adds a new chapter to Documentation/CodingStyle, explaining the circumstances under which a function should return 0 for failure and non-zero for success as opposed to a negative error code for failure and 0 for success. Signed-off-by: Alan Stern <stern@rowland.harvard.edu> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/CodingStyle34
1 files changed, 34 insertions, 0 deletions
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 6d2412ec91ed..29c18966b050 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -532,6 +532,40 @@ appears outweighs the potential value of the hint that tells gcc to do
532something it would have done anyway. 532something it would have done anyway.
533 533
534 534
535 Chapter 16: Function return values and names
536
537Functions can return values of many different kinds, and one of the
538most common is a value indicating whether the function succeeded or
539failed. Such a value can be represented as an error-code integer
540(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure,
541non-zero = success).
542
543Mixing up these two sorts of representations is a fertile source of
544difficult-to-find bugs. If the C language included a strong distinction
545between integers and booleans then the compiler would find these mistakes
546for us... but it doesn't. To help prevent such bugs, always follow this
547convention:
548
549 If the name of a function is an action or an imperative command,
550 the function should return an error-code integer. If the name
551 is a predicate, the function should return a "succeeded" boolean.
552
553For example, "add work" is a command, and the add_work() function returns 0
554for success or -EBUSY for failure. In the same way, "PCI device present" is
555a predicate, and the pci_dev_present() function returns 1 if it succeeds in
556finding a matching device or 0 if it doesn't.
557
558All EXPORTed functions must respect this convention, and so should all
559public functions. Private (static) functions need not, but it is
560recommended that they do.
561
562Functions whose return value is the actual result of a computation, rather
563than an indication of whether the computation succeeded, are not subject to
564this rule. Generally they indicate failure by returning some out-of-range
565result. Typical examples would be functions that return pointers; they use
566NULL or the ERR_PTR mechanism to report failure.
567
568
535 569
536 Appendix I: References 570 Appendix I: References
537 571