From 6dafd0566786a417cfe1131ab804b162fcc79d15 Mon Sep 17 00:00:00 2001 From: "Shawn O. Pearce" Date: Fri, 31 Oct 2008 18:30:22 -0700 Subject: [PATCH] Document the return NULL style of calling convention Signed-off-by: Shawn O. Pearce --- CONVENTIONS | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CONVENTIONS b/CONVENTIONS index e3c672819..ea9fa2b55 100644 --- a/CONVENTIONS +++ b/CONVENTIONS @@ -57,6 +57,18 @@ This permits common POSIX result testing: abort("odb open failed"); ---- +Functions returning a pointer may return NULL instead of an int +if there is only one type of failure (ENOMEM). + +Functions returning a pointer may also return NULL if the common +case needed by the application is strictly success/failure and a +(possibly slower) function exists that the caller can use to get +more detailed information. Parsing common data structures from +on-disk formats is a good example of this pattern; in general a +"corrupt" entity can be treated as though it does not exist but +a more sophisticated "fsck" support function can report how the +entity is malformed. + Documentation Fomatting -----------------------