doc: Explain use of common error variable names.

--

1 files changed, 24 insertions, 7 deletions

diff --git a/doc/HACKING b/doc/HACKING
index 11ae53b89..d2168d65b 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -74,7 +74,6 @@ do this after this scissor line:
 Note that such a comment will be removed if the git commit option
 =--cleanup=scissor= is used.
 
-
 ** License policy
 
   GnuPG is licensed under the GPLv3+ with some files under a mixed
@@ -131,12 +130,13 @@ Note that such a comment will be removed if the git commit option
   - Ignore signed/unsigned pointer mismatches
   - No arithmetic on void pointers; cast to char* first.
   - We use our own printf style functions like =es_printf=, and
-    =es_asprintf= which implement most C99 features with the exception
-    of =wchar_t= (which should anyway not be used).  Please always use
-    them and do not resort to those provided by libc.  The rationale
-    for using them is that we know that the format specifiers work on
-    all platforms and that we do not need to chase platform dependent
-    bugs.
+    =gpgrt_asprintf= (or the =es_asprintf= macro) which implement most
+    C99 features with the exception of =wchar_t= (which should anyway
+    not be used).  Please use them always and do not resort to those
+    provided by libc.  The rationale for using them is that we know
+    that the format specifiers work on all platforms and that we do
+    not need to chase platform dependent bugs.  Note also that in
+    gnupg asprintf is a macro already evaluating to gpgrt_asprintf.
   - It is common to have a label named "leave" for a function's
     cleanup and return code.  This helps with freeing memory and is a
     convenient location to set a breakpoint for debugging.
@@ -150,6 +150,23 @@ Note that such a comment will be removed if the git commit option
     end up in BSS.
   - Use --enable-maintainer-mode with configure.
 
+** Variable names
+
+  Follow the GNU standards.  Here are some conventions you may want to
+  stick to (do not rename existing "wrong" uses without a goog
+  reason).
+
+  - err :: This conveys an error code of type =gpg_error_t= which is
+           compatible to an =int=.  To compare such a variable to a
+           GPG_ERR_ constant, it is necessary to map the value like
+           this: =gpg_err_code(err)=.
+  - ec  :: This is used for a gpg-error code which has no source part
+           (=gpg_err_code_t=) and will eventually be used as input to
+           =gpg_err_make=.
+  - rc  :: Used for all kind of other errors; for example system
+           calls.  The value is not compatible with gpg-error.
+
+
 *** C99 language features
 
   In GnuPG 2.x, but *not in 1.4* and not in most libraries, a limited