docs: mention potential leak in curl_slist_append

When a non-empty list is appended to, and used as the returnvalue,
the list pointer can leak in case of an allocation failure in the
curl_slist_append() call. This is correctly handled in curl code
usage but we weren't explicitly pointing it out in the API call
documentation. Fix by extending the RETURNVALUE manpage section
and example code.

Closes #3424
Reported-by: dnivras on github
Reviewed-by: Daniel Stenberg <daniel@haxx.se>

1 files changed, 14 insertions, 2 deletions

diff --git a/docs/libcurl/curl_slist_append.3 b/docs/libcurl/curl_slist_append.3
index 2d4e30527..a902b4754 100644
--- a/docs/libcurl/curl_slist_append.3
+++ b/docs/libcurl/curl_slist_append.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -39,17 +39,29 @@ The list should be freed again (after usage) with
 \fIcurl_slist_free_all(3)\fP.
 .SH RETURN VALUE
 A null pointer is returned if anything went wrong, otherwise the new list
-pointer is returned.
+pointer is returned. To avoid overwriting an existing non-empty list on
+failure, the new list should be returned to a temporary variable which can
+be tested for NULL before updating the original list pointer.
 .SH EXAMPLE
 .nf
 CURL *handle;
 struct curl_slist *slist=NULL;
+struct curl_slist *temp=NULL;
 
 slist = curl_slist_append(slist, "pragma:");
 
 if (slist == NULL)
   return -1;
 
+temp = curl_slist_append(slist, "Accept:")
+
+if (temp == NULL) {
+  curl_slist_free_all(slist);
+  return -1;
+}
+
+slist = temp;
+
 curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist);
 
 curl_easy_perform(handle);