[PATCH] Add section on function return values to CodingStyle

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