From: Ján Tomko <jtomko@redhat.com>
Date: Fri, 18 Oct 2019 21:14:40 +0000 (+0200)
Subject: docs: hacking: document preferred strdup alternatives
X-Git-Tag: v5.9.0-rc1~71
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=da5c73352402df3a04fa2b2d205167486ff36403;p=thirdparty%2Flibvirt.git

docs: hacking: document preferred strdup alternatives

Recommend g_str(n)dup instead of VIR_STRDUP.

Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
---

diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index d60ea5d120..60dc2f18e3 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -1275,18 +1275,14 @@ BAD:
     </p>
 
 <pre>
-  VIR_STRDUP(char *dst, const char *src);
-  VIR_STRNDUP(char *dst, const char *src, size_t n);
+    dst = g_strdup(src);
+    dst = g_strndup(src, n);
 </pre>
     <p>
-      You should avoid using strdup or strndup directly as they do not report
-      out-of-memory error, and do not allow a NULL source. Use
-      VIR_STRDUP or VIR_STRNDUP macros instead, which return 0 for
-      NULL source, 1 for successful copy, and -1 for allocation
-      failure with the error already reported. In very
-      specific cases, when you don't want to report the out-of-memory error, you
-      can use VIR_STRDUP_QUIET or VIR_STRNDUP_QUIET, but such usage is very rare
-      and usually considered a flaw.
+      You should avoid using strdup or strndup directly as they do not handle
+      out-of-memory errors, and do not allow a NULL source.
+      Use <code>g_strdup</code> and <code>g_strndup</code> from GLib which
+      abort on OOM and handle NULL source by returning NULL.
     </p>
 
     <h2><a id="strbuf">Variable length string buffer</a></h2>