Recommend pm_asprintf

git-svn-id: http://svn.code.sf.net/p/netpbm/code/trunk@2533 9d0c8265-081b-0410-96cb-a4ca84ce46f8

1 files changed, 10 insertions, 0 deletions

diff --git a/doc/Netpbm.programming b/doc/Netpbm.programming
index 549e0fb3..c4d38ed4 100644
--- a/doc/Netpbm.programming
+++ b/doc/Netpbm.programming
@@ -385,6 +385,16 @@ code.  Modular and structured above all.
   typically stored on the stack, is much more dangerous than overrunning a
   variable stored in the heap.
 
+* Use pm_asprintf() to compose strings, instead of sprintf(), strcat(), and
+  strcpy().  pm_asprintf() is essentially the same as GNU asprintf(), i.e.
+  sprintf(), except it dynamically allocates the result memory.  This
+  effortlessly makes it impossible to overrun the result buffer.  Use
+  pm_strfree() to free the result memory.  You usually need not worry about
+  the pathological case that there is no memory available for the result,
+  because in that case, pm_asprintf() returns a constant string "OUT OF MEMORY"
+  and in most cases, that won't cause a disaster - just incorrect behavior that
+  is reasonable in the face of such a pathological situation.
+
 * Do not use the "register" qualifier of a variable.