Re: [PATCH v6 1/5] string_copy.7: Add page to document all string-copying functions

From: Alejandro Colomar <alx.manpages@gmail.com>
To: Eric Biggers <ebiggers@kernel.org>
Cc: linux-man@vger.kernel.org, Alejandro Colomar <alx@kernel.org>,
	Martin Sebor <msebor@redhat.com>,
	"G. Branden Robinson" <g.branden.robinson@gmail.com>,
	Douglas McIlroy <douglas.mcilroy@dartmouth.edu>,
	Jakub Wilk <jwilk@jwilk.net>, Serge Hallyn <serge@hallyn.com>,
	Iker Pedrosa <ipedrosa@redhat.com>,
	Andrew Pinski <pinskia@gmail.com>,
	Stefan Puiu <stefan.puiu@gmail.com>
Subject: Re: [PATCH v6 1/5] string_copy.7: Add page to document all string-copying functions
Date: Fri, 20 Jan 2023 13:55:51 +0100	[thread overview]
Message-ID: <51f4f1f4-b072-af6f-ad18-bdf18aa42406@gmail.com> (raw)
In-Reply-To: <Y8oN1ae9C0UZIaEA@sol.localdomain>

[-- Attachment #1.1: Type: text/plain, Size: 1811 bytes --]

Hi Eric,

On 1/20/23 04:43, Eric Biggers wrote:
> On Mon, Dec 19, 2022 at 10:02:05PM +0100, Alejandro Colomar wrote:
>> diff --git a/man7/string_copy.7 b/man7/string_copy.7
>> new file mode 100644
>> index 000000000..a32b93c01
>> --- /dev/null
>> +++ b/man7/string_copy.7
>> @@ -0,0 +1,855 @@
>> +.\" Copyright 2022 Alejandro Colomar <alx@kernel.org>
>> +.\"
>> +.\" SPDX-License-Identifier: BSD-3-Clause
>> +.\"
>> +.TH string_copy 7 (date) "Linux man-pages (unreleased)"
>> +.\" ----- NAME :: -----------------------------------------------------/
>> +.SH NAME
>> +stpcpy,
>> +strcpy, strcat,
>> +stpecpy, stpecpyx,
>> +strlcpy, strlcat,
>> +stpncpy,
>> +strncpy,
>> +zustr2ustp, zustr2stp,
>> +strncat,
>> +ustpcpy, ustr2stp
> 
> I happened to come across this new man page, and I'm confused by the inclusion
> of functions like "ustpcpy".  These functions don't seem to actually exist, so
> why are they documented in the man page?

That page is not documenting the existing libc functions for copying strings, 
but rather trying to explain all the alternatives, including other systems' ones 
(such as strlcpy(3bsd)), and custom ones that are not provided by any system 
(yet).  It tries to guide a programmer that knows nothing about string copying 
to allow him produce quality code, independently of libc support.  For 
documentation of the libc functions we still have the separate pages for each, 
which have been also updated.

Those specific functions are similar to the old saying of "just use memcpy(3) 
and forget about string copying functions", which is not so bad of an advice: 
it's the fastest; however, those functions are a bit safer than directly calling 
memcpy(3).

> 
> - Eric

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]