Re: [PATCH v2 1/4] man/man3/str*.3: NAME: Explain the names

Alejandro Colomar <[email protected]> Sun, 26 Jul 2026 00:09:19 +0200
Newsgroups	org.kernel.vger.linux-man
Message-ID	<amUw8ArFwmnsIKl1@devuan>
Hi Serge,

On 2026-07-24T13:52:10-0500, [email protected] wrote:
> On Wed, Jul 08, 2026 at 05:09:10PM +0200, Alejandro Colomar wrote:
> > Reported-by: "Serge E. Hallyn" <[email protected]>
> > Cc: Mark Harris <[email protected]>
> > Cc: "G. Branden Robinson" <[email protected]>
> > Cc: Douglas McIlroy <[email protected]>
> > Signed-off-by: Alejandro Colomar <[email protected]>
> 
> Most of these look good to me, just a few notes:

Thanks!

[...]
> > @@ -6,7 +6,7 @@
> >  .\"
> >  .TH strdup 3 (date) "Linux man-pages (unreleased)"
> >  .SH NAME
> > -strdup, strndup \- duplicate a string
> > +strdup, strndup \- string duplicate
> 
> string [bounded] duplicate
> maybe?

I think for consistency with the other strn*() functions, the following
would be better:

	string [nonstring] duplicate

[...]
> > @@ -6,7 +6,7 @@
> >  .\"
> >  .TH strfry 3 (date) "Linux man-pages (unreleased)"
> >  .SH NAME
> > -strfry \- randomize a string
> > +strfry \- string fry
> 
> Maybe at least 'string fry (randomize)' ?  Because while stirfry
> is amusing, it's confusing if you haven't heard it before.

Hmmm, randomize seems to generous, and one may think it is kind of
a shred(1), while it isn't.  Maybe 'string fry (reorder)'?

[...]
> > @@ -5,10 +5,7 @@
> >  .\"
> >  .TH strncat 3 (date) "Linux man-pages (unreleased)"
> >  .SH NAME
> > -strncat
> > -\-
> > -append non-null bytes from a source array to a string,
> > -and null-terminate the result
> > +strncat \- nonstring catenate
> 
> why nonstring?  The source string doesn't *have* to be a string,
> but can be, right?

Yup, it can be a string, although it would be useless (if you want
a string, you can use strcat(3)).

>  (IIRC, you define a nonstring as an array
> of given length that doesn't necessarily end in \0?  I could be
> mis-remembering)

Yes, a nonstring is a character array that doesn't necessarily end in
\0.  That's why a string is a valid nonstring, but not the other way
around.

> string bounded concatente maybe?

Nope; that's what makes people misunderstand these functions, and
confuse them with safe truncating functions (e.g., strscpy(9)).

I'll send you a copy of a paper I'm writing for the C Committee.

> I think it helps the quick association in the mind if the start
> of the string matches more closely (str).

In this specific case, it's not a good idea.  strn*() are NOT string
functions.

[...]
> > @@ -6,7 +6,7 @@
> >  .\"
> >  .TH strnlen 3 (date) "Linux man-pages (unreleased)"
> >  .SH NAME
> > -strnlen \- determine the length of a fixed-size string
> > +strnlen \- nonstring length
> 
> string bounded length?

Nope.  It doesn't handle strings.

[...]
> > @@ -6,7 +6,7 @@
> >  .\"
> >  .TH strpbrk 3 (date) "Linux man-pages (unreleased)"
> >  .SH NAME
> > -strpbrk \- search a string for any of a set of bytes
> > +strpbrk \- string search characters
> 
> does the p stand for returning pointer?

<https://stackoverflow.com/a/501005/6872717>

People say it was "string pointer break".  It was a weird name, and
I ignore why they called it like that.  It seems to come from 4.3BSD;
blame them.  :)

I expanded it as if it were called strchrs(), which is what it should
have been called.  It's also the name used in Plan9 internally (in some
cases).


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es>
signature.asc (application/pgp-signature, 833 B)