Introduce virStrncpy.

Add the virStrncpy function, which takes a dst string, source string,
the number of bytes to copy and the number of bytes available in the
dest string.  If the source string is too large to fit into the
destination string, including the \0 byte, then no data is copied and
the function returns NULL.  Otherwise, this function copies n bytes
from source into dst, including the \0, and returns a pointer to the
dst string.  This function is intended to replace all unsafe uses
of strncpy in the code base, since strncpy does *not* guarantee that
the buffer terminates with a \0.

Signed-off-by: Chris Lalancette <clalance@redhat.com>

1 files changed, 31 insertions, 0 deletions

diff --git a/HACKING b/HACKING
index da28e98bf..bcff8c633 100644
--- a/HACKING
+++ b/HACKING
@@ -231,6 +231,37 @@ one of the following semantically named macros
 
 
 
+String copying
+==============
+
+Do not use the strncpy function.  According to the man page, it does
+*not* guarantee a NULL-terminated buffer, which makes it extremely dangerous
+to use.  Instead, use one of the functionally equivalent functions:
+
+  - virStrncpy(char *dest, const char *src, size_t n, size_t destbytes)
+      The first three arguments have the same meaning as for strncpy; namely the
+      destination, source, and number of bytes to copy, respectively.  The last
+      argument is the number of bytes available in the destination string; if a
+      copy of the source string (including a \0) will not fit into the
+      destination, no bytes are copied and the routine returns NULL.
+      Otherwise, n bytes from the source are copied into the destination and a
+      trailing \0 is appended.
+
+  - virStrcpy(char *dest, const char *src, size_t destbytes)
+      Use this variant if you know you want to copy the entire src string
+      into dest.  Note that this is a macro, so arguments could be
+      evaluated more than once.  This is equivalent to
+      virStrncpy(dest, src, strlen(src), destbytes)
+
+  - virStrcpyStatic(char *dest, const char *src)
+      Use this variant if you know you want to copy the entire src string
+      into dest *and* you know that your destination string is a static string
+      (i.e. that 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)).
+
+
+
 Variable length string buffer
 =============================