Re: [PATCH v4] NULL.3const: Add documentation for NULL

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hi Branden,

On 7/26/22 17:54, G. Branden Robinson wrote:
[...relocated material for a topic shift...]

+.SH NOTES
+The following headers also provide
+.BR NULL :
+.IR <locale.h> ,
+.IR <stdio.h> ,
+.IR <stdlib.h> ,
+.IR <string.h> ,
+.IR <time.h> ,
+.IR <unistd.h> ,
+and
+.IR <wchar.h> .

Not exactly on topic (sorry), but apropos of our concurrent discussion
on man pages for constants with external linkage and data types, the
foregoing is an excellent counterexample of what I contend is good
practice: document them in the man page for the header file.

For countering that, I'd point you to tm(3type).
If I document in such detail every type and constant in <time.h>, the page will become an unreadable mess, IMO.

NULL(3const) is also a good example. stddef(0posix) has 2 lines + a blank for NULL.

Now consider a page that documents NULL, offsetof(), ptrdiff_t, size_t (all of them already documented, so you can take a look at their pages to get an idea of their docs), + wchar_t (yet undocumented).

stddef.h(0posix) is very short about them, and IMO, it's quite incomplete. But I could live with it if I had link pages to it (it would be suboptimal to my needs, but I could certainly live with it).






It is only the standard C library that avails itself of such a rampant
multiplicity of definition sites for constants.  This is of course
because of the synergy of 2 factors: (1) the library header design is
modular, and yet (2) the null pointer is ubiquitous and supports
applications in many application areas.

To me, this supports rather than undermines my argument for header file
man page contents, because as we can see here, what we've diagnosed is
really a missed opportunity to define the null pointer constant _at the
language level_ instead of relegating it to an optional feature of the
standard library which you nevertheless will have a hard time doing
without.  C programmers can code freestanding applications without
resource to the standard C library.  What are these freestanding
applications, invariably?  Operating system kernels, or machine-mode
code doing the work of an OS alongside its (presumably embedded,
microcontroller-like) function.  Are _those_ going to have a use for a
null pointer constant?  What do you think?  ;-)

What do I think?

Many blame C and Unix/Linux development because of how they've grown:
each vendor added their extensions to a "common" idea of the language and the system, often with incompatible extensions. Resulting in a huge mess, very inconsistent, and suboptimal.

I think that's the best that could possibly have happened. A sort of natural selection. I don't believe the idea that the gods K & R et al. brought us a god language and system and we humans broke it. Yes, the original language and system were good, but far from what they are now.

Then, other languages and systems have seen a more strict development, where the design was more centralized (or at least "better" thought). I can only say that I don't like them as much.

Yes, half a century after the invention of C we now kind of agree on things like NULL could be part of the language. But now it's maybe too late for that. And really, who cares? gcc implements it as if it were part of the language: <stddef.h> doesn't even exist. You could probably suggest making NULL a language keyword for the next revision of the standard, but I don't think it will get much attention. But maybe it would be a good thing...


POSIX supplements to the standard C library, and other libraries for C,
will not typically have this difficulty, and will have one definition
site only for their constants with external linkage.

Oh, no.  Check ssize_t(3type)!

Cheers,

Alex

--
Alejandro Colomar
<http://www.alejandro-colomar.es/>

Attachment: OpenPGP_signature
Description: OpenPGP digital signature


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux