[PATCH] apr_pstrndup() doc tweak

[Jeff Trawick <tr...@gmail.com>]

Context: Code review of a third-party Apache module related
coincidentally to chronic memory corruption problems found a blunder
in code ported from Apache 1.3 to Apache 2.0+APR.  It assumed that
apr_pstrndup(), like ap_pstrndup(), always allocated n+1 bytes from
the pool (i.e., it actually reused n+1 bytes of the returned string).
But the two functions differ in that respect, and apr_pstrndup()
documentation isn't as explicit as it could be.

Concerns with the following tweaks, or better ideas?

Index: include/apr_strings.h
===================================================================
--- include/apr_strings.h       (revision 441474)
+++ include/apr_strings.h       (working copy)
@@ -109,12 +109,14 @@
 APR_DECLARE(char *) apr_pstrmemdup(apr_pool_t *p, const char *s, apr_size_t n);

 /**
- * duplicate the first n characters of a string into memory allocated
+ * duplicate at most n characters of a string into memory allocated
  * out of a pool; the new string will be null-terminated
  * @param p The pool to allocate out of
  * @param s The string to duplicate
- * @param n The number of characters to duplicate
+ * @param n The maximum number of characters to duplicate
  * @return The new string
+ * @remark The amount of memory allocated from the pool is the length
+ *         of the returned string with null termination.
  */
 APR_DECLARE(char *) apr_pstrndup(apr_pool_t *p, const char *s, apr_size_t n);

Re: [PATCH] apr_pstrndup() doc tweak

[Joe Orton <jo...@redhat.com>]

On Tue, Oct 31, 2006 at 07:25:48AM -0500, Jeff Trawick wrote:
> Context: Code review of a third-party Apache module related
> coincidentally to chronic memory corruption problems found a blunder
> in code ported from Apache 1.3 to Apache 2.0+APR.  It assumed that
> apr_pstrndup(), like ap_pstrndup(), always allocated n+1 bytes from
> the pool (i.e., it actually reused n+1 bytes of the returned string).

Ouch!

> But the two functions differ in that respect, and apr_pstrndup()
> documentation isn't as explicit as it could be.
>
> Concerns with the following tweaks, or better ideas?

My pet nit, NUL != NULL... maybe have the remark:

"The amount of memory allocated from the pool is the length of the
returned string including the NUL terminator"

and may as well capitalise that Duplicate at the beginning :)

joe