The patch titled
Add section on function return values to CodingStyle
has been removed from the -mm tree. Its filename is
add-section-on-function-return-values-to-codingstyle.patch
This patch was dropped because it was merged into mainline or a subsystem tree
------------------------------------------------------
Subject: Add section on function return values to CodingStyle
From: Alan Stern <stern@xxxxxxxxxxxxxxxxxxx>
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@xxxxxxxxxxxxxxxxxxx>
Signed-off-by: Andrew Morton <akpm@xxxxxxxx>
---
Documentation/CodingStyle | 34 ++++++++++++++++++++++++++++++++++
1 file changed, 34 insertions(+)
diff -puN Documentation/CodingStyle~add-section-on-function-return-values-to-codingstyle Documentation/CodingStyle
--- a/Documentation/CodingStyle~add-section-on-function-return-values-to-codingstyle
+++ a/Documentation/CodingStyle
@@ -532,6 +532,40 @@ appears outweighs the potential value of
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
_
Patches currently in -mm which might be from stern@xxxxxxxxxxxxxxxxxxx are
origin.patch
block-layer-early-detection-of-medium-not-present.patch
scsi-core-and-sd-early-detection-of-medium-not-present.patch
sd-early-detection-of-medium-not-present.patch
scsi-early-detection-of-medium-not-present-updated.patch
add-srcu-based-notifier-chains.patch
srcu-report-out-of-memory-errors.patch
srcu-report-out-of-memory-errors-fixlet.patch
cpufreq-make-the-transition_notifier-chain-use-srcu.patch
-
To unsubscribe from this list: send the line "unsubscribe mm-commits" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
