[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