safestring: 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 <mark.d.rustad@intel.com>

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
+ * then 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
@@ -165,11 +171,11 @@ wcsncpy_s(wchar_t* dest, rsize_t dmax, const wchar_t* src, rsize_t slen)
  }
 
  if (slen == 0) {
+#ifdef SAFECLIB_STR_NULL_SLACK
  /*
  * Copying truncated to slen chars. Note that the TR says to
  * copy slen chars plus the null char. We null the slack.
  */
-#ifdef SAFECLIB_STR_NULL_SLACK
  while (dmax) { *dest = '\0'; dmax--; dest++; }
 #else
  *dest = '\0';
@@ -203,11 +209,11 @@ wcsncpy_s(wchar_t* dest, rsize_t dmax, const wchar_t* src, rsize_t slen)
  }
 
  if (slen == 0) {
+#ifdef SAFECLIB_STR_NULL_SLACK
  /*
  * Copying truncated to slen chars. Note that the TR says to
  * copy slen chars plus the null char. We null the slack.
  */
-#ifdef SAFECLIB_STR_NULL_SLACK
  while (dmax) { *dest = '\0'; dmax--; dest++; }
 #else
  *dest = '\0';