[Top][All Lists]

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

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

From: Alejandro Colomar (man-pages)
Subject: Re: [PATCH] NULL.3def: Add documentation for NULL
Date: Sun, 24 Jul 2022 14:49:36 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.8.1

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

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"
+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.

+.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]: <>

+.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

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

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!



Alejandro Colomar
Linux man-pages comaintainer;

reply via email to

[Prev in Thread] Current Thread [Next in Thread]