1912. [func] ISC string copy API.

CHANGES

@@ -1,3 +1,5 @@
+1912.	[func]		ISC string copy API.
+
 1911.	[func]		Attempt to make the amount of work performed in a
 			iteration self tuning.  The covers nodes clean from
 			the cache per iteration, nodes written to disk when

lib/isc/include/isc/string.h

@@ -15,7 +15,7 @@
  * PERFORMANCE OF THIS SOFTWARE.
  */
 
-/* $Id: string.h,v 1.12.18.2 2005/04/29 00:17:03 marka Exp $ */
+/* $Id: string.h,v 1.12.18.3 2005/08/16 04:39:05 marka Exp $ */
 
 #ifndef ISC_STRING_H
 #define ISC_STRING_H 1
@@ -24,9 +24,13 @@
 
 #include <string.h>
 
+#include <isc/formatcheck.h>
 #include <isc/int.h>
 #include <isc/lang.h>
 #include <isc/platform.h>
+#include <isc/types.h>
+
+#define ISC_STRING_MAGIC 0x5e
 
 ISC_LANG_BEGINDECLS
 
@@ -45,6 +49,150 @@ isc_string_touint64(char *source, char **endp, int base);
  * On error 'endp' points to 'source'.
  */
 
+isc_result_t
+isc_string_copy(char *target, size_t size, const char *source);
+/*
+ * Copy the string pointed to by 'source' to 'target' which is a
+ * pointer to a string of at least 'size' bytes.
+ *
+ * Requires:
+ *	'target' is a pointer to a char[] of at least 'size' bytes.
+ *	'size' an integer > 0.
+ *	'source' == NULL or points to a NUL terminated string.
+ *
+ * Ensures:
+ *	If result == ISC_R_SUCCESS
+ *		'target' will be a NUL terminated string of no more
+ *		than 'size' bytes (including NUL).
+ *
+ *	If result == ISC_R_NOSPACE
+ *		'target' is undefined.
+ *
+ * Returns:
+ *	ISC_R_SUCCESS  -- 'source' was successfully copied to 'target'.
+ *	ISC_R_NOSPACE  -- 'source' could not be copied since 'target'
+ *	                  is too small.
+ */
+
+void
+isc_string_copy_truncate(char *target, size_t size, const char *source);
+/*
+ * Copy the string pointed to by 'source' to 'target' which is a
+ * pointer to a string of at least 'size' bytes.
+ *
+ * Requires:
+ *	'target' is a pointer to a char[] of at least 'size' bytes.
+ *	'size' an integer > 0.
+ *	'source' == NULL or points to a NUL terminated string.
+ *
+ * Ensures:
+ *	'target' will be a NUL terminated string of no more
+ *	than 'size' bytes (including NUL).
+ */
+
+isc_result_t
+isc_string_append(char *target, size_t size, const char *source);
+/*
+ * Append the string pointed to by 'source' to 'target' which is a
+ * pointer to a NUL terminated string of at least 'size' bytes.
+ *
+ * Requires:
+ *	'target' is a pointer to a NUL terminated char[] of at
+ *	least 'size' bytes.
+ *	'size' an integer > 0.
+ *	'source' == NULL or points to a NUL terminated string.
+ *
+ * Ensures:
+ *	If result == ISC_R_SUCCESS
+ *		'target' will be a NUL terminated string of no more
+ *		than 'size' bytes (including NUL).
+ *
+ *	If result == ISC_R_NOSPACE
+ *		'target' is undefined.
+ *
+ * Returns:
+ *	ISC_R_SUCCESS  -- 'source' was successfully appended to 'target'.
+ *	ISC_R_NOSPACE  -- 'source' could not be appended since 'target'
+ *	                  is too small.
+ */
+
+void
+isc_string_append_truncate(char *target, size_t size, const char *source);
+/*
+ * Append the string pointed to by 'source' to 'target' which is a
+ * pointer to a NUL terminated string of at least 'size' bytes.
+ *
+ * Requires:
+ *	'target' is a pointer to a NUL terminated char[] of at
+ *	least 'size' bytes.
+ *	'size' an integer > 0.
+ *	'source' == NULL or points to a NUL terminated string.
+ *
+ * Ensures:
+ *	'target' will be a NUL terminated string of no more
+ *	than 'size' bytes (including NUL).
+ */
+
+isc_result_t
+isc_string_printf(char *target, size_t size, const char *format, ...);
+/*
+ * Print 'format' to 'target' which is a pointer to a string of at least
+ * 'size' bytes.
+ *
+ * Requires:
+ *	'target' is a pointer to a char[] of at least 'size' bytes.
+ *	'size' an integer > 0.
+ *	'format' == NULL or points to a NUL terminated string.
+ *
+ * Ensures:
+ *	If result == ISC_R_SUCCESS
+ *		'target' will be a NUL terminated string of no more
+ *		than 'size' bytes (including NUL).
+ *
+ *	If result == ISC_R_NOSPACE
+ *		'target' is undefined.
+ *
+ * Returns:
+ *	ISC_R_SUCCESS  -- 'format' was successfully printed to 'target'.
+ *	ISC_R_NOSPACE  -- 'format' could not be printed to 'target' since it
+ *	                  is too small.
+ */
+
+void
+isc_string_printf_truncate(char *target, size_t size, const char *format, ...)
+	ISC_FORMAT_PRINTF(3, 4);
+/*
+ * Print 'format' to 'target' which is a pointer to a string of at least
+ * 'size' bytes.
+ *
+ * Requires:
+ *	'target' is a pointer to a char[] of at least 'size' bytes.
+ *	'size' an integer > 0.
+ *	'format' == NULL or points to a NUL terminated string.
+ *
+ * Ensures:
+ *	'target' will be a NUL terminated string of no more
+ *	than 'size' bytes (including NUL).
+ */
+
+
+char *
+isc_string_regiondup(isc_mem_t *mctx, const isc_region_t *source);
+/*
+ * Copy the region pointed to by r to a NUL terminated string
+ * allocated from the memory context pointed to by mctx.
+ *
+ * The result should be deallocated using isc_mem_free()
+ *
+ * Requires:
+ *	'mctx' is a point to a valid memory context.
+ *	'source' is a pointer to a valid region.
+ *
+ * Returns:
+ *	a pointer to a NUL terminated string or
+ *	NULL if memory for the copy could not be allocated
+ *
+ */
 
 char *
 isc_string_separate(char **stringp, const char *delim);

lib/isc/string.c

@@ -15,7 +15,7 @@
  * PERFORMANCE OF THIS SOFTWARE.
  */
 
-/* $Id: string.c,v 1.10.18.3 2005/04/29 00:16:50 marka Exp $ */
+/* $Id: string.c,v 1.10.18.4 2005/08/16 04:39:05 marka Exp $ */
 
 /*! \file */
 
@@ -23,7 +23,10 @@
 
 #include <ctype.h>
 
+#include <isc/mem.h>
+#include <isc/region.h>
 #include <isc/string.h>
+#include <isc/util.h>
 
 static char digits[] = "0123456789abcdefghijklmnoprstuvwxyz";
 
@@ -91,6 +94,105 @@ isc_string_touint64(char *source, char **end, int base) {
 	return (tmp);
 }
 
+isc_result_t
+isc_string_copy(char *target, size_t size, const char *source) {
+	REQUIRE(size > 0);
+
+	if (strlcpy(target, source, size) >= size) {
+		memset(target, ISC_STRING_MAGIC, size);
+		return (ISC_R_NOSPACE);
+	}
+
+	ENSURE(strlen(target) < size);
+
+	return (ISC_R_SUCCESS);
+}
+
+void
+isc_string_copy_truncate(char *target, size_t size, const char *source) {
+	REQUIRE(size > 0);
+
+	strlcpy(target, source, size);
+
+	ENSURE(strlen(target) < size);
+}
+
+isc_result_t
+isc_string_append(char *target, size_t size, const char *source) {
+	REQUIRE(size > 0);
+	REQUIRE(strlen(target) < size);
+
+	if (strlcat(target, source, size) >= size) {
+		memset(target, ISC_STRING_MAGIC, size);
+		return (ISC_R_NOSPACE);
+	}
+
+	ENSURE(strlen(target) < size);
+
+	return (ISC_R_SUCCESS);
+}
+
+void
+isc_string_append_truncate(char *target, size_t size, const char *source) {
+	REQUIRE(size > 0);
+	REQUIRE(strlen(target) < size);
+
+	strlcat(target, source, size);
+
+	ENSURE(strlen(target) < size);
+}
+
+isc_result_t
+isc_string_printf(char *target, size_t size, const char *format, ...) {
+	va_list args;
+	size_t n;
+
+	REQUIRE(size > 0);
+
+	va_start(args, format);
+	n = vsnprintf(target, size, format, args);
+	va_end(args);
+
+	if (n >= size) {
+		memset(target, ISC_STRING_MAGIC, size);
+		return (ISC_R_NOSPACE);
+	}
+
+	ENSURE(strlen(target) < size);
+
+	return (ISC_R_SUCCESS);
+}
+
+void
+isc_string_printf_truncate(char *target, size_t size, const char *format, ...) {
+	va_list args;
+	size_t n;
+
+	REQUIRE(size > 0);
+
+	va_start(args, format);
+	n = vsnprintf(target, size, format, args);
+	va_end(args);
+
+	ENSURE(strlen(target) < size);
+}
+
+char *
+isc_string_regiondup(isc_mem_t *mctx, const isc_region_t *source) {
+	char *target;
+
+	REQUIRE(mctx != NULL);
+	REQUIRE(source != NULL);
+
+	target = (char *) isc_mem_allocate(mctx, source->length + 1);
+	if (target != NULL) {
+		memcpy(source->base, target, source->length);
+		target[source->length] = '\0';
+	}
+
+	return (target);
+}
+
 char *
 isc_string_separate(char **stringp, const char *delim) {
 	char *string = *stringp;