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

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

[Alejandro Colomar]

Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---

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

diff --git a/man3def/NULL.3def b/man3def/NULL.3def
new file mode 100644
index 000000000..a1dec28c2
--- /dev/null
+++ b/man3def/NULL.3def
@@ -0,0 +1,43 @@
+.\" Copyright (c) 2022 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" 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)
-- 
2.36.1

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

[Ralph Corderoy]

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.

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

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

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

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

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

...or function.

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

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

-- 
Cheers, Ralph.

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/

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

[Alejandro Colomar]

Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Ralph Corderoy <ralph@inputplus.co.uk>
Cc: Ingo Schwarze <schwarze@usta.de>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---

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

diff --git a/man3const/NULL.3const b/man3const/NULL.3const
new file mode 100644
index 000000000..1b0cb7948
--- /dev/null
+++ b/man3const/NULL.3const
@@ -0,0 +1,70 @@
+.\" Copyright (c) 2022 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" 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)
-- 
2.36.1

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

[Alejandro Colomar]

Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Ralph Corderoy <ralph@inputplus.co.uk>
Cc: Ingo Schwarze <schwarze@usta.de>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---


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

diff --git a/man3const/NULL.3const b/man3const/NULL.3const
new file mode 100644
index 000000000..730f670fe
--- /dev/null
+++ b/man3const/NULL.3const
@@ -0,0 +1,80 @@
+.\" Copyright (c) 2022 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" 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)
-- 
2.36.1

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

[Ingo Schwarze]

Hi Alejandro,

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

> - 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
> 
> diff --git a/man3const/NULL.3const b/man3const/NULL.3const
> new file mode 100644
> index 000000000..730f670fe
> --- /dev/null
> +++ b/man3const/NULL.3const
> @@ -0,0 +1,80 @@
> +.\" Copyright (c) 2022 by Alejandro Colomar <colomar.6.4.3@gmail.com>
> +.\"
> +.\" 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,

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.

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

> +.B 0

There is really no need to mark up integer constants.

> +cast to type

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

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

> +.SH CONFORMING TO

That should be ".SH STANDARDS".

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

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

> +or to perform pointer arithmetics on it.

Sure.

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

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

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

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

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

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

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

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

[Jakub Wilk]

* Alejandro Colomar <alx.manpages@gmail.com>, 2022-07-24, 21:19:
>+.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 *" .

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

>+.SH CONFORMING TO
>+C99 and later;

It's in C89 too.

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

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

-- 
Jakub Wilk

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 14205 bytes --]

Hi Ingo,

On 7/25/22 20:49, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Alejandro Colomar wrote on Sun, Jul 24, 2022 at 09:19:32PM +0200:
> 
>> - 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
>>
>> diff --git a/man3const/NULL.3const b/man3const/NULL.3const
>> new file mode 100644
>> index 000000000..730f670fe
>> --- /dev/null
>> +++ b/man3const/NULL.3const
>> @@ -0,0 +1,80 @@
>> +.\" Copyright (c) 2022 by Alejandro Colomar <colomar.6.4.3@gmail.com>
>> +.\"
>> +.\" 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,
> 
> 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.

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

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

Makes sense; I reworded.

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

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


> 
>> +cast to type
> 
> Bad grammar:  s/to type/to the type/.

Fixed.

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

I prefer your wording.  Fixed.

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

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

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

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.

> 
>> +or to perform pointer arithmetics on it.
> 
> Sure.
> 
>> +.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.

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

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

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

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

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

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

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

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

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

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

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

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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1249 bytes --]

Hi Jakub,

On 7/25/22 20:57, Jakub Wilk wrote:
> * Alejandro Colomar <alx.manpages@gmail.com>, 2022-07-24, 21:19:
>> +.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 *" .
> 
> Might be worth noting that the cast requirement was added only in 
> POSIX.1-2008 aka SUSv4.
> 
>> +.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).

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

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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Alejandro Colomar]

Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Ralph Corderoy <ralph@inputplus.co.uk>
Cc: Ingo Schwarze <schwarze@usta.de>
Cc: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---

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

diff --git a/man3const/NULL.3const b/man3const/NULL.3const
new file mode 100644
index 000000000..28a6f67aa
--- /dev/null
+++ b/man3const/NULL.3const
@@ -0,0 +1,76 @@
+.\" Copyright (c) 2022 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" 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)
-- 
2.36.1

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 3576 bytes --]

Hi Alex,

I'm a bit late to the review party.

At 2022-07-26T14:48:01+0200, Alejandro Colomar wrote:
> diff --git a/man3const/NULL.3const b/man3const/NULL.3const
> new file mode 100644
> index 000000000..28a6f67aa
> --- /dev/null
> +++ b/man3const/NULL.3const
> @@ -0,0 +1,76 @@
> +.\" Copyright (c) 2022 by Alejandro Colomar <colomar.6.4.3@gmail.com>
> +.\"
> +.\" 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.
[...relocated material for a topic shift...]
> +.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.

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

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

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3981 bytes --]

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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Ingo Schwarze]

Hi,

Alejandro Colomar wrote on Tue, Jul 26, 2022 at 08:47:59PM +0200:
> On 7/26/22 17:54, G. Branden Robinson wrote:
>> Alejandro Colomar wrote:

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

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.

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

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

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Tue, Jul 26, 2022 at 02:02:56PM +0200:
> On 7/25/22 20:49, Ingo Schwarze wrote:
>> Alejandro Colomar wrote on Sun, Jul 24, 2022 at 09:19:32PM +0200:

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

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.


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


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

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

Yours,
  Ingo

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4925 bytes --]

Hi Ingo,

On 7/27/22 12:49, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Alejandro Colomar wrote on Tue, Jul 26, 2022 at 02:02:56PM +0200:
>> On 7/25/22 20:49, Ingo Schwarze wrote:
>>> Alejandro Colomar wrote on Sun, Jul 24, 2022 at 09:19:32PM +0200:
> 
>>>> +.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?
> 
> 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.

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

> 
> That's why i consider the .B pointless; then again, it does not
> do much harm either.
> 
> 
>>>> +.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.

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.

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


> 
> Yours,
>    Ingo

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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1798 bytes --]

Hi Ingo,

On 7/27/22 15:11, Alejandro Colomar wrote:
>>>>> +.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.
> 
> 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

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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]