From 95f3a1fe3cd09dbe33c3cdec5b1055033bc3a82a Mon Sep 17 00:00:00 2001
From: =?utf8?q?J=C3=A1n=20Tomko?= <jtomko@redhat.com>
Date: Fri, 18 Oct 2019 23:12:19 +0200
Subject: [PATCH] docs: hacking: mention GLib alternatives of libvirt string
 allocation macros
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

Document the preferred alternatives to existing libvirt macros for
allocating strings. These cannot be deleted just yet because
converting them will require a lot of work.

Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
---
 docs/hacking.html.in | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index 0f4587522d..d60ea5d120 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -1072,6 +1072,18 @@ BAD:
         <tr><td><code>VIR_FREE</code></td><td><code>g_free</code></td>
             <td><code>g_free</code> does not zero the pointer</td></tr>
     </table>
+
+    <p>String allocation macros and functions:</p>
+    <table class="top_table">
+        <tr><th>deprecated version</th><th>GLib version</th><th>Notes</th></tr>
+        <tr><td><code>VIR_STRDUP</code></td><td><code>g_strdup</code></td><td></td></tr>
+        <tr><td><code>VIR_STRNDUP</code></td><td><code>g_strndup</code></td><td></td></tr>
+        <tr><td><code>virAsprintf</code></td><td><code>g_strdup_printf</code></td><td></td></tr>
+        <tr><td><code>virVasprintf</code></td><td><code>g_strdup_vprint</code></td>
+            <td>use <code>g_vasprintf</code> if you really need to know the returned length</td></tr>
+        <tr><td><code>virStrerror</code></td><td><code>g_strerror</code></td>
+            <td>the error strings are cached globally so no need to free it</td></tr>
+    </table>
     </dl>
 
     <p>
-- 
2.47.2