You are viewing a plain text version of this content. The canonical link for it is here.
Posted to c-commits@axis.apache.org by ro...@apache.org on 2026/01/23 13:54:32 UTC

(axis-axis2-c-core) 01/10: Clarify base64 encode functions return buffer size, not strlen (AXIS2C-976)

This is an automated email from the ASF dual-hosted git repository.

robertlazarski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/axis-axis2-c-core.git

commit 21965d97da5ccb08eedad9d2e8e5cfd0b15aec9c
Author: Robert Lazarski <ro...@gmail.com>
AuthorDate: Tue Jan 20 07:56:28 2026 -1000

    Clarify base64 encode functions return buffer size, not strlen (AXIS2C-976)
    
    The base64 encode functions intentionally return the total bytes written
    including the null terminator, which is suitable for buffer allocation.
    This differs from strlen() by one. Updated documentation to make this
    design choice explicit and prevent confusion.
    
    Co-Authored-By: Claude Opus 4.5 <no...@anthropic.com>
---
 util/include/axutil_base64.h | 30 ++++++++++++++++++------------
 util/src/base64.c            |  8 +++++++-
 2 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/util/include/axutil_base64.h b/util/include/axutil_base64.h
index d52e3afa3..d75d30caa 100644
--- a/util/include/axutil_base64.h
+++ b/util/include/axutil_base64.h
@@ -48,21 +48,25 @@ extern "C"
      */
 
     /*
-     * Given the length of an un-encrypted string, get the length of the
-     * encrypted string.
-     * @param len the length of an unencrypted string.
-     * @return the length of the string after it is encrypted
+     * Given the length of an un-encoded string, get the buffer size needed
+     * to hold the base64-encoded result.
+     * @param len the length of the plain text string to be encoded.
+     * @return the buffer size needed, including space for null terminator.
+     *         This is one more than strlen() would return on the encoded string.
+     *         Use this value for memory allocation: malloc(axutil_base64_encode_len(len))
      */
     AXIS2_EXTERN int AXIS2_CALL
     axutil_base64_encode_len(
         int len);
 
     /*
-     * Encode a text string using base64encoding.
-     * @param coded_dst The destination string for the encoded string.
+     * Encode a text string using base64 encoding.
+     * @param coded_dst The destination buffer for the encoded string.
+     *                  Must be at least axutil_base64_encode_len(len_plain_src) bytes.
      * @param plain_src The original string in plain text
      * @param len_plain_src The length of the plain text string
-     * @return the length of the encoded string
+     * @return the number of bytes written including null terminator.
+     *         This is one more than strlen(coded_dst) would return.
      */
     AXIS2_EXTERN int AXIS2_CALL
     axutil_base64_encode(
@@ -71,11 +75,13 @@ extern "C"
         int len_plain_src);
 
     /*
-     * Encode an EBCDIC string using base64encoding.
-     * @param coded_dst The destination string for the encoded string.
-     * @param plain_src The original string in plain text
-     * @param len_plain_src The length of the plain text string
-     * @return the length of the encoded string
+     * Encode binary data using base64 encoding.
+     * @param coded_dst The destination buffer for the encoded string.
+     *                  Must be at least axutil_base64_encode_len(len_plain_src) bytes.
+     * @param plain_src The binary data to encode
+     * @param len_plain_src The length of the binary data
+     * @return the number of bytes written including null terminator.
+     *         This is one more than strlen(coded_dst) would return.
      */
     AXIS2_EXTERN int AXIS2_CALL
     axutil_base64_encode_binary(
diff --git a/util/src/base64.c b/util/src/base64.c
index ba1a60585..85ea4cfea 100644
--- a/util/src/base64.c
+++ b/util/src/base64.c
@@ -239,6 +239,10 @@ AXIS2_EXTERN int AXIS2_CALL
 axutil_base64_encode_len(
     int len)
 {
+    /* Returns buffer size needed: base64 output size + 1 for null terminator.
+     * Base64 encodes 3 bytes into 4 characters, so output is ceil(len/3)*4.
+     * The +1 is for the null terminator - this returns allocation size, not strlen.
+     * See AXIS2C-976 for discussion of this design choice. */
     return ((len + 2) / 3 * 4) + 1;
 }
 
@@ -285,6 +289,7 @@ axutil_base64_encode(
     }
 
     *p++ = '\0';
+    /* Returns total bytes written including null terminator (allocation size, not strlen) */
     return p - encoded;
 #endif                          /* __OS400__ */
 }
@@ -326,6 +331,7 @@ axutil_base64_encode_binary(
     }
 
     *p++ = '\0';
+    /* Returns total bytes written including null terminator (allocation size, not strlen).
+     * We are sure that the difference lies within the int range. */
     return (int)(p - encoded);
-    /* We are sure that the difference lies within the int range */
 }