Hi Ralph!
On 7/23/22 12:23, Ralph Corderoy wrote:
Hi Alejandro,
As hinted in recent mails to groff@ and linux-man@,
I'm going to inaugurate a new [sub]section for constants.
This seems a bad idea. They're quite at home in section 3.
Others disagree, with the argument that 3 is reserved for functions.
3type is already in use by systems such as Illumos, Solaris and a few
others, for types. Mirroring that for constants is a good thing; I think.
I think it should contain constants, normally represented by
object-like macros in C. But it should also contain other forms of
constants in other languages (e.g., C++'s constexpr variables), so I'm
not convinced by the name 3def.
3const was seem more in line with how you keep referring to it.
Agreed. Thanks!
I'm (very) tempted to inaugurate section 11 for this
That's seems a worse idea. They're far too trivial to deserve their own
section.
The initial page for this section is non other than NULL ;)
It seems a bit simple to be worthy of its own man page.
Oh, seemingly simple things are sometimes the most complex ones, with
interesting surprises. I've documented a few surprises of NULL that not
many programmers know, and even those that know the details could get
some help by having such a simple reminder.
I remember very well a recent discussion I had (involving mtk and a few
others) about NULL, where I was wrong about it and Michael was right
(and I like to think that I usually know very well those kinds of little
language-lawyer details). The discussion would have been resolved
immediately by just consulting NULL(3const).
+.TH NULL 3def 2022-07-22 Linux "Linux Programmer's Manual"
+.SH NAME
+NULL \- null pointer constant
It's one of them. An integer constant expression with the value 0 is
also a null pointer constant.
Yup; I forgot to document that detail. Will add for v2.
+.SH SYNOPSIS
+.nf
+.B "#define NULL ((void *) 0)"
Does the reader need to know the definition of a macro?
Normally, I'd put a placeholder /* ... */, but in this case, POSIX is
very clear about the definition of NULL (it doesn't specify the
enclosing parentheses, but I think it's not a big deal, and glibc has
them --and I guess most sane implementation also do--).
Are you intending to do this for all macros and constants?
No. Most macros will be defined as
#define MACRO /* ... */
As I already do in int8_t(3type).
+A null pointer is one that doesn't point to a valid object.
...or function.
Thanks. I wasn't sure if I should mention that, but I'll do.
+When it is necessary to set a pointer variable to a null pointer,
+it is not enough to use
+.IR "memset(&p, 0, sizeof(p))" ,
+since ISO C and POSIX don't guarantee that a bit pattern of all
+.BR 0 s
+would represent a null pointer.
‘p = 0’ would suffice there; it may be better to give the typical case
where the pointer is part of a struct.
I didn't want to overcomplicate the example, but since that's the case
where it usually matters, I'll do.
Also, sizeof is an operator, not a function as the parenthesis and lack
of space suggest. ‘memset(&p, 0, sizeof p)’ is clearer. Perhaps you're
following some house style.
Ahh, yes, it's house style. I like the kernel coding style in that
regard. Also, ISO C seems to be making the parentheses mandatory for
new operators (e.g., _Alignas()[1]), so I prefer using parens here.
[1]:
<https://www.open-std.org/JTC1/SC22/WG14/www/docs/n2731.pdf#subsection.6.7.5>
+.SH SEE ALSO
+.BR memset (3),
+.BR void (3type)
More importantly, see also stddef.h(0p), as the man page hasn't yet told
me how to obtain NULL's definition. Am I to copy the definition into my
code?
Yup, I forgot to put #include <stddef.h> in the SYNOPSIS; that's already
fixed in my working copy. I think it's not necessary to add the header
to SEE ALSO, having it in the SYNOPSIS. I also removed memset from SEE
ALSO, since it's not really a related function, and mentioning the thing
in BUGS is enough. So SEE ALSO is only void(3type) now.
POSIX has a man page per standard header; that seems a good level to
cover all the little things which each header file is defined to
provide.
Well, stddef.h(0p) doesn't cover many of the interesting details covered
by this page, so I guess I showed some of the reasons to have such a
separate page. Having stddef.h(0) document all of those details would
make it unreadable.
If you really want to create work, consider a man page which
tables NULL, EOF, etc., and the header-file man-page to read.
I'm not sure EOF has much relation with NULL to put it in the same page.
But it certainly is one important macro to document next, since it's
very often misused.
Thanks for your thorough review!
Cheers,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
