Re: the Linux man-pages as an educational tool

[Alejandro Colomar <alx@kernel.org>]

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

Hi Collin,

> Date: 2026-08-01 18:04:05-0700
> From: Collin Funk <collin.funk1@gmail.com>
>
> Alejandro Colomar <alx@kernel.org> writes:
> 
> >> I'd like to underscore this point.  As I noted in my response to Doug,
> >> the flagship book on C, as we all know, is stuck in 1988.  The throne is
> >> vacant, with many pretenders, some with excellent cases for service as
> >> regent.
> >
> > In fact, the throne might currently fall in the Linux man-pages project.
> > While not being a blood heir of the Unix standards, it has become a
> > de-facto standard.
> 
> I don't think anyone is arguing whether or not man-pages is an
> educational tool. The argument is whether it should educate based on
> current standards, or the maintainers preferences.

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.

The manual pages should certainly educate about reality, and standards
are only secondary to that.

This reminds me of realloc(3).  That's a perfect example of educating
based on current (and withdrawn) standards.  And the education might
very well consist of saying "don't listen to the standards in this case;
they're bad for you".

I expect we'll be able to fix realloc(p,0) eventually, and Microsoft is
working with me on that.


STANDARDS
	...

   realloc(p, 0)
     The  behavior of realloc(p, 0) in glibc doesn’t conform to
     any of C99, C11, POSIX.1‐2001, POSIX.1‐2004, POSIX.1‐2008,
     POSIX.1‐2013,  POSIX.1‐2017,  or  POSIX.1‐2024.   The  C17
     specification  was changed to make it conforming, but that
     specification made it impossible to write code that  reli‐
     ably  determines if the input pointer is freed after real‐
     loc(p, 0), and C23 changed it again to make this undefined
     behavior, acknowledging that  the  C17  specification  was
     broad enough, so that undefined behavior wasn’t worse than
     that.

     reallocarray() suffers the same issues in glibc.

     musl  libc  and  the BSDs conform to all versions of ISO C
     and POSIX.1.

     gnulib provides the realloc‐posix module,  which  provides
     wrappers  realloc() and reallocarray() that conform to all
     versions of ISO C and POSIX.1.

     There’s a proposal to standardize the BSD behavior: https:
     //www.open-std.org/jtc1/sc22/wg14/www/docs/n3621.txt.

HISTORY
	...

   realloc(p, 0)
     C89 was ambiguous in its specification of  realloc(p,  0).
     C99 partially fixed this.

     The  original implementation in glibc would have been con‐
     forming to C99.  However, and ironically, trying to comply
     with C99 before the standard was released,  glibc  changed
     its  behavior  in glibc 2.1.1 into something that ended up
     not conforming to the final C99 specification (but this is
     debated, as the wording of the standard seems self‐contra‐
     dicting).

...

BUGS
     Programmers  would  naturally  expect  by  induction  that
     realloc(p, size)  is  consistent  with  free(p)  and  mal‐
     loc(size),  as  that  is the behavior in the general case.
     This is not explicitly required by  POSIX.1‐2024  or  C11,
     but  all  conforming  implementations  are consistent with
     that.

     The glibc implementation of realloc()  is  not  consistent
     with  that,  and as a consequence, it is dangerous to call
     realloc(p, 0) in glibc.

     A  trivial  workaround  for  glibc  is   calling   it   as
     realloc(p, size?size:1).

     The  workaround for reallocarray() in glibc ——which shares
     the         same          bug——          would          be
     reallocarray(p, n?n:1, size?size:1).


Have a lovely night!
Alex

> 
> Collin

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

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