Add documentation for all parameters and the return value based on the
function's current behavior.
Apparently this function was intended to behave like snprintf(), where
the output is simply truncated if the output buffer isn't big enough.
However, as currently written, the function might write past the end
of the output buffer if the output buffer isn't big enough. Thus, in
its current state it can't be used with a small buffer, so document it
as such.
Note that this change in documented behavior means that the test cases
in stringutils-test.c now violate the API specification. Similarly,
other users of this function might rely on support for small output
buffers. However, future commits will change scrub_for_print() to
support truncation, so I am not going to modify any code to conform to
this new documentation.
---
lib/util/stringutils.h | 19 ++++++++++++++++++-
1 file changed, 18 insertions(+), 1 deletion(-)
diff --git a/lib/util/stringutils.h b/lib/util/stringutils.h
index 61030b3..c059c77 100644
--- a/lib/util/stringutils.h
+++ b/lib/util/stringutils.h
@@ -141,8 +141,25 @@ int expand_by_doubling(
* @brief Replace questionable chars from string for printing.
*
* @note Caller handles memory for dst.
- * @note Output might be truncated, compared to input.
* @note dst will be null terminated, at or before index dst_sz-1.
+ *
+ * @param[out] dst
+ * Location of the buffer to hold the output string. This must
+ * not be NULL.
+ * @param[in] src
+ * The input string to escape. This must not be NULL.
+ * @param[in] dst_sz
+ * Size of the buffer at @p dst. The buffer must be big enough to
+ * hold the entire escaped string, including the nul terminator.
+ * @param[out] dst_len_out
+ * On return, the value at this location will be set to the length
+ * of the escaped string (excluding the nul terminator). This
+ * parameter may be NULL.
+ * @param[in] other_chars_to_escape
+ * nul-terminated array of additional characters to escape with a
+ * backslash. This must not be NULL.
+ *
+ * @return dst
------------------------------------------------------------------------------*/
char *scrub_for_print(
char *dst,
--
2.4.3
------------------------------------------------------------------------------
_______________________________________________
rpstir-devel mailing list
rpstir-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/rpstir-devel
