safestringlib: Fix documentation to match implementation

Although the documentation describes destination buffers being
filled with 0, that is only done when SAFECLIB_STR_NULL_SLACK
is defined. Make the source documentation conditional on the
same variable. Documentation outside the source is perpetually
at risk of being different than how any particular library is
built. A such, most documentation should assume that the
clearing is not done, as that is the least risk assumption.

Signed-off-by: Mark Rustad <[email protected]>

Author: MRustad

safeclib/stpcpy_s.c

@@ -46,10 +46,14 @@
  * DESCRIPTION
  *    The stpcpy_s function copies the string pointed to by src
  *    (including the terminating null character) into the array
+#ifdef SAFECLIB_STR_NULL_SLACK
  *    pointed to by dest. All elements following the terminating
  *    null character (if any) written by stpcpy_s in the array
  *    of dmax characters pointed to by dest are nulled when
  *    strcpy_s returns. The function returns a pointer to the
+#else
+ *    pointed to by dest. The function returns a pointer to the
+#endif // SAFECLIB_STR_NULL_SLACK
  *    end of the string in dest - that is to the null terminator
  *    of dest - upon return. If an error occurs, NULL is returned
  *    and err is set to the error encountered.
@@ -88,7 +92,12 @@
  *    Copying shall not take place between objects that overlap.
  *    If there is a runtime-constraint violation, then if dest
  *       is not a null pointer and destmax is greater than zero and
+#ifdef SAFECLIB_STR_NULL_SLACK
  *       not greater than RSIZE_MAX_STR, then stpcpy_s nulls dest.
+#else
+ *       not greater than RSIZE_MAX_STR, then stpcpy_s stores a 0
+ *       terminator in dest.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * RETURN VALUE
  *   a char pointer to the terminating null at the end of dest

safeclib/stpncpy_s.c

@@ -47,8 +47,10 @@
  *    The stpncpy_s function copies at most smax characters from the string
  *    pointed to by src, including the terminating null byte ('\0'), to the
  *    array pointed to by dest. Exactly smax characters are written at dest.
+#ifdef SAFECLIB_STR_NULL_SLACK
  *    If the length strlen_s(src) is smaller than smax, the remaining smax
  *    characters in the array pointed to by dest are filled with null bytes.
+#endif // SAFECLIB_STR_NULL_SLACK
  *    If the length strlen_s(src) is greater than or equal to smax, the string
  *    pointed to by dest will contain smax characters from src plus a null
  *    characters (dest will be null-terminated).
@@ -97,8 +99,13 @@
  *    If src and dest overlap, copying shall be stopped; destruction of src may have occurred.
  *    If there is a runtime-constraint violation, then:
  *       if dest is not a null pointer and dmax is greater than zero and
+#ifdef SAFECLIB_STR_NULL_SLACK
  *       not greater than RSIZE_MAX_STR, then stpncpy_s shall fill dest with nulls,
  *       if library was compiled with SAFECLIB_STR_NULL_SLACK.
+#else
+ *       not greater than RSIZE_MAX_STR, then stpncpy_s shall write a terminator
+ *       to the dest buffer.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * RETURN VALUE
  *   a char pointer to the terminating null at the end of dest

safeclib/strcat_s.c

@@ -62,8 +62,10 @@
  * INPUT PARAMETERS
  *    dest      pointer to string that will be extended by src
  *              if dmax allows. The string is null terminated.
+#ifdef SAFECLIB_STR_NULL_SLACK
  *              If the resulting concatenated string is less
  *              than dmax, the remaining slack space is nulled.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  *    dmax      restricted maximum length of the resulting dest,
  *              including the null
@@ -82,7 +84,12 @@
  *    Copying shall not takeplace between objects that overlap
  *    If there is a runtime-constraint violation, then if dest is
  *       not a null pointer and dmax is greater than zero and not
+#ifdef SAFECLIB_STR_NULL_SLACK
  *       greater than RSIZE_MAX_STR, then strcat_s nulls dest.
+#else
+ *       greater than RSIZE_MAX_STR, then strcat_s writes a terminator
+ *       to dest.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * RETURN VALUE
  *    EOK        successful operation, all the characters from src

safeclib/strcpy_s.c

@@ -46,10 +46,14 @@
  * DESCRIPTION
  *    The strcpy_s function copies the string pointed to by src
  *    (including the terminating null character) into the array
+#ifdef SAFECLIB_STR_NULL_SLACK
  *    pointed to by dest. All elements following the terminating
  *    null character (if any) written by strcpy_s in the array
  *    of dmax characters pointed to by dest are nulled when
  *    strcpy_s returns.
+#else
+ *    pointed to by dest.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * SPECIFIED IN
  *    ISO/IEC TR 24731, Programming languages, environments
@@ -75,7 +79,12 @@
  *    Copying shall not take place between objects that overlap.
  *    If there is a runtime-constraint violation, then if dest
  *       is not a null pointer and destmax is greater than zero and
+#ifdef SAFECLIB_STR_NULL_SLACK
  *       not greater than RSIZE_MAX_STR, then strcpy_s nulls dest.
+#else
+ *       not greater than RSIZE_MAX_STR, then strcpy_s writes a
+ *       terminator to dest.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * RETURN VALUE
  *    EOK        successful operation, the characters in src were

safeclib/strncpy_s.c

@@ -48,10 +48,12 @@
  *    (characters that follow a null character are not copied) from the
  *    array pointed to by src to the array pointed to by dest. If no null
  *    character was copied from src, then dest[n] is set to a null character.
+#ifdef SAFECLIB_STR_NULL_SLACK
  *
  *    All elements following the terminating null character (if any)
  *    written by strncpy_s in the array of dmax characters pointed to
  *    by dest take on the null value when strncpy_s returns.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * Specicified in:
  *    ISO/IEC TR 24731-1, Programming languages, environments
@@ -82,7 +84,11 @@
  *    Copying shall not take place between objects that overlap.
  *    If there is a runtime-constraint violation, then if dest
  *       is not a null pointer and dmax greater than RSIZE_MAX_STR,
+#ifdef SAFECLIB_STR_NULL_SLACK
  *       then strncpy_s nulls dest.
+#else
+ *       the strncpy_s writes a terminator to dest.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * RETURN VALUE
  *    EOK        successful operation, the characters in src were copied

safeclib/wcpcpy_s.c

@@ -47,10 +47,14 @@
  *    The wcpcpy_s function copies the wide character string pointed
  *    to by src (including the terminating null character) into the
  *    array pointed to by dest, and returns a pointer to the end of
+#ifdef SAFECLIB_STR_NULL_SLACK
  *    the wide character string. All elements following the terminating
  *    null character (if any) written by wcpcpy_s in the array of
  *    dmax characters pointed to by dest are nulled when
  *    wcpcpy_s returns.
+#else
+ *    the wide character string.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * SPECIFIED IN
  *    ISO/IEC TR 24731, Programming languages, environments
@@ -86,7 +90,12 @@
  *    Copying shall not take place between objects that overlap.
  *    If there is a runtime-constraint violation, then if dest
  *       is not a null pointer and destmax is greater than zero and
+#ifdef SAFECLIB_STR_NULL_SLACK
  *       not greater than RSIZE_MAX_STR, then strcpy_s nulls dest.
+#else
+ *       not greater than RSIZE_MAX_STR, then strcpy_s stores a
+ *       terminator at dest.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * RETURN VALUE
  *   a wchar_t pointer to the terminating null at the end of dest

safeclib/wcscat_s.c

@@ -48,11 +48,13 @@
  *    to by src (including the terminating null character) to the
  *    end of the string pointed to by dest. The initial wide character
  *    from src overwrites the null character at the end of dest.
+#ifdef SAFECLIB_STR_NULL_SLACK
  *
  *    All elements following the terminating null character (if
  *    any) written by strcat_s in the array of dmax characters
  *    pointed to by dest take unspecified values when strcat_s
  *    returns.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * SPECIFIED IN
  *    ISO/IEC TR 24731, Programming languages, environments
@@ -82,7 +84,12 @@
  *    Copying shall not takeplace between objects that overlap
  *    If there is a runtime-constraint violation, then if dest is
  *       not a null pointer and dmax is greater than zero and not
+#ifdef SAFECLIB_STR_NULL_SLACK
  *       greater than RSIZE_MAX_STR, then strcat_s nulls dest.
+#else
+ *       greater than RSIZE_MAX_STR, then strcat_s stores a
+ *       terminator at dest.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * RETURN VALUE
  *    EOK        successful operation, all the characters from src

safeclib/wcscpy_s.c

@@ -46,10 +46,14 @@
  * DESCRIPTION
  *    The wcscpy_s function copies the wide character string pointed
  *    to by src (including the terminating null character) into the
+#ifdef SAFECLIB_STR_NULL_SLACK
  *    array pointed to by dest. All elements following the terminating
  *    null character (if any) written by strcpy_s in the array of
  *    dmax characters pointed to by dest are nulled when
  *    wcscpy_s returns.
+#else
+ *    array pointed to by dest.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * SPECIFIED IN
  *    ISO/IEC TR 24731, Programming languages, environments
@@ -75,7 +79,12 @@
  *    Copying shall not take place between objects that overlap.
  *    If there is a runtime-constraint violation, then if dest
  *       is not a null pointer and destmax is greater than zero and
+#ifdef SAFECLIB_STR_NULL_SLACK
  *       not greater than RSIZE_MAX_STR, then strcpy_s nulls dest.
+#else
+ *       not greater than RSIZE_MAX_STR, then strcpy_s stores a
+ *       terminator at dest.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * RETURN VALUE
  *    EOK        successful operation, the characters in src were

safeclib/wcsncpy_s.c

@@ -48,6 +48,7 @@
  *    (characters that follow a null character are not copied) from the
  *    array pointed to by src to the array pointed to by dest. If no null
  *    character was copied from src, then dest[slen] is set to a null character.
+#ifdef SAFECLIB_STR_NULL_SLACK
  *
  *    All elements following the terminating null character (if any)
  *    written by wcsncpy_s in the array of dmax characters pointed to
@@ -60,6 +61,7 @@
  *    array is used multiple times to string manipulation routines in this
  *    library. If this extra security is not required, ensure that the
  *    library is compiled without #DEFINE SAFECLIB_STR_NULL_SLACK.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * Specicified in:
  *    ISO/IEC TR 24731-1, Programming languages, environments
@@ -90,7 +92,11 @@
  *    Copying shall not take place between objects that overlap.
  *    If there is a runtime-constraint violation, then if dest
  *       is not a null pointer and dmax greater than RSIZE_MAX_STR,
+#ifdef SAFECLIB_STR_NULL_SLACK
  *       then strncpy_s nulls dest.
+#else
+ *       then strncpy_s stores a terminator at dest.
+#endif // SAFECLIB_STR_NULL_SLACK
  *
  * RETURN VALUE
  *    EOK        successful operation, the characters in src were copied