virstring: Introduce VIR_STRDUP and VIR_STRNDUP

The code adaptation is not done right now, but in subsequent patches.
Hence I am not implementing syntax-check rule as it would break
compilation. Developers are strongly advised to use these new macros.
They are similar to VIR_ALLOC() logic: VIR_STRDUP(dst, src) returns zero
on success, -1 otherwise. In case you don't want to report OOM error,
use the _QUIET variant of a macro.

1 files changed, 11 insertions, 0 deletions

diff --git a/HACKING b/HACKING
index e8bebd48e7..b70b89d016 100644
--- a/HACKING
+++ b/HACKING
@@ -719,6 +719,17 @@ sizeof(dest) returns something meaningful). Note that this is a macro, so
 arguments could be evaluated more than once. This is equivalent to
 virStrncpy(dest, src, strlen(src), sizeof(dest)).
 
+  VIR_STRDUP(char *dst, const char *src);
+  VIR_STRNDUP(char *dst, const char *src, size_t n);
+
+You should avoid using strdup or strndup directly as they do not report
+out-of-memory error. Use VIR_STRDUP or VIR_STRNDUP macros instead. Note, that
+these two behave similar to VIR_ALLOC: on success zero is returned, otherwise
+the result is -1 and dst is guaranteed to be NULL. In very specific cases,
+when you don't want to report the out-of-memory error, you can use
+VIR_STRDUP_QUIET or VIR_STRNDUP_QUIET, but such usage is very rare and usually
+considered a flaw.
+
 
 Variable length string buffer
 =============================