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

[Alejandro Colomar <alx@kernel.org>]

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

[CC += Doug]

Hi Mark,

Thanks for the feedback!  See below for comments.

On 2026-07-02T22:03:05-0700, Mark Harris wrote:
> Alejandro Colomar wrote:
> >
> > Reported-by: "Serge E. Hallyn" <serge@hallyn.com>
> > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > ---
> >
> > Hi Serge,
> >
> > I finally took some time to do this that you asked me to do some time
> > ago.  I've edited all the str*(3) manual pages so that the NAME section
> > actually explains the name of the function.
> >
> > There's an exception: strpbrk(3).  I refuse to explain that name.  I've
> > explained it as if it were called strchrs(), which is a name that Plan9
> > uses for that function, and which would have been a better name for it.
> > (See patch 2/2).
> >
> >
> > Have a lovely day!
> > Alex
> >
> >  man/man3/strcasecmp.3 | 2 +-
> >  man/man3/strchr.3     | 2 +-
> >  man/man3/strcmp.3     | 2 +-
> >  man/man3/strcoll.3    | 2 +-
> >  man/man3/strcpy.3     | 2 +-
> >  man/man3/strdup.3     | 2 +-
> >  man/man3/strerror.3   | 5 +++--
> >  man/man3/strfmon.3    | 2 +-
> >  man/man3/strfromd.3   | 3 +--
> >  man/man3/strfry.3     | 2 +-
> >  man/man3/strftime.3   | 2 +-
> >  man/man3/string.3     | 5 +----
> >  man/man3/strlen.3     | 2 +-
> >  man/man3/strncat.3    | 5 +----
> >  man/man3/strnlen.3    | 2 +-
> >  man/man3/strpbrk.3    | 2 +-
> >  man/man3/strptime.3   | 2 +-
> >  man/man3/strsep.3     | 2 +-
> >  man/man3/strsignal.3  | 2 +-
> >  man/man3/strspn.3     | 2 +-
> >  man/man3/strtod.3     | 2 +-
> >  man/man3/strtoimax.3  | 2 +-
> >  man/man3/strtok.3     | 2 +-
> >  man/man3/strtol.3     | 2 +-
> >  man/man3/strtoul.3    | 2 +-
> >  man/man3/strverscmp.3 | 2 +-
> >  man/man3/strxfrm.3    | 2 +-
> >  27 files changed, 29 insertions(+), 35 deletions(-)
> >
> > diff --git a/man/man3/strcasecmp.3 b/man/man3/strcasecmp.3
> > index aa554341da4c..65941ddf6524 100644
> > --- a/man/man3/strcasecmp.3
> > +++ b/man/man3/strcasecmp.3
> > @@ -6,7 +6,7 @@
> >  .\"
> >  .TH strcasecmp 3 (date) "Linux man-pages (unreleased)"
> >  .SH NAME
> > -strcasecmp, strncasecmp \- compare two strings ignoring case
> > +strcasecmp, strncasecmp \- strings case-insensitive compare
> >  .SH LIBRARY
> >  Standard C library
> >  .RI ( libc ,\~ \-lc )

[...]

> > diff --git a/man/man3/strspn.3 b/man/man3/strspn.3
> > index fe4414317df6..7c85d209c59d 100644
> > --- a/man/man3/strspn.3
> > +++ b/man/man3/strspn.3
> > @@ -6,7 +6,7 @@
> >  .\"
> >  .TH strspn 3 (date) "Linux man-pages (unreleased)"
> >  .SH NAME
> > -strspn, strcspn \- get length of a prefix substring
> > +strspn, strcspn \- string [complementary] span
> >  .SH LIBRARY
> >  Standard C library
> >  .RI ( libc ,\~ \-lc )

[...]

> > diff --git a/man/man3/strxfrm.3 b/man/man3/strxfrm.3
> > index d4ac57006eb0..a892bf4c813b 100644
> > --- a/man/man3/strxfrm.3
> > +++ b/man/man3/strxfrm.3
> > @@ -6,7 +6,7 @@
> >  .\"
> >  .TH strxfrm 3 (date) "Linux man-pages (unreleased)"
> >  .SH NAME
> > -strxfrm \- string transformation
> > +strxfrm \- string transform
> >  .SH LIBRARY
> >  Standard C library
> >  .RI ( libc ,\~ \-lc )
> > --
> > 2.53.0
> >
> 
> The text after the \- is documented as a "summary-description", and
> many users and tools (including man -k, apropos, and whatis) rely on
> this.

I thought precisely about whatis(1) when doing this.  Here's what
whatis(1) shows after this change (and a similar one for mem*(3)):

	$ find man/man3/ -type f \
	| grep -e/mem -e/str \
	| xargs basename -s.3 \
	| xargs whatis \
	| grep '(3)' \
	| sort;
	memalign (3)         - memory aligned allocate
	memccpy (3)          - memory until-and-including-character copy
	memchr (3)           - memory search character
	memcmp (3)           - memory compare
	memcpy (3)           - memory copy
	memeq (3)            - memory equal
	memfrob (3)          - memory frobnicate (obfuscate)
	memmem (3)           - memory search submemory
	memmove (3)          - memory move
	mempcpy (3)          - memory return-offset-pointer copy
	memrchr (3)          - memory rear-search character
	memset (3)           - memory set
	strcasecmp (3)       - strings case-insensitive compare
	strcasestr (3)       - string case-insensitive search substring
	strcat (3)           - string copy/catenate
	strchr (3)           - string search character
	strchrnul (3)        - string search character or NUL
	strcmp (3)           - strings compare
	strcoll (3)          - strings collate
	strcpy (3)           - string copy/catenate
	strcspn (3)          - string [complementary] span
	strdup (3)           - string duplicate
	strdupa (3)          - string duplicate using alloca
	streq (3)            - strings equal
	strerror (3)         - string error-string
	strerror_l (3)       - string error-string
	strerror_r (3)       - string error-string
	strerrordesc_np (3)  - string error-string
	strerrorname_np (3)  - string error-string
	strfmon (3)          - string format monetary value
	strfmon_l (3)        - string format monetary value
	strfromd (3)         - string from float
	strfromf (3)         - string from float
	strfroml (3)         - string from float
	strfry (3)           - string fry (obfuscate)
	strftime (3)         - string format date and time
	strftime_l (3)       - string format date and time
	string (3)           - byte operations
	strlen (3)           - string length
	strncasecmp (3)      - strings case-insensitive compare
	strncat (3)          - nonstring catenate
	strncmp (3)          - strings compare
	strncpy (3)          - fill a fixed-size buffer with non-null bytes from a st...
	strndup (3)          - string duplicate
	strndupa (3)         - string duplicate using alloca
	strnlen (3)          - nonstring length
	strnul (3)           - string search NUL
	strpbrk (3)          - string search characters
	strptime (3)         - string parse time
	strrchr (3)          - string rear-search character
	strsep (3)           - string separate
	strsignal (3)        - string signal description
	strspn (3)           - string [complementary] span
	strstr (3)           - string search substring
	strtod (3)           - string to float
	strtof (3)           - string to float
	strtoimax (3)        - string to [u]intmax_t
	strtok (3)           - string tokenize
	strtok_r (3)         - string tokenize reentrant
	strtol (3)           - string to long int
	strtold (3)          - string to float
	strtoll (3)          - string to long int
	strtoq (3)           - string to long int
	strtoul (3)          - string to unsigned long int
	strtoull (3)         - string to unsigned long int
	strtoumax (3)        - string to [u]intmax_t
	strtouq (3)          - string to unsigned long int
	strverscmp (3)       - strings version compare
	strxfrm (3)          - string transform

As an example of how I think this is useful, I learnt the difference
between strftime(3) and strptime(3) while doing this change.  The
ethymology of the name was the key to understanding it.  strftime(3) is
for _formatting_ a string, while strptime(3) is for _parsing_ from a
string; I'll never forget that.  Before, I knew one of them was for
reading from a string, and the other for writing to a string, but never
remembered which is which, so I had to consult the page every time.

>  Repeating the function name in a slightly more expanded form is
> not only contrary to what users expect, but is much less useful than a
> proper summary description.  In most cases the new text does not
> provide the summary that users expect from tools like man -k, is
> inconsistent with other summaries that might be shown by man -k, and
> is not even grammatically correct, making it needlessly difficult to
> interpret as a summary or contrast with other summaries to determine
> which of several matching functions is desired.

I agree I wasn't entirely happy about it not being gramatically correct,
but though that maybe it's not necessary to be so.

> If an expanded form of the function name is useful, it could be added
> to the NOTES section.

I've CCd Doug McIlroy.  I'm interested in his opinion before deciding
what to do.  Anyone else reading this, please give opinions too.  I'm
still undecided.


Have a lovely day!
Alex

> 
> 
> 
>  - Mark
> 

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

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