Name
	n3662, alx-0022r2 - add stpcpy(3), wcpcpy(3), mempcpy(3), wmempcpy(3)

Principles
	-  Codify existing practice to address evident deficiencies.
	-  Enable secure programming

Category
	Standardize common APIs

Author
	Alejandro Colomar <alx@kernel.org>

	Cc: Yair Lenga <yair.lenga@gmail.com>
	Cc: Joseph Myers <josmyers@redhat.com>
	Cc: Christopher Bazley <chris.bazley.wg14@gmail.com>

History
	<https://www.alejandro-colomar.es/src/alx/alx/wg14/alx-0022.git/>

	r0 (2025-06-13):
	-  Initial draft.

	r1 (2025-06-26; n3615):
	-  wfix.
	-  Define the return value more accurately.

	r2 (2025-07-03; n3662):
	-  Add cast in description of mempcpy(3).
	-  Don't repeat the name of a function unnecesarily.
	-  Describe wmempcpy(3) in terms of wmemcpy(3) instead of
	   mempcpy(3).

Rationale
	Some C libraries have a set of functions that return a different
	pointer value, which is more useful for certain operations.
	These APIs enable code that is simpler and more efficient.

Prior art
	POSIX standardizes some of these APIs.  Others, like mempcpy(3)
	are non-standard, but widely available in POSIX systems.

Design decisions
	This proposal leaves out stpncpy(3) and wcpncpy(3), since I
	believe strncpy(3) does not belong in the standard string
	library, as it's a very specialized API that should almost never
	be used by most programmers.  It's only useful for handling
	fixed-width zero-padded character arrays.

Proposed wording
	Based on N3550.

    7.28.2  String handling <string.h> :: Copying functions
	## New section after 7.28.2.1 ("The memcpy function"):

	+7.28.2.1+1  The <b>mempcpy</b> function
	+
	+Synopsis
	+1	#include <string.h>
	+	void *mempcpy(void *restrict dst, const void *restrict src, size_t n);
	+
	+Description
	+2	This function
	+	is equivalent to <b>memcpy</b>,
	+	except for the return value.
	+
	+Returns
	+3	This function returns
	+	<tt>(void *) ((char *) dst + n)</tt>.

	## New section after 7.28.2.4 ("The strcpy function")

	+7.28.2.4+1  The <b>stpcpy</b> function
	+
	+Synopsis
	+1	#include <string.h>
	+	char *stpcpy(char *restrict dst, const char *restrict src);
	+
	+Description
	+2	This function
	+	is equivalent to <b>strcpy</b>,
	+	except for the return value.
	+
	+Returns
	+3	This function returns
	+	a pointer to the terminating null byte in <tt>dst</tt>.

    7.33.4.3  Wide string copying functions
	## New section after 7.33.4.3.1 ("The wcscpy function"):

	+7.33.4.3.1+1  The <b>wcpcpy</b> function
	+
	+Synopsis
	+1	#include <wchar.h>
	+	wchar_t *wcpcpy(wchar_t *restrict dst, const wchar_t *restrict src);
	+
	+Description
	+2	This function
	+	is equivalent to <b>stpcpy</b>,
	+	except that it handles wide strings.

	## New section after 7.33.4.3.3 ("The wmemcpy function"):

	+7.33.4.3.3+1  The <b>wmempcpy</b> function
	+
	+Synopsis
	+1	#include <string.h>
	+	wchar_t *wmempcpy(wchar_t *restrict dst, const wchar_t *restrict src, size_t n);
	+
	+Description
	+2	This function
	+	is equivalent to <b>wmemcpy</b>,
	+	except for the return value.
	+
	+Returns
	+3	This function returns
	+	<tt>dst + n</tt>.