Re: strncpy clarify result may not be null terminated

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 2240 bytes --]

Hi Jonny,

On Sun, Nov 05, 2023 at 09:16:25PM +0000, Jonny Grant wrote:
> Michael, what do you think about this documentation suggestion I have made. Interested to hear your opinion.
> 
> Should the man page follow the C spec description of the strncpy function and how when it copies the arrays, it may leave the resulting array of characters not terminated, and warn about this pitfall.
> 
> C99 had this, and it is still there in latest C23 draft - worth clarifying on strncpy(3)?
> 
> "7.21.2.4 The strncpy function"
> 
> "269) Thus, if there is no null character in the first n characters of the array pointed to by s2, the result will
> not be null-terminated."

What ISO C has said and continues to say about strncpy(3) is the actual
harmful stuff, which has led many programmers to believe strncpy(3) was
useful at all for producing strings.

The problem I see with what ISO C says about strncpy(3) is that it
treats it as a string-copying function.  If you treat strncpy(3) as a
string-copying function, then it is really broken and should be removed
from libc.

However, its functionality is still useful for those cases where you
don't want a string, which is the only reason I didn't mark the function
as [[deprecated]].

> 
> Note, I'm not using strncpy myself, it's a documentation clarification proposal.

I think it could be useful to add a note that one should first read the
CAVEATS section and string_copying(7) and only then read this page.


diff --git a/man3/stpncpy.3 b/man3/stpncpy.3
index 239a2eb7e..c7bb79028 100644
--- a/man3/stpncpy.3
+++ b/man3/stpncpy.3
@@ -37,6 +37,12 @@ .SH SYNOPSIS
         _GNU_SOURCE
 .fi
 .SH DESCRIPTION
+.IR Note :
+These functions are probably not what you want.
+Read CAVEATS below,
+and
+.BR string_copying (7).
+.PP
 These functions copy the string pointed to by
 .I src
 into a null-padded character sequence at the fixed-width buffer pointed to by


Is this scary enough?  Do you think this would tell readers to never use
this function unless they know what they're doing (and even when they
think they do, they probably don't)?

Cheers,
Alex

> 
> Kind regards
> Jonny

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

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