From: Alejandro Colomar <alx.manpages@gmail.com>
To: Sam James <sam@gentoo.org>
Cc: Helge Kreutzmann <debian@helgefjell.de>,
GNU C Library <libc-alpha@sourceware.org>,
mario.blaettermann@gmail.com, linux-man@vger.kernel.org
Subject: Re: Issue in man page wcsncpy.3
Date: Mon, 5 Dec 2022 00:14:48 +0100 [thread overview]
Message-ID: <cbce8940-0de5-da04-a7d9-ae4bff499781@gmail.com> (raw)
In-Reply-To: <EC7619DA-5D2E-4738-97D2-9A98D4108A02@gentoo.org>
[-- Attachment #1.1: Type: text/plain, Size: 6094 bytes --]
Hi Sam!
On 12/5/22 00:06, Sam James wrote:
>
>
>> On 4 Dec 2022, at 20:42, Alejandro Colomar via Libc-alpha <libc-alpha@sourceware.org> wrote:
>>
>> Hi Helge, glibc developers,
>>
>> On 12/4/22 10:07, Helge Kreutzmann wrote:
>>> Without further ado, the following was found:
>>> Issue: Is the "L" in the bracket (for the NULL character) correct?
>>> "The B<wcsncpy>() function is the wide-character equivalent of the"
>>> "B<strncpy>(3) function. It copies at most I<n> wide characters from the"
>>> "wide-character string pointed to by I<src>, including the terminating null"
>>> "wide character (L\\(aq\\e0\\(aq), to the array pointed to by I<dest>."
>>> "Exactly I<n> wide characters are written at I<dest>. If the length"
>>> "I<wcslen(src)> is smaller than I<n>, the remaining wide characters in the"
>>> "array pointed to by I<dest> are filled with null wide characters. If the"
>>> "length I<wcslen(src)> is greater than or equal to I<n>, the string pointed"
>>> "to by I<dest> will not be terminated by a null wide character."
>>
>> As an unrelated note. I've had this running in my mind for some time... your various bug reports for strncpy(3) and similar wide character functions have triggered those thougts.
>>
>> I'm going to mark strncpy(3) and similar functions as deprecated, even if no libc or standard has done so. There's wide agreement (at least in some communities) that strncpy(3) _is evil_. There's simply no use for it.
>>
>
> Please don't do this unilaterally. Apple did this unilaterally for sprintf which has caused problems, as well.
>
> It's going to cause confusion as people will inevitably ask where/who deprecated it and there won't
> be a solid answer.
I'm writing up a solid answer for that. Please check
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man3/strncpy.3>.
The manual page is now all about why it should never be used. In fact, I was
going to do that without adding the [[deprecated]] attribute to the SYNOPSIS,
but I convinced myself that it's necessary after writing that.
I'll copy here the current state of the page. If there's general concern about
the attribute, I can remove it while keeping everything else against its use; I
don't think it will be a big change. But I hope this convinces readers about it
being harmful.
strncpy(3) Library Functions Manual strncpy(3)
NAME
strncpy - copy a string into a fixed‐length buffer and zero the
rest of it
LIBRARY
Standard C library (libc, -lc)
SYNOPSIS
#include <string.h>
[[deprecated]] char *strncpy(char dest[restrict .n],
const char src[restrict .n], size_t n);
DESCRIPTION
Note: This is not the function you want to use. For safe string
copying, see strlcpy(3bsd). For copying a string into a fixed‐
length buffer with zeroing of the rest, see stpncpy(3).
The strncpy() copies at most n bytes of src, and fills the rest of
the dest buffer with null bytes. Warning: If there is no null
byte among the first n bytes of src, the string placed in dest
will not be null‐terminated.
A simple implementation of strncpy() might be:
char *
strncpy(char *dest, const char *src, size_t n)
{
bzero(dest, n);
memccpy(dest, src, '\0', n);
return dest;
}
The only valid use of strncpy() is to copy a C string to a fixed‐
length buffer while ensuring that unused bytes in the destination
buffer are zeroed out (perhaps to prevent information leaks if the
buffer is to be written to media or transmitted to another process
via an interprocess communication technique). But stpncpy(3) is
better for this purpose, since it detects truncation. See CAVEATS
below.
RETURN VALUE
The strncpy() function returns a pointer to the destination buffer
dest.
ATTRIBUTES
For an explanation of the terms used in this section, see attrib‐
utes(7).
┌───────────────────────────────────────┬───────────────┬─────────┐
│Interface │ Attribute │ Value │
├───────────────────────────────────────┼───────────────┼─────────┤
│strncpy() │ Thread safety │ MT‐Safe │
└───────────────────────────────────────┴───────────────┴─────────┘
STANDARDS
POSIX.1‐2001, POSIX.1‐2008, C89, C99, SVr4, 4.3BSD.
CAVEATS
strncpy() has a misleading name. It doesn’t produce a (null‐ter‐
minated) string; and it should never be used for producing a
string.
It can’t detect truncation. It’s probably better to explicitly
call bzero(3) and memccpy(3), or stpncpy(3) since they allow de‐
tecting truncation.
SEE ALSO
bzero(3), memccpy(3), stpncpy(3), string(3), wcsncpy(3)
Linux man‐pages (unreleased) (date) strncpy(3)
> And if we can't get a libc to agree to deprecate it as well, then doing it in the man
> pages is wrong. Even if I understand the spirit of the idea.
I hope this can convince someone in glibc :)
If there's consensus against marking it as [[deprecated]], I'll revert that bit
before the next release later this month.
Cheers,
Alex
>
> Best,
> sam
--
<http://www.alejandro-colomar.es/>
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
prev parent reply other threads:[~2022-12-04 23:15 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20221204090724.GA1249@Debian-50-lenny-64-minimal>
2022-12-04 20:42 ` Alejandro Colomar
2022-12-04 22:44 ` Alejandro Colomar
2022-12-04 23:06 ` Sam James
2022-12-04 23:09 ` Sam James
2022-12-04 23:28 ` Alejandro Colomar
2022-12-04 23:14 ` Alejandro Colomar [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=cbce8940-0de5-da04-a7d9-ae4bff499781@gmail.com \
--to=alx.manpages@gmail.com \
--cc=debian@helgefjell.de \
--cc=libc-alpha@sourceware.org \
--cc=linux-man@vger.kernel.org \
--cc=mario.blaettermann@gmail.com \
--cc=sam@gentoo.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).