common: add comments to strscat/cpy functions
authorFerry Huberts <ferry.huberts@pelagic.nl>
Thu, 2 Jun 2016 16:19:19 +0000 (18:19 +0200)
committerFerry Huberts <ferry.huberts@pelagic.nl>
Thu, 2 Jun 2016 20:06:48 +0000 (22:06 +0200)
Signed-off-by: Ferry Huberts <ferry.huberts@pelagic.nl>
src/common/string_handling.c

index 5370fe9..eaeb804 100644 (file)
 
 #include "common/string_handling.h"
 
-/*
- * A somewhat safe version of strncpy and strncat. Note, that
- * BSD/Solaris strlcpy()/strlcat() differ in implementation, while
- * the BSD compiler prints out a warning if you use plain strcpy().
+/**
+ * A somewhat safe version of strncpy.
+ * 1) This function never writes more than dest_size bytes.
+ * 2) This function always terminates the content of the dest buffer with
+ *    a zero byte.
+ * 3) This function does not write more than strlen(src)+1 bytes
+ *
+ * @param dest pointer to the destination buffer
+ * @param src pointer to the source buffer
+ * @param dest_size length of destination buffer in bytes
+ *
+ * @return pointer to destination buffer
  */
-
 char * strscpy(char *dest, const char *src, size_t dest_size) {
   register size_t l = 0;
 #if !defined(NODEBUG) && defined(DEBUG)
@@ -76,6 +83,22 @@ char * strscpy(char *dest, const char *src, size_t dest_size) {
   return strncpy(dest, src, l);
 }
 
+/**
+ * A somewhat safe version of strncat, it appends the string
+ * content of src to dest.
+ * 1) This function never writes more than dest_size bytes.
+ * 2) This function always terminates the content of the dest buffer with
+ *    a zero byte.
+ * 3) This function does not write more than strlen(src)+1 bytes
+ *
+ * The function returns an error if dst or src or dst_size is zero.
+ *
+ * @param dest pointer to the destination buffer
+ * @param src pointer to the source buffer
+ * @param dest_size length of destination buffer in bytes
+ *
+ * @return pointer to destination buffer, NULL if an error happened
+ */
 char * strscat(char *dest, const char *src, size_t dest_size) {
   register size_t l = strlen(dest);
   return strscpy(dest + l, src, dest_size > l ? dest_size - l : 0);