Re: [PATCH] NULL.3def: Add documentation for NULL

[Alejandro Colomar (man-pages)]

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/