Skip to contentSkip to conversation

NULL.3def: Add documentation for NULL

PATCH In review Alejandro Colomar 5 participants 16 messages Jul 22, 2022 – Jul 28, 2022 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 NULL.3def: Add documentation for NULL

---

Hi all!

As hinted in recent mails to groff@ and linux-man@, I'm going to inaugurate a new [sub]section for constants.

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.

I'm (very) tempted to inaugurate section 11 for this, following standard practice of getting a higher number for something not similar to anything else currently documented. That would mean that section 10 would accomodate what now is in 3type, which also doesn't entirely fit section 3.

But for this initial discussion, I kept it in section 3def temporarily.

The initial page for this section is non other than NULL ;)

Cheers,

Alex

 man3def/NULL.3def | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 man3def/NULL.3def
man3def/NULL.3def new file +43 -0
new file mode 100644
index 000000000..a1dec28c2
@@ -0,0 +1,43 @@
+.\" Copyright (c) 2022 by Alejandro Colomar <[email protected]>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.TH NULL 3def 2022-07-22 Linux "Linux Programmer's Manual"
+.SH NAME
+NULL \- null pointer constant
+.SH SYNOPSIS
+.nf
+.B "#define NULL  ((void *) 0)"
+.fi
+.SH DESCRIPTION
+.B NULL
+represents a null pointer constant.
+.PP
+According to POSIX,
+it shall expand to an integer constant expression with the value
+.B 0
+cast to type
+.IR "void *" .
+.PP
+A null pointer is one that doesn't point to a valid object.
+.SH CONFORMING TO
+C99 and later.
+POSIX.1-2001 and later.
+.SH NOTES
+It is undefined behavior to try to dereference a null pointer
+or to perform pointer arithmetics on it:
+.I NULL \- NULL
+is, surprisingly, undefined behavior, according to ISO C.
+.SH BUGS
+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.
+Instead, pointer variables need to be explicitly set to a null pointer
+when they need to hold a null pointer.
+.SH SEE ALSO
+.BR memset (3),
+.BR void (3type)
Signature · 1 line
2.36.1
#1 lore raw

Hi Alejandro,

Quoted 2 lines

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.

Quoted 4 lines

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.

Quoted 1 line

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.

Quoted 1 line

The initial page for this section is non other than NULL ;)

It seems a bit simple to be worthy of its own man page.

Quoted 3 lines

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

Quoted 3 lines

+.SH SYNOPSIS
+.nf
+.B "#define NULL ((void *) 0)"

Does the reader need to know the definition of a macro? Are you intending to do this for all macros and constants?

Quoted 1 line

+A null pointer is one that doesn't point to a valid object.

...or function.

man3def/NULL.3def line 38

Quoted 6 lines
man3def/NULL.3def new file +6 -0
+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.

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.

Quoted 3 lines

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

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. If you really want to create work, consider a man page which tables NULL, EOF, etc., and the header-file man-page to read.

Signature · 1 line
Cheers, Ralph.
#2 lore raw

Hi Ralph!

Quoted 6 lines · Ralph Corderoy

Hi Alejandro,

Quoted 2 lines

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.

Quoted 7 lines
Quoted 5 lines

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!

Quoted 9 lines
Quoted 2 lines

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.

Quoted 1 line

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

Quoted 7 lines
Quoted 4 lines

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

Quoted 6 lines
Quoted 4 lines

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

Quoted 1 line

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

Quoted 4 lines
Quoted 2 lines

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

Quoted 10 lines

man3def/NULL.3def line 38

Quoted 7 lines
man3def/NULL.3def new file +6 -0
+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.

Quoted 4 lines

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>

Quoted 8 lines
Quoted 4 lines

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

Quoted 4 lines

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.

Quoted 3 lines

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

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#3 lore raw

PATCH 1/1 NULL.3const: Add documentation for NULL

In reply to Alejandro Colomar

---

v2:

- Move to man3const [Ralph, Branden]
- Added LIBRARY section
- Added #include [Ralph]
- Note that it can also be used as a function pointer [Ralph]
- Document that 0 is another null pointer constant [Ralph] But note that it's to be avoided by most coding standards [alx]
- Note that NULL is not NUL
- Improve wording about zeroing a pointer [Ralph]
And refer to getaddrinfo(3) for an example.
This probably can be further improved; I'm not convinced.
- Trim SEE ALSO to just void(3type)
- Other minor fixes

 man3const/NULL.3const | 70 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 man3const/NULL.3const
man3const/NULL.3const new file +70 -0
new file mode 100644
index 000000000..1b0cb7948
@@ -0,0 +1,70 @@
+.\" Copyright (c) 2022 by Alejandro Colomar <[email protected]>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.TH NULL 3const 2022-07-22 Linux "Linux Programmer's Manual"
+.SH NAME
+NULL \- null pointer constant
+.SH LIBRARY
+Standard C library
+.RI ( libc )
+.SH SYNOPSIS
+.nf
+.B #include <stddef.h>
+.PP
+.B "#define NULL  ((void *) 0)"
+.fi
+.SH DESCRIPTION
+.B NULL
+represents a null pointer constant.
+.PP
+According to POSIX,
+it shall expand to an integer constant expression with the value
+.B 0
+cast to type
+.IR "void *" .
+.PP
+A null pointer is one that doesn't point to a valid object or function.
+.SH CONFORMING TO
+C99 and later;
+POSIX.1-2001 and later.
+.SH NOTES
+It is undefined behavior to dereference a null pointer
+or to perform pointer arithmetics on it.
+.I NULL \- NULL
+is, surprisingly, undefined behavior, according to ISO C.
+.PP
+.B 0
+also represents a null pointer constant
+when used in a context where a pointer is expected.
+This is considered bad practise by most coding guidelines,
+since it can be very confusing,
+and so
+.B NULL
+is preferred.
+.PP
+.B NULL
+shouldn't be confused with
+.BR NUL ,
+which is an
+.BR ascii (7)
+character,
+represented in C as
+.BR \(aq\e0\(aq .
+.SH BUGS
+When it is necessary to set a pointer variable to a null pointer,
+it is not enough to use
+.BR memset (3)
+to zero the pointer
+(this is usually done when zeroing a struct that contains pointers),
+since ISO C and POSIX don't guarantee that a bit pattern of all
+.BR 0 s
+would represent a null pointer.
+Instead, pointer variables need to be explicitly set to a null pointer
+when they need to hold a null pointer.
+See the EXAMPLES section in
+.BR getaddrinfo (3)
+for an example program that does this.
+.SH SEE ALSO
+.BR void (3type)
Signature · 1 line
2.36.1
#4 lore raw

PATCH v3 1/1 NULL.3const: Add documentation for NULL

In reply to Alejandro Colomar

---

v2:

- Move to man3const [Ralph, Branden]
- Added LIBRARY section
- Added #include [Ralph]
- Note that it can also be used as a function pointer [Ralph]
- Document that 0 is another null pointer constant [Ralph] But note that it's to be avoided by most coding standards [alx]
- Note that NULL is not NUL
- Improve wording about zeroing a pointer [Ralph]
And refer to getaddrinfo(3) for an example.
This probably can be further improved; I'm not convinced.
- Trim SEE ALSO to just void(3type)
- Other minor fixes

v3:

- Don't boldface 0s, since it doesn't refer to the literal constant 0, but to the bit pattern of 0s.
- Add list of headers that also define NULL (per POSIX.1-2008).

 man3const/NULL.3const | 80 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 man3const/NULL.3const
man3const/NULL.3const new file +80 -0
new file mode 100644
index 000000000..730f670fe
@@ -0,0 +1,80 @@
+.\" Copyright (c) 2022 by Alejandro Colomar <[email protected]>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.TH NULL 3const 2022-07-22 Linux "Linux Programmer's Manual"
+.SH NAME
+NULL \- null pointer constant
+.SH LIBRARY
+Standard C library
+.RI ( libc )
+.SH SYNOPSIS
+.nf
+.B #include <stddef.h>
+.PP
+.B "#define NULL  ((void *) 0)"
+.fi
+.SH DESCRIPTION
+.B NULL
+represents a null pointer constant.
+.PP
+According to POSIX,
+it shall expand to an integer constant expression with the value
+.B 0
+cast to type
+.IR "void *" .
+.PP
+A null pointer is one that doesn't point to a valid object or function.
+.SH CONFORMING TO
+C99 and later;
+POSIX.1-2001 and later.
+.SH NOTES
+It is undefined behavior to dereference a null pointer
+or to perform pointer arithmetics on it.
+.I NULL \- NULL
+is, surprisingly, undefined behavior, according to ISO C.
+.PP
+.B 0
+also represents a null pointer constant
+when used in a context where a pointer is expected.
+This is considered bad practise by most coding guidelines,
+since it can be very confusing,
+and so
+.B NULL
+is preferred.
+.PP
+.B NULL
+shouldn't be confused with
+.BR NUL ,
+which is an
+.BR ascii (7)
+character,
+represented in C as
+.BR \(aq\e0\(aq .
+.PP
+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> .
+.SH BUGS
+When it is necessary to set a pointer variable to a null pointer,
+it is not enough to use
+.BR memset (3)
+to zero the pointer
+(this is usually done when zeroing a struct that contains pointers),
+since ISO C and POSIX don't guarantee that a bit pattern of all 0s
+would represent a null pointer.
+Instead, pointer variables need to be explicitly set to a null pointer
+when they need to hold a null pointer.
+See the EXAMPLES section in
+.BR getaddrinfo (3)
+for an example program that does this.
+.SH SEE ALSO
+.BR void (3type)
Signature · 1 line
2.36.1
#5 lore raw

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

Hi Alejandro,

Alejandro Colomar wrote on Sun, Jul 24, 2022 at 09:19:32PM +0200:

Quoted 42 lines

- Move to man3const [Ralph, Branden]
- Added LIBRARY section
- Added #include [Ralph]
- Note that it can also be used as a function pointer [Ralph]
- Document that 0 is another null pointer constant [Ralph] But note that it's to be avoided by most coding standards [alx]
- Note that NULL is not NUL
- Improve wording about zeroing a pointer [Ralph]
And refer to getaddrinfo(3) for an example.
This probably can be further improved; I'm not convinced.
- Trim SEE ALSO to just void(3type)
- Other minor fixes

v3:

- Don't boldface 0s, since it doesn't refer to the literal constant 0, but to the bit pattern of 0s.
- Add list of headers that also define NULL (per POSIX.1-2008).

 man3const/NULL.3const | 80 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 man3const/NULL.3const
man3const/NULL.3const new file +12 -0
new file mode 100644
index 000000000..730f670fe
@@ -0,0 +1,80 @@
+.\" Copyright (c) 2022 by Alejandro Colomar <[email protected]>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.TH NULL 3const 2022-07-22 Linux "Linux Programmer's Manual"
+.SH NAME
+NULL \- null pointer constant
+.SH LIBRARY
+Standard C library
+.RI ( libc )
+.SH SYNOPSIS

man3const/NULL.3const line 22

Quoted 10 lines
man3const/NULL.3const new file +10 -0
+.nf
+.B #include <stddef.h>
+.PP
+.B "#define NULL  ((void *) 0)"
+.fi
+.SH DESCRIPTION
+.B NULL
+represents a null pointer constant.
+.PP
+According to POSIX,

That phrase is misplaced in the DESCRIPTION.
In belongs into STANDARDS.

Not littering the DESCRIPTION with misplaced information is particular important in the first two sentences, because that's the first point of contact for the user where they are likely trying to figure out what the basic idea of the thing is, and whether they are even looking at the right manual page.

man3const/NULL.3const line 23

Quoted 1 line
man3const/NULL.3const new file +1 -0
+it shall expand to an integer constant expression with the value

Using the word "shall" in a manual page is usually terrible style. Here, it is misleading on top of that because it is unrelated to anything the user might be expected to do or not do.

A manual page is neither a standard document formally defining the language nor a guideline for compiler authors.

Considering this sentence in isolation, what you want to say is:

The macro
.B NULL
expands to the integer number 0 cast to the type .IR "void *" .

But you are violating an important guideline for writing manual
pages: avoid useless verbosity, don't say the same thing twice. Here, you are saying exactly the same *three times*: in the SYNOPSIS, in the first sentence of the DESCRIPTION, and in the second sentence of the DESCRIPTION.

Consequently, i suggest deleting the second sentence with no replacement.

man3const/NULL.3const line 24

Quoted 1 line
man3const/NULL.3const new file +1 -0
+.B 0

There is really no need to mark up integer constants.

man3const/NULL.3const line 25

Quoted 1 line
man3const/NULL.3const new file +1 -0
+cast to type

Bad grammar: s/to type/to the type/.

man3const/NULL.3const line 28

Quoted 3 lines
man3const/NULL.3const new file +3 -0
+.IR "void *" .
+.PP
+A null pointer is one that doesn't point to a valid object or function.

That sounds like an afterthought, which is always bad in documentation. If you think the first sentence is too vague, integrate this information into the first sentence, where it obviously belongs. Besides, this wording is misleading: it sounds as if NULL might be pointing to an invalid object.

I guess what you mean is:

.B NULL
represents a null pointer constant, that is, a pointer that does not point to anything.

man3const/NULL.3const line 29

Quoted 1 line
man3const/NULL.3const new file +1 -0
+.SH CONFORMING TO

That should be ".SH STANDARDS".

man3const/NULL.3const line 32

Quoted 3 lines
man3const/NULL.3const new file +3 -0
+C99 and later;
+POSIX.1-2001 and later.
+.SH NOTES

I throughly hate this section. It is almost always an indication that the organization of the page wasn't properly thought through and random afterthoughts were dumped here.

man3const/NULL.3const line 33

Quoted 1 line
man3const/NULL.3const new file +1 -0
+It is undefined behavior to dereference a null pointer

That is formally true, but hardly helpful in a manual page because what happens when you dereference a NULL pointer is faily predictable in practice: a segmentation fault.

Any other behaviour of the C language implementation would be such a massive security risk that i don't think even the most avid compiler optimizer would seriously consider it. According to my practical experience, NULL pointer accesses are among the most frequent bugs, easily 20-50% of all bugs the can be found by fuzzing real-world code. Having the C language do anything else than segfault, for example continue execution with invalid or uninitialized data, would turn huge numbers of fairly harmless bugs into potentially exploitable security vulnerabilities. Using my experience, off the top my head, i would estimate that *not* segfaulting on NULL pointer accesses would, in a typical codebase, increase the number of potentially exploitable vulnerabilities by roughly one power of ten.

So, if you want to be helpful to the reader, you should say something like:

While dereferencing a NULL pointer is formally undefined behaviour, it almost certainly causes a segmentation fault in practice.

man3const/NULL.3const line 34

Quoted 1 line
man3const/NULL.3const new file +1 -0
+or to perform pointer arithmetics on it.

Sure.

man3const/NULL.3const line 36

Quoted 2 lines
man3const/NULL.3const new file +2 -0
+.I NULL \- NULL
+is, surprisingly, undefined behavior, according to ISO C.

Saying that is completely useless. Please delete this sentence.

On the one hand, it is irrelevant because nobody in their right mind would do that in the first place. A manual page is not the place to enumerate weird and unusual ways how something can *not* be used. Its purpose is to explain proper usage.

Besides, this is already obvious without saying it; it is not surprising in the least. Pointer subtraction is only defined for pointers *into the same object*, and you already said that NULL pointers are not pointing to an object.

man3const/NULL.3const line 40

Quoted 4 lines
man3const/NULL.3const new file +4 -0
+.PP
+.B 0
+also represents a null pointer constant
+when used in a context where a pointer is expected.

That is also completely irrelevant because you already told the user about a better way to create a NULL pointer. Why digress into explaining another, no so good way? On top of that, taking the SYNOPSIS and standard type coercion rules together, the content of this sentence is already blazingly obvious:
If an explicit cast (void *)0 yields a NULL pointer, then it is clear the the implicit coercion "void *p = 0;" can only have the same result.

man3const/NULL.3const line 45

Quoted 5 lines
man3const/NULL.3const new file +5 -0
+This is considered bad practise by most coding guidelines,
+since it can be very confusing,
+and so
+.B NULL
+is preferred.

You do have a minor point here, but all the same, i doubt that coding style belongs in a manual page, except when it has security implications. In that case, it might be appropriate for the CAVEATS section. If you think this matters for security, you might for example say:

.SH CAVEATS
To avoid confusing human readers of the code, do not compare pointer variables to 0 and do not assign 0 to them. Instead, always use
.BR NULL .

man3const/NULL.3const line 54

Quoted 9 lines
man3const/NULL.3const new file +9 -0
+.PP
+.B NULL
+shouldn't be confused with
+.BR NUL ,
+which is an
+.BR ascii (7)
+character,
+represented in C as
+.BR \(aq\e0\(aq .

That definitely belongs in the CAVEATS section.

man3const/NULL.3const line 65

Quoted 11 lines
man3const/NULL.3const new file +11 -0
+.PP
+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> .

If you think that matters, just put it at the end of the DESCRIPTION, which is very short anyway.

But usually, i see no need for dwelling on such technicalities. No harm is done if inexperienced users include <stddef.h>, too, and experienced users can look up such technicalities in the standard if they really need them, which happens rarely even for professionals.

man3const/NULL.3const line 66

Quoted 1 line
man3const/NULL.3const new file +1 -0
+.SH BUGS

The following is misplaced in BUGS. It is not talking about any bug, nor about any API design defect.

If you consider memset of a struct containing pointer members as unsafe, the section to say so would be CAVEATS because it would then be considered as a user error, and CAVEATS is the section to warn users about typical misuse of the API.

It seems in theory, you are correct that

  struct s {
  	void *p;
  };
  s.p = 0;

is guaranteed to set p to NULL whereas

  memset(&s, 0, sizeof(s));

is not. It's not hugely important though as i doubt that you will be able to find a system in practice where the latter fails, and if a future platform would decide to let the latter fail, that would break such huge amounts of existing code it would not really be sustainable for the manufacturer of that hypothetical future system.

man3const/NULL.3const line 78

Quoted 12 lines
man3const/NULL.3const new file +12 -0
+When it is necessary to set a pointer variable to a null pointer,
+it is not enough to use
+.BR memset (3)
+to zero the pointer
+(this is usually done when zeroing a struct that contains pointers),
+since ISO C and POSIX don't guarantee that a bit pattern of all 0s
+would represent a null pointer.
+Instead, pointer variables need to be explicitly set to a null pointer
+when they need to hold a null pointer.
+See the EXAMPLES section in
+.BR getaddrinfo (3)
+for an example program that does this.

That example can also be improved in two respects.

First, and less importantly,

  memset(&hints, 0, sizeof(hints));

is less error prone, more readable, and shorter than

  memset(&hints, 0, sizeof(struct addrinfo));

More importantly, it is not good style to first memset the struct as a whole and then individual fields like

  hints.ai_flags = 0;
  hints.ai_protocol = 0;

to zero right afterwards. You should either (preferably, because that also clears any padding) memset and then only set the fields you want to be non-0, or set all fields individually, but not both.

Yours,
Ingo

#6 lore raw

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

Hi Ingo,

Quoted 51 lines · Ingo Schwarze

Hi Alejandro,

Alejandro Colomar wrote on Sun, Jul 24, 2022 at 09:19:32PM +0200:

Quoted 47 lines

- Move to man3const [Ralph, Branden]
- Added LIBRARY section
- Added #include [Ralph]
- Note that it can also be used as a function pointer [Ralph]
- Document that 0 is another null pointer constant [Ralph] But note that it's to be avoided by most coding standards [alx]
- Note that NULL is not NUL
- Improve wording about zeroing a pointer [Ralph]
And refer to getaddrinfo(3) for an example.
This probably can be further improved; I'm not convinced.
- Trim SEE ALSO to just void(3type)
- Other minor fixes

v3:

- Don't boldface 0s, since it doesn't refer to the literal constant 0, but to the bit pattern of 0s.
- Add list of headers that also define NULL (per POSIX.1-2008).

  man3const/NULL.3const | 80 +++++++++++++++++++++++++++++++++++++++++++
  1 file changed, 80 insertions(+)

create mode 100644 man3const/NULL.3const

man3const/NULL.3const new file +17 -0
new file mode 100644
index 000000000..730f670fe
@@ -0,0 +1,80 @@
+.\" Copyright (c) 2022 by Alejandro Colomar <[email protected]>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.TH NULL 3const 2022-07-22 Linux "Linux Programmer's Manual"
+.SH NAME
+NULL \- null pointer constant
+.SH LIBRARY
+Standard C library
+.RI ( libc )
+.SH SYNOPSIS
+.nf
+.B #include <stddef.h>
+.PP
+.B "#define NULL  ((void *) 0)"
+.fi
Quoted 8 lines

man3const/NULL.3const line 22

Quoted 5 lines
man3const/NULL.3const new file +5 -0
+.SH DESCRIPTION
+.B NULL
+represents a null pointer constant.
+.PP
+According to POSIX,

That phrase is misplaced in the DESCRIPTION.
In belongs into STANDARDS.

I moved it to VERSIONS, since Jakub correctly pointed that this is something that was introduced in POSIX.1-2008.

I also considered removing it completely, though.

Quoted 6 lines

Not littering the DESCRIPTION with misplaced information is particular important in the first two sentences, because that's the first point of contact for the user where they are likely trying to figure out what the basic idea of the thing is, and whether they are even looking at the right manual page.

Agreed.

Quoted 9 lines

man3const/NULL.3const line 23

Quoted 2 lines
man3const/NULL.3const new file +1 -0
+it shall expand to an integer constant expression with the value

Using the word "shall" in a manual page is usually terrible style. Here, it is misleading on top of that because it is unrelated to anything the user might be expected to do or not do. > A manual page is neither a standard document formally defining the language nor a guideline for compiler authors.

Quoted 6 lines

Considering this sentence in isolation, what you want to say is:

The macro
.B NULL
expands to the integer number 0 cast to the type .IR "void *" .

Makes sense; I reworded.

Quoted 9 lines

But you are violating an important guideline for writing manual
pages: avoid useless verbosity, don't say the same thing twice. Here, you are saying exactly the same *three times*: in the SYNOPSIS, in the first sentence of the DESCRIPTION, and in the second sentence of the DESCRIPTION.

Consequently, i suggest deleting the second sentence with no replacement.

Yeah, I'm considering removing it. Let's keep it for v4, and maybe I'll remove it after.

Quoted 4 lines

man3const/NULL.3const line 24

Quoted 2 lines
man3const/NULL.3const new file +1 -0
+.B 0

There is really no need to mark up integer constants.

groff_man_style(7):
Use bold for literal portions of syntax synopses, for command‐line options in running text, and for literals that are major topics of the subject un‐ der discussion; for example, this page uses bold for macro, string, and register names. In an .EX/.EE example of interactive I/O (such as a shell session), set only user input in bold.

Since this is a literal that is a major topic of the subject under discussion, I prefer to be a bit pedantic here and boldface it.

I guess it's no big issue; does it hurt readability too much for you?

Quoted 4 lines

man3const/NULL.3const line 25

Quoted 2 lines
man3const/NULL.3const new file +1 -0
+cast to type

Bad grammar: s/to type/to the type/.

Fixed.

Quoted 11 lines

man3const/NULL.3const line 28

Quoted 4 lines
man3const/NULL.3const new file +3 -0
+.IR "void *" .
+.PP
+A null pointer is one that doesn't point to a valid object or function.

That sounds like an afterthought, which is always bad in documentation. If you think the first sentence is too vague, integrate this information into the first sentence, where it obviously belongs. Besides, this wording is misleading: it sounds as if NULL might be pointing to an invalid object.

Quoted 5 lines

I guess what you mean is:

.B NULL
represents a null pointer constant, that is, a pointer that does not point to anything.

I prefer your wording. Fixed.

Quoted 4 lines

man3const/NULL.3const line 29

Quoted 2 lines
man3const/NULL.3const new file +1 -0
+.SH CONFORMING TO

That should be ".SH STANDARDS".

We use CONFORMING TO in Linux. Don't know why; just history, I guess. See man-pages(7).

Quoted 8 lines

man3const/NULL.3const line 32

Quoted 4 lines
man3const/NULL.3const new file +3 -0
+C99 and later;
+POSIX.1-2001 and later.
+.SH NOTES

I throughly hate this section. It is almost always an indication that the organization of the page wasn't properly thought through and random afterthoughts were dumped here.

Me too :p

Quoted 20 lines

man3const/NULL.3const line 33

Quoted 2 lines
man3const/NULL.3const new file +1 -0
+It is undefined behavior to dereference a null pointer

That is formally true, but hardly helpful in a manual page because what happens when you dereference a NULL pointer is faily predictable in practice: a segmentation fault.

Any other behaviour of the C language implementation would be such a massive security risk that i don't think even the most avid compiler optimizer would seriously consider it. According to my practical experience, NULL pointer accesses are among the most frequent bugs, easily 20-50% of all bugs the can be found by fuzzing real-world code. Having the C language do anything else than segfault, for example continue execution with invalid or uninitialized data, would turn huge numbers of fairly harmless bugs into potentially exploitable security vulnerabilities. Using my experience, off the top my head, i would estimate that *not* segfaulting on NULL pointer accesses would, in a typical codebase, increase the number of potentially exploitable vulnerabilities by roughly one power of ten.

Quoted 6 lines

So, if you want to be helpful to the reader, you should say something like:

While dereferencing a NULL pointer is formally undefined behaviour, it almost certainly causes a segmentation fault in practice.

Oh, yeah, the act of dereferencing will very likely cause the process to segfault; it seems useful info to add. Thanks!

But also, the compiler can feel too smart about it, and silently remove other portions of code that it deems useless.

I reworded it to something similar to your proposal.

Quoted 15 lines

man3const/NULL.3const line 34

Quoted 2 lines
man3const/NULL.3const new file +1 -0
+or to perform pointer arithmetics on it.

Sure.

man3const/NULL.3const line 36

Quoted 2 lines
man3const/NULL.3const new file +2 -0
+.I NULL \- NULL
+is, surprisingly, undefined behavior, according to ISO C.

Saying that is completely useless. Please delete this sentence.

On the one hand, it is irrelevant because nobody in their right mind would do that in the first place. A manual page is not the place to enumerate weird and unusual ways how something can *not* be used. Its purpose is to explain proper usage.

Quoted 4 lines

Besides, this is already obvious without saying it; it is not surprising in the least. Pointer subtraction is only defined for pointers *into the same object*, and you already said that NULL pointers are not pointing to an object.

Heh! Not so irrelevant IMO. Or maybe I'm "not in my right mind" :P

<https://github.com/nginx/unit/commit/c3e40ae932f0>

I made use of that UB in the commit linked above.

BTW, the C++ standard seems to have considered it something worth defining, and as much as I usually hate C++, this is a case where I think they did it better.

I considered even mentioning that detail about C++ in the manual page, to let users know that even if it's UB, they can probably rely on the fact that NULL - NULL == 0.

Quoted 14 lines

man3const/NULL.3const line 40

Quoted 5 lines
man3const/NULL.3const new file +4 -0
+.PP
+.B 0
+also represents a null pointer constant
+when used in a context where a pointer is expected.

That is also completely irrelevant because you already told the user about a better way to create a NULL pointer. Why digress into explaining another, no so good way? On top of that, taking the SYNOPSIS and standard type coercion rules together, the content of this sentence is already blazingly obvious:
If an explicit cast (void *)0 yields a NULL pointer, then it is clear the the implicit coercion "void *p = 0;" can only have the same result.

Hmm, yeah, maybe it's obvious in POSIX, and so I consider removing it.

But consider the broader ISO C scenario (or old POSIX.1-2001), where NULL isn't defined to be (void*)0. There it isn't so obvious that 0 would also represent a null pointer. But, yeah, I'm leaning towards ignoring ISO C when (current) POSIX is much better, and in this case, every Unix implementation uses (void*)0 (or at the very least 0), AFAIK.

Quoted 12 lines

man3const/NULL.3const line 45

Quoted 6 lines
man3const/NULL.3const new file +5 -0
+This is considered bad practise by most coding guidelines,
+since it can be very confusing,
+and so
+.B NULL
+is preferred.

You do have a minor point here, but all the same, i doubt that coding style belongs in a manual page, except when it has security implications. In that case, it might be appropriate for the CAVEATS section. If you think this matters for security, you might for example say:

I still may add a few lines in CAVEATS, yes.

Quoted 7 lines

.SH CAVEATS
To avoid confusing human readers of the code, do not compare pointer variables to 0 and do not assign 0 to them. Instead, always use
.BR NULL .

Quoted 11 lines

man3const/NULL.3const line 54

Quoted 9 lines
man3const/NULL.3const new file +9 -0
+.PP
+.B NULL
+shouldn't be confused with
+.BR NUL ,
+which is an
+.BR ascii (7)
+character,
+represented in C as
+.BR \(aq\e0\(aq .

That definitely belongs in the CAVEATS section.

Okay.

Quoted 15 lines

man3const/NULL.3const line 65

Quoted 12 lines
man3const/NULL.3const new file +11 -0
+.PP
+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> .

If you think that matters, just put it at the end of the DESCRIPTION, which is very short anyway.

Okay.

I think it matters (it matters to me, and to iwyu(1)).

Quoted 5 lines

But usually, i see no need for dwelling on such technicalities. No harm is done if inexperienced users include <stddef.h>, too, and experienced users can look up such technicalities in the standard if they really need them, which happens rarely even for professionals.

I admit the audience of that info is rather small (and I'm working on iwyu(1) to make it even smaller), but I need the info to implement iwyu(1) correctly, and I'm not going to consult the standards all the time for every symbol that I want to know where it's defined.

Quoted 5 lines

man3const/NULL.3const line 66

Quoted 2 lines
man3const/NULL.3const new file +1 -0
+.SH BUGS

The following is misplaced in BUGS. It is not talking about any bug, nor about any API design defect.

Oh, I do consider this a bug in the API design. I placed it there on purpose.

Allowing the bit pattern of all 0s to represent a valid pointer (and thus not a null pointer) is something that could be meaningful many decades ago, when architectures were more different.

Nowadays, every arch out there is 2's complement, and uses 0s as the null pointer. The standard should simplify, and allow memset(2)ing pointers.

In fact, AFAIK, the next revision of POSIX will fix that bug. But I don't remember well the details of that.

Quoted 13 lines

If you consider memset of a struct containing pointer members as unsafe, the section to say so would be CAVEATS because it would then be considered as a user error, and CAVEATS is the section to warn users about typical misuse of the API.

It seems in theory, you are correct that

   struct s {
   	void *p;
   };
   s.p = 0;
Quoted 6 lines

is guaranteed to set p to NULL whereas

   memset(&s, 0, sizeof(s));

is not. It's not hugely important though as i doubt that you will be able to find a system in practice where the latter fails, and if

You're right. All POSIX systems in existence de-facto allow memset(2).

Quoted 31 lines

a future platform would decide to let the latter fail, that would break such huge amounts of existing code it would not really be sustainable for the manufacturer of that hypothetical future system.

man3const/NULL.3const line 78

Quoted 12 lines
man3const/NULL.3const new file +12 -0
+When it is necessary to set a pointer variable to a null pointer,
+it is not enough to use
+.BR memset (3)
+to zero the pointer
+(this is usually done when zeroing a struct that contains pointers),
+since ISO C and POSIX don't guarantee that a bit pattern of all 0s
+would represent a null pointer.
+Instead, pointer variables need to be explicitly set to a null pointer
+when they need to hold a null pointer.
+See the EXAMPLES section in
+.BR getaddrinfo (3)
+for an example program that does this.

That example can also be improved in two respects.

First, and less importantly,

   memset(&hints, 0, sizeof(hints));

is less error prone, more readable, and shorter than

   memset(&hints, 0, sizeof(struct addrinfo));

More importantly, it is not good style to first memset the struct as a whole and then individual fields like

Quoted 6 lines
   hints.ai_flags = 0;
   hints.ai_protocol = 0;

to zero right afterwards. You should either (preferably, because that also clears any padding) memset and then only set the fields you want to be non-0, or set all fields individually, but not both.

Yep. I noticed when looking at it, but was a bit lazy to fix it :)

I'll come up with a new revision. Thanks for the review!

Cheers,

Alex

Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>
#7 lore raw

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

Hi Alejandro,

Alejandro Colomar wrote on Tue, Jul 26, 2022 at 02:02:56PM +0200:

Quoted 16 lines · Ingo Schwarze
Quoted 5 lines

Alejandro Colomar wrote on Sun, Jul 24, 2022 at 09:19:32PM +0200:

Quoted 1 line

+.B 0

There is really no need to mark up integer constants.

groff_man_style(7):
Use bold for literal portions of syntax synopses, for command‐line options in running text, and for literals that are major topics of the subject un‐ der discussion; for example, this page uses bold for macro, string, and register names. In an .EX/.EE example of interactive I/O (such as a shell session), set only user input in bold.

Quoted 4 lines

Since this is a literal that is a major topic of the subject under discussion, I prefer to be a bit pedantic here and boldface it.

I guess it's no big issue; does it hurt readability too much for you?

No, it's no big deal and doesn't hurt readability. It only looks slightly unusual.

There are cases where a bare '0' character needs to be bold face, for example when discussing ".Fl 0" in xargs(1). But here, you are just talking about the integer 0. The "major topic" here is ".Dv NULL", not the ordinary integer 0 that is internally used to define that constant.
Bold face is mostly for literals that the user needs to type - and the user is specifically *not* supposed to type this 0.

That's why i consider the .B pointless; then again, it does not do much harm either.

Quoted 6 lines
Quoted 3 lines
Quoted 1 line

+.SH CONFORMING TO

That should be ".SH STANDARDS".

We use CONFORMING TO in Linux. Don't know why; just history, I guess. See man-pages(7).

Weird.

I failed to find a single instance of "CONFORMING TO" in AT&T UNIX (including v6, PWB, v7, 32v, v8, v10, System III, SVR1, SVR2) nor in any version of UCB CSRG BSD. So considering that System V and BSD are widely considered the two main original branches of the development of Unix-like operating systems and Linux is often considered to have drawn inspiration from both, the section name "CONFORMING TO" does not appear to be a UNIX thing. For example, Aeleen Frisch, "Essential System Administration", O'Reilly, Cambridge 1995, considers Linux as slightly more influenced by 4.3BSD than by System V Release 3.

STANDARDS, on the other hand, is present since 4.3BSD-Reno (June 1990).

4.3BSD-Reno predates the first version of the Linux kernel by more than a year, and the first Linux manual pages probably for longer than that.

So i have no idea where "CONFORMING TO" may have come from.

[...]

Quoted 12 lines
Quoted 4 lines
Quoted 1 line

+.SH BUGS

The following is misplaced in BUGS. It is not talking about any bug, nor about any API design defect.

Oh, I do consider this a bug in the API design. I placed it there on purpose.

Allowing the bit pattern of all 0s to represent a valid pointer (and thus not a null pointer) is something that could be meaningful many decades ago, when architectures were more different.

Quoted 6 lines

Nowadays, every arch out there is 2's complement, and uses 0s as the null pointer. The standard should simplify, and allow memset(2)ing pointers.

In fact, AFAIK, the next revision of POSIX will fix that bug. But I don't remember well the details of that.

Fair points. You convinced me this isn't misplaced in BUGS.

Yours,
Ingo

#8 lore raw

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

Hi Ingo,

Quoted 27 lines · Ingo Schwarze

Hi Alejandro,

Alejandro Colomar wrote on Tue, Jul 26, 2022 at 02:02:56PM +0200:

Quoted 16 lines · Ingo Schwarze
Quoted 5 lines

Alejandro Colomar wrote on Sun, Jul 24, 2022 at 09:19:32PM +0200:

Quoted 1 line

+.B 0

There is really no need to mark up integer constants.

groff_man_style(7):
Use bold for literal portions of syntax synopses, for command‐line options in running text, and for literals that are major topics of the subject un‐ der discussion; for example, this page uses bold for macro, string, and register names. In an .EX/.EE example of interactive I/O (such as a shell session), set only user input in bold.

Quoted 4 lines

Since this is a literal that is a major topic of the subject under discussion, I prefer to be a bit pedantic here and boldface it.

I guess it's no big issue; does it hurt readability too much for you?

No, it's no big deal and doesn't hurt readability. It only looks slightly unusual.

Quoted 7 lines

There are cases where a bare '0' character needs to be bold face, for example when discussing ".Fl 0" in xargs(1). But here, you are just talking about the integer 0. The "major topic" here is ".Dv NULL", not the ordinary integer 0 that is internally used to define that constant.
Bold face is mostly for literals that the user needs to type - and the user is specifically *not* supposed to type this 0.

Well, the suggestion of not recommending typing 0 is one thing.

But, the thing is, it's not exactly the integer 0; 0 represents the null pointer in pointer contexts, even if the null pointer was for example 0xFFFF on some weird platform. Even in ISO C, where NULL is not defined to be (void *)0; some conforming platform could perfectly #define (void *)-1, but the platform should then still interpret literal 0 as if the user had typed NULL, or (void *)-1.

So, I really consider 0 as an alternative representation, of course worse than NULL, of the major topic "null pointer constant".

Quoted 24 lines

That's why i consider the .B pointless; then again, it does not do much harm either.

Quoted 6 lines
Quoted 3 lines
Quoted 1 line

+.SH CONFORMING TO

That should be ".SH STANDARDS".

We use CONFORMING TO in Linux. Don't know why; just history, I guess. See man-pages(7).

Weird.

I failed to find a single instance of "CONFORMING TO" in AT&T UNIX (including v6, PWB, v7, 32v, v8, v10, System III, SVR1, SVR2) nor in any version of UCB CSRG BSD. So considering that System V and BSD are widely considered the two main original branches of the development of Unix-like operating systems and Linux is often considered to have drawn inspiration from both, the section name "CONFORMING TO" does not appear to be a UNIX thing. For example, Aeleen Frisch, "Essential System Administration", O'Reilly, Cambridge 1995, considers Linux as slightly more influenced by 4.3BSD than by System V Release 3.

Quoted 6 lines

STANDARDS, on the other hand, is present since 4.3BSD-Reno (June 1990).

4.3BSD-Reno predates the first version of the Linux kernel by more than a year, and the first Linux manual pages probably for longer than that.

So i have no idea where "CONFORMING TO" may have come from.

I don't like the idea of being inconsistent with other Unix systems with no good reason. 's/CONFORMING TO/STANDARDS/' might happen some day; just saying.

Quoted 15 lines

[...]

Quoted 12 lines
Quoted 4 lines
Quoted 1 line

+.SH BUGS

The following is misplaced in BUGS. It is not talking about any bug, nor about any API design defect.

Oh, I do consider this a bug in the API design. I placed it there on purpose.

Allowing the bit pattern of all 0s to represent a valid pointer (and thus not a null pointer) is something that could be meaningful many decades ago, when architectures were more different.

Quoted 8 lines
Quoted 6 lines

Nowadays, every arch out there is 2's complement, and uses 0s as the null pointer. The standard should simplify, and allow memset(2)ing pointers.

In fact, AFAIK, the next revision of POSIX will fix that bug. But I don't remember well the details of that.

Fair points. You convinced me this isn't misplaced in BUGS.

Awww, I did! :-)

Still, I may completely remove that text, since it doesn't trigger in POSIX systems, AFAIK. The bug is only theoretical in POSIX (and practical in non-POSIX, but that's outside of our scope).

I'm also considering a round of trimming 3type pages, by removing theoretical stuff that I added, that really doesn't matter in POSIX systems, or doesn't matter to users.

Yours,

Alex

Quoted 3 lines

Yours,
Ingo

Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>
#9 lore raw

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

Hi Ingo,

Quoted 19 lines · Alejandro Colomar
Quoted 19 lines
Quoted 6 lines
Quoted 3 lines
Quoted 1 line

+.SH CONFORMING TO

That should be ".SH STANDARDS".

We use CONFORMING TO in Linux.  Don't know why; just history, I guess. See man-pages(7).

Weird.

I failed to find a single instance of "CONFORMING TO" in AT&T UNIX (including v6, PWB, v7, 32v, v8, v10, System III, SVR1, SVR2) nor in any version of UCB CSRG BSD.  So considering that System V and BSD are widely considered the two main original branches of the development of Unix-like operating systems and Linux is often considered to have drawn inspiration from both, the section name "CONFORMING TO" does not appear to be a UNIX thing.  For example, Aeleen Frisch, "Essential System Administration", O'Reilly, Cambridge 1995, considers Linux as slightly more influenced by 4.3BSD than by System V Release 3.

Quoted 8 lines
Quoted 6 lines

STANDARDS, on the other hand, is present since 4.3BSD-Reno (June 1990).

4.3BSD-Reno predates the first version of the Linux kernel by more than a year, and the first Linux manual pages probably for longer than that.

So i have no idea where "CONFORMING TO" may have come from.

I don't like the idea of being inconsistent with other Unix systems with no good reason.  's/CONFORMING TO/STANDARDS/' might happen some day; just saying.

I've already changed that. I didn't yet push to <kernel.org>. The patch is in my server, for you to check: <http://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?id=8aac6f8f512e46a008140b93956b6c414ab13a04>.
It didn't fit in an email (the mailing list is limited to 100KB).

I'll probably push tomorrow.

Cheers,

Alex

Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>
#10 lore raw

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

In reply to Alejandro Colomar

* Alejandro Colomar <[email protected]>, 2022-07-24, 21:19:

man3const/NULL.3const line 26

Quoted 11 lines

+.B "#define NULL ((void *) 0)"
+.fi
+.SH DESCRIPTION
+.B NULL

man3const/NULL.3const new file +7 -0
+represents a null pointer constant.
+.PP
+According to POSIX,
+it shall expand to an integer constant expression with the value
+.B 0
+cast to type
+.IR "void *" .

Might be worth noting that the cast requirement was added only in POSIX.1-2008 aka SUSv4.

Quoted 2 lines

+.SH CONFORMING TO
+C99 and later;

It's in C89 too.

Quoted 2 lines

+.I NULL \- NULL
+is, surprisingly, undefined behavior, according to ISO C.

FWIW, I don't find it surprising at all.

Signature · 1 line
Jakub Wilk
#11 lore raw

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

Hi Jakub,

Quoted 15 lines · Jakub Wilk

* Alejandro Colomar <[email protected]>, 2022-07-24, 21:19:

man3const/NULL.3const line 26

Quoted 11 lines

+.B "#define NULL  ((void *) 0)"
+.fi
+.SH DESCRIPTION
+.B NULL

man3const/NULL.3const new file +7 -0
+represents a null pointer constant.
+.PP
+According to POSIX,
+it shall expand to an integer constant expression with the value
+.B 0
+cast to type
+.IR "void *" .

Might be worth noting that the cast requirement was added only in POSIX.1-2008 aka SUSv4.

Quoted 4 lines
Quoted 2 lines

+.SH CONFORMING TO
+C99 and later;

It's in C89 too.

Michael and I agreed that for new pages, we're going to ignore the C89 standard, as almost all current code assumes C99 is available, at least to a certain degree of support.

The same as POSIX.1-1990 is also ignored for simplicity, and we start counting from POSIX.1-2001.

I'm not sure if documenting C89 provides any value (apart from historical curiosity, that is).

Quoted 5 lines
Quoted 3 lines

+.I NULL \- NULL
+is, surprisingly, undefined behavior, according to ISO C.

FWIW, I don't find it surprising at all.

Then you might perhaps find it surprising that in C++ it's defined to be 0.

Cheers,

Alex

Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>
#12 lore raw

PATCH v4 1/1 NULL.3const: Add documentation for NULL

In reply to Alejandro Colomar

---

v2:

- Move to man3const [Ralph, Branden]
- Added LIBRARY section
- Added #include [Ralph]
- Note that it can also be used as a function pointer [Ralph]
- Document that 0 is another null pointer constant [Ralph] But note that it's to be avoided by most coding standards [alx]
- Note that NULL is not NUL
- Improve wording about zeroing a pointer [Ralph]
And refer to getaddrinfo(3) for an example.
This probably can be further improved; I'm not convinced.
- Trim SEE ALSO to just void(3type)
- Other minor fixes

v3:

- Don't boldface 0s, since it doesn't refer to the literal constant 0, but to the bit pattern of 0s.
- Add list of headers that also define NULL (per POSIX.1-2008).

v4:

- Remove details about POSIX defining NULL as (void*)0. [Ingo] All Unix systems already define it that way, so it's irrelevant for us that ISO C or old versions of POSIX didn't define it that way.
- Reword the remaining DESCRIPTION [Ingo]
- Move a big part of NOTES into a new CAVEATS section [Ingo] NOTES is a generic "doesn't fit elsewhere" section. Those things fitted very well a CAVEATS section.
- Simplify mention of 0 as a null pointer constant, and change it to make clear that it's a thing to avoid. [Ingo]
- Keep extra headers in NOTES, as it's a thing that few readers will be interested in.
- Reworded a few things. [Ingo]

 man3const/NULL.3const | 76 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 man3const/NULL.3const
man3const/NULL.3const new file +76 -0
new file mode 100644
index 000000000..28a6f67aa
@@ -0,0 +1,76 @@
+.\" Copyright (c) 2022 by Alejandro Colomar <[email protected]>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.TH NULL 3const 2022-07-22 Linux "Linux Programmer's Manual"
+.SH NAME
+NULL \- null pointer constant
+.SH LIBRARY
+Standard C library
+.RI ( libc )
+.SH SYNOPSIS
+.nf
+.B #include <stddef.h>
+.PP
+.B "#define NULL  ((void *) 0)"
+.fi
+.SH DESCRIPTION
+.B NULL
+represents a null pointer constant,
+that is, a pointer that does not point to anything.
+.SH CONFORMING TO
+C99 and later;
+POSIX.1-2001 and later.
+.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> .
+.SH CAVEATS
+It is undefined behavior to dereference a null pointer,
+and that usually causes a segmentation fault in practice.
+.PP
+It is also undefined behavior to perform pointer arithmetics on it.
+.PP
+.I NULL \- NULL
+is undefined behavior, according to ISO C, but is defined to be 0 in C++.
+.PP
+To avoid confusing human readers of the code,
+do not compare pointer variables to
+.BR 0 ,
+and do not assign
+.B 0
+to them.
+Instead, always use
+.BR NULL .
+.PP
+.B NULL
+shouldn't be confused with
+.BR NUL ,
+which is an
+.BR ascii (7)
+character,
+represented in C as
+.BR \(aq\e0\(aq .
+.SH BUGS
+When it is necessary to set a pointer variable to a null pointer,
+it is not enough to use
+.BR memset (3)
+to zero the pointer
+(this is usually done when zeroing a struct that contains pointers),
+since ISO C and POSIX don't guarantee that a bit pattern of all 0s
+would represent a null pointer.
+Instead, pointer variables need to be explicitly set to a null pointer
+when they need to hold a null pointer.
+See the EXAMPLES section in
+.BR getaddrinfo (3)
+for an example program that does this.
+.SH SEE ALSO
+.BR void (3type)
Signature · 1 line
2.36.1
#13 lore raw

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

Hi Alex,

I'm a bit late to the review party.

Quoted 20 lines · Alejandro Colomar
man3const/NULL.3const new file +14 -0
new file mode 100644
index 000000000..28a6f67aa
@@ -0,0 +1,76 @@
+.\" Copyright (c) 2022 by Alejandro Colomar <[email protected]>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.TH NULL 3const 2022-07-22 Linux "Linux Programmer's Manual"
+.SH NAME
+NULL \- null pointer constant
+.SH LIBRARY
+Standard C library
+.RI ( libc )
+.SH SYNOPSIS
+.nf
+.B #include <stddef.h>

man3const/NULL.3const line 24

Quoted 10 lines
man3const/NULL.3const new file +10 -0
+.PP
+.B "#define NULL  ((void *) 0)"
+.fi
+.SH DESCRIPTION
+.B NULL
+represents a null pointer constant,
+that is, a pointer that does not point to anything.
+.SH CONFORMING TO
+C99 and later;
+POSIX.1-2001 and later.

[...relocated material for a topic shift...]

man3const/NULL.3const line 40

Quoted 5 lines
man3const/NULL.3const new file +5 -0
+.SH CAVEATS
+It is undefined behavior to dereference a null pointer,
+and that usually causes a segmentation fault in practice.
+.PP
+It is also undefined behavior to perform pointer arithmetics on it.

s/artithmetics/arithmetic/

This word is always singular in English.

man3const/NULL.3const line 69

Quoted 7 lines
man3const/NULL.3const new file +7 -0
+When it is necessary to set a pointer variable to a null pointer,
+it is not enough to use
+.BR memset (3)
+to zero the pointer
+(this is usually done when zeroing a struct that contains pointers),
+since ISO C and POSIX don't guarantee that a bit pattern of all 0s
+would represent a null pointer.

Tighten: s/would represent/represents/

man3const/NULL.3const line 71

Quoted 2 lines
man3const/NULL.3const new file +2 -0
+Instead, pointer variables need to be explicitly set to a null pointer
+when they need to hold a null pointer.

This feels nearly circular to me. I suggest

s/explicitly set to a null pointer/assigned the null pointer constant/

That's all I have review-wise.

man3const/NULL.3const line 35

Quoted 11 lines
man3const/NULL.3const new file +11 -0
+.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.

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? ;-)

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.

Regards,
Branden

#14 lore raw

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

Hi Branden,

Quoted 18 lines · G. Branden Robinson

[...relocated material for a topic shift...]

man3const/NULL.3const line 35

Quoted 11 lines

+.SH NOTES

man3const/NULL.3const new file +10 -0
+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).

Quoted 7 lines

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.

Quoted 11 lines

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

Quoted 4 lines

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

Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>
#15 lore raw

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

Hi,

Alejandro Colomar wrote on Tue, Jul 26, 2022 at 08:47:59PM +0200:

Quoted 27 lines · G. Branden Robinson
Quoted 18 lines

man3const/NULL.3const line 35

Quoted 11 lines · Alejandro Colomar

+.SH NOTES

man3const/NULL.3const new file +10 -0
+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.

Quoted 7 lines

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

For once, i agree. Manual pages for header files (like stddef.h(3)) are an even worse idea than manual pages for preprocessor constants and data types. The main reason is that almost every header file includes so much material that such pages would become unreasonably large, just as Alejandro explains above. Besides, the material in a typical header file is not so closely related among itself that it should share a manual page. And in fact, documentation for almost every header file is already split up into many manual
pages: one for each group of closely related functions.

[...]

Quoted 5 lines
Quoted 3 lines

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)!

Indeed.

Then again, while NULL and size_t are exceptional in so far as they are so widely used that there is no clear place for documenting them, most types are better documented together with the most typical function using them.

For example, document  struct tm  in  localtime(3)  and
                       ssize_t    in  read(2).

Besides, almost nothing needs to be said where ssize_t is documented. In particular, documentation of %zd belongs with printf(3), not with ssize_t(3type).

Yours,
Ingo