document the newly-repaired-and-rejuvinated Util_snprintf() function

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

1 files changed, 136 insertions, 5 deletions

diff --git a/doc/ReferenceManual/UtilReference.tex b/doc/ReferenceManual/UtilReference.tex
index ce04eff2..3190dfca 100644
--- a/doc/ReferenceManual/UtilReference.tex
+++ b/doc/ReferenceManual/UtilReference.tex
@@ -33,10 +33,15 @@ Here the functions are listed alphabetically within each section.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-%% comment this whole section out until it's non-empty
-%%\section{Miscellaneous Functions}
-%%
-%%\begin{Lentry}
+\section{Miscellaneous Functions}
+
+\begin{Lentry}
+
+\item[\code{Util\_snprintf}]
+     [\pageref{Util-snprintf}]
+
+\item[\code{Util\_vsnprintf}]
+     [\pageref{Util-vsnprintf}]
 
 %%\item[\code{Util\_asprintf}]
 %%     [\pageref{Util-asprintf}]
@@ -143,7 +148,7 @@ Here the functions are listed alphabetically within each section.
 %%\item[\code{Util\_StringListNext}]
 %%     [\pageref{Util-StringListNext}]
 
-%%\end{Lentry}
+\end{Lentry}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -329,6 +334,132 @@ a copy of a specified C-style null-terminated character string
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+\chapter{Full Descriptions of Miscellaneous Functions}
+
+\begin{FunctionDescription}{Util\_sprintf}
+\label{Util-snprintf}
+Safely format data into a caller-supplied buffer.
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_String.h"
+int count = Util_snprintf(char* buffer, size_t size, const char* format, ...)
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{result\_len}
+The number of characters (not including the trailing NUL) that would
+have been stored in the destination string if \verb|size| had been infinite.
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{buffer}
+A non-NULL pointer to the (caller-provided) buffer.
+\end{Parameter}
+\begin{Parameter}{size}
+The size of the buffer pointed to by \verb|buffer|.
+\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}
+C99 defines, and many systems provide, a C library function \verb|snprintf()|,
+which safely formats data into a caller-supplied buffer.  However, a few
+systems don't provide this,%%%
+\footnote{%%%
+	 There's also a related API \texttt{sprintf()}.
+	 Don't use it -- it almost guarantees buffer
+	 overflows.
+	 }%%%
+{} so Cactus provides its own version, \verb|Util_snprintf()|.%%%
+\footnote{%%%
+	 Contrary to the usual Cactus convention, the
+	 ``\texttt{s}'' in ``\texttt{Util\_snprintf}''
+	 is in \emph{lower} case, not upper case.
+	 }%%%
+
+The interpretation of \verb|format| is the same as that of \verb|printf()|.
+See the \verb|printf()| documentation on your favorite computer system
+(notably, on any Unix system, type ``\verb|man printf|'') for lots and lots
+of details.
+
+\verb|Util_snprintf()| stores at most \verb|size| characters
+in the destination buffer; the last character it stores is always
+the terminating NUL character.  If \verb|result_len >= size| then
+the destination string was truncated to fit into the destination buffer.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{snprintf()}
+Standard 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}
+
+\begin{ErrorSection}
+\begin{Error}{$< \texttt{0}$}
+Some sort of error occured.  It's indeterminate what (if anything)
+has been stored in the destination buffer.
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_String.h"
+
+/* some values to be formatted */
+char   c = '@';
+int    i = 42;
+double d = 3.14159265358979323846;
+const char s[] = "this is a string to format";
+
+int len;
+#define N_BUFFER	100
+char buffer[N_BUFFER];
+
+/* safely format the values into the buffer */
+snprintf(buffer, N_BUFFER,
+         "values are c='%c' i=%d d=%g s=\"%s\"",
+         c, i, d, s);
+
+/*
+ * same as above example, but now explicitly check for the output
+ * being truncated due to the buffer being too small
+ */
+const int len = snprintf(buffer, N_BUFFER,
+                         "values are c='%c' i=%d d=%g s=\"%s\"",
+                         c, i, d, s);
+if (len >= N_BUFFER)
+        {
+        /*
+         * output was truncated (i.e. buffer was too small)
+         * ( buffer  probably doesn't have all the information we wanted
+         * but the code is still "safe", in the sense that it's still
+         * NUL-terminated, and no buffer-overflow has occured)
+         */
+        }
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \chapter{Full Descriptions of String Functions}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%