diff options
author | Alan Stern <stern@rowland.harvard.edu> | 2006-09-29 09:01:21 (GMT) |
---|---|---|
committer | Linus Torvalds <torvalds@g5.osdl.org> | 2006-09-29 16:18:22 (GMT) |
commit | c16a02d6f5fcfe05dc6fd40aa80a8e1d055300db (patch) | |
tree | 9335cbe024a12723395a92f5aeca7111700a0766 /Documentation | |
parent | fdf8cb0909b531f9ae8f9b9d7e4eb35ba3505f07 (diff) | |
download | linux-fsl-qoriq-c16a02d6f5fcfe05dc6fd40aa80a8e1d055300db.tar.xz |
[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/CodingStyle | 34 |
1 files changed, 34 insertions, 0 deletions
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 6d2412e..29c1896 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -532,6 +532,40 @@ appears outweighs the potential value of the hint that tells gcc to do something it would have done anyway. + Chapter 16: Function return values and names + +Functions can return values of many different kinds, and one of the +most common is a value indicating whether the function succeeded or +failed. Such a value can be represented as an error-code integer +(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure, +non-zero = success). + +Mixing up these two sorts of representations is a fertile source of +difficult-to-find bugs. If the C language included a strong distinction +between integers and booleans then the compiler would find these mistakes +for us... but it doesn't. To help prevent such bugs, always follow this +convention: + + If the name of a function is an action or an imperative command, + the function should return an error-code integer. If the name + is a predicate, the function should return a "succeeded" boolean. + +For example, "add work" is a command, and the add_work() function returns 0 +for success or -EBUSY for failure. In the same way, "PCI device present" is +a predicate, and the pci_dev_present() function returns 1 if it succeeds in +finding a matching device or 0 if it doesn't. + +All EXPORTed functions must respect this convention, and so should all +public functions. Private (static) functions need not, but it is +recommended that they do. + +Functions whose return value is the actual result of a computation, rather +than an indication of whether the computation succeeded, are not subject to +this rule. Generally they indicate failure by returning some out-of-range +result. Typical examples would be functions that return pointers; they use +NULL or the ERR_PTR mechanism to report failure. + + Appendix I: References |