r23796: main COPYING file for samba4, plus some formatting varients
[samba.git] / source / lib / talloc / talloc.3.xml
index 247bb28ed9f419f59f11c2f022be693e430a8cb6..ed7466c9ee8cd77aaf196c68b10792f8782f6ea5 100644 (file)
          It returns 0 on success and -1 on failure.
         </para>
     </refsect2>
+    <refsect2><title>size_t talloc_reference_count(const void *<emphasis role="italic">ptr</emphasis>);</title>
+        <para>
+         Return the number of references to the pointer.
+        </para>
+    </refsect2>
     <refsect2 id="talloc_set_name"><title>void talloc_set_name(const void *ptr, const char *fmt, ...);</title>
         <para>
          Each talloc pointer has a "name".  The name is used principally
         <para>
          The main use for names on pointer is for "talloc reports".  See
          <link
+         linkend="talloc_report"><quote>talloc_report_depth_cb()</quote></link>,
+         <link
+         linkend="talloc_report"><quote>talloc_report_depth_file()</quote></link>,
+         <link
+         linkend="talloc_report"><quote>talloc_report()</quote></link>
+         <link
          linkend="talloc_report"><quote>talloc_report()</quote></link>
          and <link
          linkend="talloc_report_full"><quote>talloc_report_full()</quote></link>
@@ -358,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
@@ -376,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
@@ -428,6 +449,45 @@ talloc_realloc(ctx, ptr, type, 0)  ==> talloc_free(ptr);</programlisting>
          has been called.
         </para>
     </refsect2>
+    <refsect2 id="talloc_report_depth_cb">
+     <funcsynopsis><funcprototype>
+      <funcdef>void <function>talloc_report_depth_cb</function></funcdef>
+      <paramdef><parameter>const void *ptr</parameter></paramdef>
+      <paramdef><parameter>int depth</parameter></paramdef>
+      <paramdef><parameter>int max_depth</parameter></paramdef>
+      <paramdef><parameter>void (*callback)(const void *ptr, int depth, int max_depth, int is_ref, void *priv)</parameter></paramdef>
+      <paramdef><parameter>void *priv</parameter></paramdef>
+     </funcprototype></funcsynopsis>
+        <para>
+         This provides a more flexible reports than talloc_report(). It
+         will recursively call the callback for the entire tree of memory
+         referenced by the pointer. References in the tree are passed with
+         <emphasis role="italic">is_ref = 1</emphasis> and the pointer that is referenced.
+        </para>
+        <para>
+         You can pass NULL for the pointer, in which case a report is
+         printed for the top level memory context, but only if
+         talloc_enable_leak_report() or talloc_enable_leak_report_full()
+         has been called.
+        </para>
+        <para>
+         The recursion is stopped when depth >= max_depth.
+         max_depth = -1 means only stop at leaf nodes.
+        </para>
+    </refsect2>
+    <refsect2 id="talloc_report_depth_file">
+     <funcsynopsis><funcprototype>
+      <funcdef>void <function>talloc_report_depth_file</function></funcdef>
+      <paramdef><parameter>const void *ptr</parameter></paramdef>
+      <paramdef><parameter>int depth</parameter></paramdef>
+      <paramdef><parameter>int max_depth</parameter></paramdef>
+      <paramdef><parameter>FILE *f</parameter></paramdef>
+     </funcprototype></funcsynopsis>
+        <para>
+         This provides a more flexible reports than talloc_report(). It
+         will let you specify the depth and max_depth.
+        </para>
+    </refsect2>
     <refsect2 id="talloc_enable_leak_report"><title>void talloc_enable_leak_report(void);</title>
         <para>
          This enables calling of talloc_report(NULL, stderr) when the
@@ -523,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>
@@ -545,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>
@@ -640,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>