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]>
Cc: Iker Pedrosa <[email protected]>
Signed-off-by: Alejandro Colomar <[email protected]>

lib/Makefile.am

@@ -152,7 +152,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.c

@@ -1,17 +1,7 @@
-/*
- * SPDX-FileCopyrightText: 2022-2023, Alejandro Colomar <[email protected]>
- * SPDX-License-Identifier: BSD-3-Clause
- */
+// SPDX-FileCopyrightText: 2022-2024, Alejandro Colomar <[email protected]>
+// SPDX-License-Identifier: BSD-3-Clause
 
 
 #include <config.h>
 
-#include <stddef.h>
-
-#ident "$Id$"
-
 #include "string/zustr2stp.h"
-
-
-extern inline char *zustr2stp(char *restrict dst, const char *restrict src,
-    size_t sz);

lib/string/zustr2stp.h

@@ -1,79 +1,58 @@
-/*
- * SPDX-FileCopyrightText: 2022-2023, Alejandro Colomar <[email protected]>
- * SPDX-License-Identifier: BSD-3-Clause
- */
+// SPDX-FileCopyrightText: 2022-2024, Alejandro Colomar <[email protected]>
+// SPDX-License-Identifier: BSD-3-Clause
 
 
-#ifndef SHADOW_INCLUDE_LIBMISC_ZUSTR2STP_H_
-#define SHADOW_INCLUDE_LIBMISC_ZUSTR2STP_H_
+#ifndef SHADOW_INCLUDE_LIB_STRING_ZUSTR2STP_H_
+#define SHADOW_INCLUDE_LIB_STRING_ZUSTR2STP_H_
 
 
 #include <config.h>
 
 #include <assert.h>
-#include <stddef.h>
 #include <string.h>
 
 #include "must_be.h"
 #include "sizeof.h"
 
 
-#define ZUSTR2STP(dst, src)                                                   \
-({                                                                            \
-	static_assert(!is_array(dst) || sizeof(dst) > SIZEOF_ARRAY(src), ""); \
-                                                                              \
-	zustr2stp(dst, 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
- *	to by src, into a string at the buffer pointed to by dst.
+ *	This macro copies at most NITEMS(src) non-null bytes from the
+ *	array pointed to by src, followed by a null character, to 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)), "");
-}
+#define ZUSTR2STP(dst, src)                                                   \
+({                                                                            \
+	static_assert(!is_array(dst) || sizeof(dst) > SIZEOF_ARRAY(src), ""); \
+                                                                              \
+	stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), "");             \
+})
 
 
 #endif  // include guard