lib/string/zustr2stp.[ch]: Remove zustr2stp(); keep ZUSTR2STP()

The function should never be used; it's always used via its wrapper
macro.  To simplify, and reduce chances of confusion, remove the
function, and implement the macro directly in terms of
stpcpy(mempcpy(strnlen())).

Update the documentation, and improve the example, which was rather
confusing.

Cc: "Serge E. Hallyn" <[email protected]>
Signed-off-by: Alejandro Colomar <[email protected]>

lib/Makefile.am

@@ -145,7 +145,6 @@ libshadow_la_SOURCES = \
 	string/strncpy.h \
 	string/strtcpy.c \
 	string/strtcpy.h \
-	string/zustr2stp.c \
 	string/zustr2stp.h \
 	strtoday.c \
 	sub.c \

lib/string/zustr2stp.h

@@ -11,7 +11,6 @@
 #include <config.h>
 
 #include <assert.h>
-#include <stddef.h>
 #include <string.h>
 
 #include "must_be.h"
@@ -22,58 +21,39 @@
 ({                                                                            \
 	static_assert(!is_array(dst) || sizeof(dst) > SIZEOF_ARRAY(src), ""); \
                                                                               \
-	zustr2stp(dst, src, NITEMS(src));                                     \
+	stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), "");             \
 })
 
 
-inline char *zustr2stp(char *restrict dst, const char *restrict src, size_t sz);
-
-
 /*
  * SYNOPSIS
- *	char *zustr2stp(char *restrict dst,
- *	                const char src[restrict .sz], size_t sz);
+ *	char *ZUSTR2STP(char *restrict dst, const char src[restrict]);
  *
  * ARGUMENTS
- *	dst	Destination buffer where to copy a string.
- *
- *	src	Source null-padded character sequence to be copied into
- *	        dst.
- *
- *	sz	Size of the *source* buffer.
+ *	dst	Destination buffer.
+ *	src	Source null-padded character sequence.
  *
  * DESCRIPTION
- *	This function copies the null-padded character sequence pointed
+ *	This macro copies the null-padded character sequence pointed
  *	to by src, into a string at the buffer pointed to by dst.
  *
  * RETURN VALUE
  *	dst + strlen(dst)
  *		This function returns a pointer to the terminating NUL
  *		byte.
  *
- * ERRORS
- *	This function doesn't set errno.
- *
  * CAVEATS
  *	This function doesn't know the size of the destination buffer.
  *	It assumes it will always be large enough.  Since the size of
  *	the source buffer is known to the caller, it should make sure to
- *	allocate a destination buffer of at least `sz + 1`.
+ *	allocate a destination buffer of at least `NITEMS(src) + 1`.
  *
  * EXAMPLES
- *	char  src[13] = "Hello, world!"  // No '\0' in this buffer!
- *	char  dst[NITEMS(src) + 1];
+ *	char  hostname[NITEMS(utmp->ut_host) + 1];
  *
- *	zustr2stp(dst, src, NITEMS(src));
- *	puts(dst);
+ *	len = ZUSTR2STP(hostname, utmp->ut_host) - hostname;
+ *	puts(hostname);
  */
 
 
-inline char *
-zustr2stp(char *restrict dst, const char *restrict src, size_t sz)
-{
-	return stpcpy(mempcpy(dst, src, strnlen(src, sz)), "");
-}
-
-
 #endif  // include guard