add documentation for util_asprintf

git-svn-id: http://svn.cactuscode.org/flesh/trunk@5008 17b73243-c579-4c4c-a9d2-2d5706c11dac

1 files changed, 62 insertions, 2 deletions

diff --git a/doc/ReferenceManual/UtilReference.tex b/doc/ReferenceManual/UtilReference.tex
index 5f4a6171..70b9e82e 100644
--- a/doc/ReferenceManual/UtilReference.tex
+++ b/doc/ReferenceManual/UtilReference.tex
@@ -55,8 +55,10 @@ Safely format data into a caller-supplied buffer.
      [\pageref{Util-vsnprintf}]
 Safely format data into a caller-supplied buffer.
 
-%%\item[\code{Util\_asprintf}]
-%%     [\pageref{Util-asprintf}]
+\item[\code{Util\_asprintf}]
+     [\pageref{Util-asprintf}]
+Sprintf with memory allocation.  On input
+the buffer should point to a NULL area of memory.
 
 %%\item[\code{Util\_BinTreeFindNode}]
 %%     [\pageref{Util-BinTreeFindNode}]
@@ -661,6 +663,64 @@ to use \verb|va_list| objects.
 \end{SeeAlsoSection}
 \end{FunctionDescription}
 
+%Entering a function descrpition for Util\_asprintf
+\begin{FunctionDescription}{Util\_asprintf}
+\label{Util-asprintf}
+   Sprintf with memory allocation.  On input
+   the buffer should point to a NULL area of memory.
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_String.h"
+int count = Util_asprintf(char** buffer, const char* format,
+                           va_list arg)
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{buffer}
+Buffer to which to print the string.
+
+\verb|*buffer| should be NULL on entry.  The routine
+allocates the memory, so the previous contents of
+the pointer are lost.
+On exit the buffer size will be \verb|count+1| (i.e
+the length of the string plus the \verb|\0|).
+\end{Parameter}
+\begin{Parameter}{format}
+A (non-NULL pointer to a) C-style NUL-terminated string describing
+how to format any further arguments
+\end{Parameter}
+\begin{Parameter}{...}
+Zero or more further arguments, with types as specified by the
+\verb|format| argument.
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+This function is identical to \verb|sprintf()|, except that it allocates a
+buffer large enough to hold the output including the terminating null byte,
+and returns a pointer to it via the first argument. This pointer should be
+passed to \verb|free()| to release the allocated storage when it is no longer
+needed.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso2}{Util\_snprintf}{Util-snprintf}
+Similar function which takes user supplied buffer.
+\end{SeeAlso2}
+\begin{SeeAlso}{asprintf()}
+GNU/BSD C library function which this function tries to clone.
+\end{SeeAlso}
+\begin{SeeAlso}{sprintf()}
+Unsafe and dangerous C library function similar to \verb|snprintf()|,
+which doesn't check the buffer length.
+\end{SeeAlso}
+\end{SeeAlsoSection}
+\end{FunctionDescription}
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \chapter{Full Descriptions of String Functions}