Re: the Linux man-pages as an educational tool

[Alejandro Colomar <alx@kernel.org>]

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

Hi Collin,

> Date: 2026-08-01 18:49:03-0700
> From: Collin Funk <collin.funk1@gmail.com>
>
> Alejandro Colomar <alx@kernel.org> writes:
> 
> > I'm not innovating if I say that the standards are mostly ignored.
> > Actually, I am more in the side of following the standards as much as
> > possible and appropriate (but not more) on average.
> >
> > This is just a case where educating on the current standards is done by
> > 1) documenting at the bottom of the manual what the standard says, and
> > 2) recommending to ignore it because it's bad.  When the standards are
> > bad, this is appropriate course.
> 
> But myself and likely many others who have commented on this thread do
> not agree that strings.h is a bad name. Or that general memory related
> functions, which are used on strings a large portion of the time, need a
> separate header.

This is an opinion, which I respect, but don't agree with.

The vocal many people with that opinion have had 37 years to show how
the solution to string handling bugs was a different one.

I've done my research, and am convinced that this is an unintrusive
partial solution.  As the ultimate responsible of this documentation
project, I'll commit to this solution.  Time will tell whether I am
wrong.  I think string handling is already so messed in people's heads,
that at worst this solution won't do any noticeable good or bad, and at
best it might put an end to the problem.

> In one of your original messages you mentioned the following:
> 
> > The standard mixes functions for handling strings, functions for
> > handling bytes, and other hybrids, all in a single header file:
> > <string.h>.
> >
> > This has historically caused confusion, for example leading to believe
> > that strncpy(3) is appropriate to handle strings.
> 
> Then, in another you said:
> 
> > I find that an acceptable result.  #include's aren't that important.
> > When reading code, the section of #include's is unimportant as long as
> > it works.
> 
> If I concede that "#include's aren't that important",

That sentence was in context.  #include's aren't that important in code.
They are important in documentation and education (as I replied to
Paul).

> then strncpy still
> exists and still looks like a function that should be used on
> strings.

The documentation part (including the global header classification,
which appears in the SYNOPSIS) is what makes (or should make) it not
look like a function that should be used on strings.

The name should also be part of that, but that ship sailed.  We could
actually also attempt at fixing the name, like the Linux kernel has
done, but that's a different topic.

> So, we have still have the same problem unaddressed, right?
> People will still use the function and write bugs.
> 
> > The manual pages should certainly educate about reality, and standards
> > are only secondary to that.
> 
> The current reality and standards are fully in alignment here. memcpy et
> al. have been defined in string.h since before I was born.

And they have also been defined in <memory.h> since before you and I
were born.

> Anyone who
> knows of memory.h knows that they can just do s/memory/string/ and make
> their code look more recent. Anyone who doesn't know about memory.h will
> be confused why the man-pages tell them to use a different header than
> they have used for decades.

That's why I've documented the reason in memory.h(3head).

> New programmers will follow those
> instructions and find their code breaks on illumos, when it really
> shouldn't.

I hope Illumos adds <memory.h>.  Also, I don't expect new programmers to
be exactly the kind of programmers that use Illumos.

> Collin


Have a lovely day!
Alex

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

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