(Dynamic Output): Document the return value of asprintf. Also make the asprintf/snprintf examples a little better (check for some error returns).

manual/stdio.texi

@@ -1613,6 +1613,9 @@ make_message (char *name, char *value)
   int nchars;
 @end group
 @group
+  if (buffer == NULL)
+    return NULL;
+
  /* @r{Try to print in the allocated space.} */
   nchars = snprintf (buffer, size, "value of %s is %s",
                      name, value);
@@ -1624,9 +1627,10 @@ make_message (char *name, char *value)
          how much space is needed.} */
       buffer = (char *) xrealloc (buffer, nchars + 1);
 
-      /* @r{Try again.} */
-      snprintf (buffer, size, "value of %s is %s",
-                name, value);
+      if (buffer != NULL)
+        /* @r{Try again.} */
+        snprintf (buffer, size, "value of %s is %s",
+                  name, value);
     @}
   /* @r{The last call worked, return the string.} */
   return buffer;
@@ -1659,6 +1663,10 @@ buffer you allocate in advance.  The @var{ptr} argument should be the
 address of a @code{char *} object, and @code{asprintf} stores a pointer
 to the newly allocated string at that location.
 
+The return value is the number of characters allocated for the buffer, or
+less than zero if an error occured. Usually this means that the buffer
+could not be allocated.
+
 Here is how to use @code{asprintf} to get the same result as the
 @code{snprintf} example, but more easily:
 
@@ -1669,7 +1677,8 @@ char *
 make_message (char *name, char *value)
 @{
   char *result;
-  asprintf (&result, "value of %s is %s", name, value);
+  if (asprintf (&result, "value of %s is %s", name, value) < 0)
+    return NULL;
   return result;
 @}
 @end smallexample
@@ -3084,7 +3093,7 @@ For more information about the descriptor-level I/O functions, see
 @node Error Recovery
 @section Recovering from errors
 
-You may explicitly clear the error and EOF flags with the @code{clearerr} 
+You may explicitly clear the error and EOF flags with the @code{clearerr}
 function.
 
 @comment stdio.h
@@ -3112,7 +3121,7 @@ always fail again in the same way.  So usually it is best to give up and
 report the error to the user, rather than install complicated recovery
 logic.
 
-One important exception is @code{EINTR} (@pxref{Interrupted Primitives}). 
+One important exception is @code{EINTR} (@pxref{Interrupted Primitives}).
 Many stream I/O implementations will treat it as an ordinary error, which
 can be quite inconvenient.  You can avoid this hassle by installing all
 signals with the @code{SA_RESTART} flag.