[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