lib/52779: strlcpy(3) omits important information (and is poor anyway)

[kre%munnari.OZ.AU@localhost]

>Number:         52779
>Category:       lib
>Synopsis:       strlcpy(3) omits important information (and is poor anyway)
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    lib-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Dec 03 09:00:00 +0000 2017
>Originator:     Robert Elz
>Release:        NetBSD 8.99.3
>Organization:
>Environment:
System: NetBSD magnolia.noi.kre.to 8.99.3 NetBSD 8.99.3 (MAGNOLIA-1.13-20170926) #43: Tue Sep 26 23:11:07 ICT 2017 kre%magnolia.noi.kre.to@localhost:/usr/obj/current/kernels/amd64/MAGNOLIA amd64
Architecture: x86_64
Machine: amd64
>Description:
	The man page for strlcpy(3) (and strncat(3) since it is the same one)
	makes no mention of whether overlapping buffer copies are safe or not.
	It should.

	That is, can a program do

		strlcpy(buf, buf+1, ...)
	or
		strlcpy(buf+1, buf, ...)
	or even
		strlcpy(buf, buf, ...)

	(probably not as blatantly as that, but where the src happens to
	have been computed as a pointer into the dest string.)

	Same for strlcat() obviously - though perhaps it might provide
	a more likely use scenario.

	Beyond that, the man pages have way too much of the "why I was
	so great as to create this new function" which doesn't belong at
	all, it should just say what the functions do, what the args are,
	what restrictions are placed upon them, and what the results will
	be (and if it seems needed, an example - or even two).

>How-To-Repeat:
	RTFM.

>Fix:
	Rewrite the man page.   Almost completely.