r23796: main COPYING file for samba4, plus some formatting varients
[samba.git] / source / lib / talloc / talloc.3.xml
index a448e8d9784d8c26858036fadf2bb71949ddef04..ed7466c9ee8cd77aaf196c68b10792f8782f6ea5 100644 (file)
@@ -369,7 +369,7 @@ talloc_realloc(ctx, ptr, type, 0)  ==> talloc_free(ptr);</programlisting>
          known so the type-safe talloc_realloc() cannot be used.
         </para>
     </refsect2>
-    <refsect2><title>void *talloc_steal(const void *<emphasis role="italic">new_ctx</emphasis>, const void *<emphasis role="italic">ptr</emphasis>);</title>
+    <refsect2><title>TYPE *talloc_steal(const void *<emphasis role="italic">new_ctx</emphasis>, const TYPE *<emphasis role="italic">ptr</emphasis>);</title>
         <para>
          The talloc_steal() function changes the parent context of a
          talloc pointer.  It is typically used when the context that the
@@ -387,6 +387,16 @@ talloc_realloc(ctx, ptr, type, 0)  ==> talloc_free(ptr);</programlisting>
          data if you do this.
         </para>
     </refsect2>
+    <refsect2><title>TYPE *talloc_move(const void *<emphasis role="italic">new_ctx</emphasis>, TYPE **<emphasis role="italic">ptr</emphasis>);</title>
+        <para>
+         The talloc_move() function is a wrapper around
+         talloc_steal() which zeros the source pointer after the
+         move. This avoids a potential source of bugs where a
+         programmer leaves a pointer in two structures, and uses the
+         pointer from the old structure after it has been moved to a
+         new one.
+        </para>
+    </refsect2>
     <refsect2><title>size_t talloc_total_size(const void *<emphasis role="italic">ptr</emphasis>);</title>
         <para>
          The talloc_total_size() function returns the total size in bytes
@@ -573,11 +583,27 @@ if (ptr) memcpy(ptr, p, strlen(p)+1);</programlisting>
         </para>
         <programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
     </refsect2>
+    <refsect2><title>char *talloc_append_string(const void *<emphasis role="italic">t</emphasis>, char *<emphasis role="italic">orig</emphasis>, const char *<emphasis role="italic">append</emphasis>);</title>
+        <para>
+         The talloc_append_string() function appends the given formatted
+         string to the given string.
+        </para>
+        <para>
+         This function sets the name of the new pointer to the new
+         string. This is equivalent to:
+        </para>
+        <programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
+    </refsect2>
     <refsect2><title>char *talloc_vasprintf(const void *<emphasis role="italic">t</emphasis>, const char *<emphasis role="italic">fmt</emphasis>, va_list <emphasis role="italic">ap</emphasis>);</title>
         <para>
          The talloc_vasprintf() function is the talloc equivalent of the C
          library function vasprintf(3).
         </para>
+        <para>
+         This function sets the name of the new pointer to the new
+         string. This is equivalent to:
+        </para>
+        <programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
     </refsect2>
     <refsect2><title>char *talloc_asprintf(const void *<emphasis role="italic">t</emphasis>, const char *<emphasis role="italic">fmt</emphasis>, ...);</title>
         <para>
@@ -595,6 +621,11 @@ if (ptr) memcpy(ptr, p, strlen(p)+1);</programlisting>
          The talloc_asprintf_append() function appends the given formatted
          string to the given string.
         </para>
+        <para>
+         This function sets the name of the new pointer to the new
+         string. This is equivalent to:
+        </para>
+        <programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
     </refsect2>
     <refsect2><title>(type *)talloc_array(const void *ctx, type, uint_t count);</title>
         <para>
@@ -690,7 +721,7 @@ if (ptr) memcpy(ptr, p, strlen(p)+1);</programlisting>
     <para>
       This program is free software; you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
-      the Free Software Foundation; either version 2 of the License, or (at
+      the Free Software Foundation; either version 3 of the License, or (at
       your option) any later version.
     </para>
     <para>