[Top][All Lists]

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

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

From: Alejandro Colomar
Subject: [PATCH v4] NULL.3const: Add documentation for NULL
Date: Tue, 26 Jul 2022 14:48:01 +0200

Reported-by: "G. Branden Robinson" <>
Cc: Ralph Corderoy <>
Cc: Ingo Schwarze <>
Cc: Jakub Wilk <>
Signed-off-by: Alejandro Colomar <>


- 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


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


- 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 <>
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.TH NULL 3const 2022-07-22 Linux "Linux Programmer's Manual"
+NULL \- null pointer constant
+Standard C library
+.RI ( libc )
+.B #include <stddef.h>
+.B "#define NULL  ((void *) 0)"
+represents a null pointer constant,
+that is, a pointer that does not point to anything.
+C99 and later;
+POSIX.1-2001 and later.
+The following headers also provide
+.IR <locale.h> ,
+.IR <stdio.h> ,
+.IR <stdlib.h> ,
+.IR <string.h> ,
+.IR <time.h> ,
+.IR <unistd.h> ,
+.IR <wchar.h> .
+It is undefined behavior to dereference a null pointer,
+and that usually causes a segmentation fault in practice.
+It is also undefined behavior to perform pointer arithmetics on it.
+is undefined behavior, according to ISO C, but is defined to be 0 in C++.
+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
+shouldn't be confused with
+.BR NUL ,
+which is an
+.BR ascii (7)
+represented in C as
+.BR \(aq\e0\(aq .
+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.
+.BR void (3type)

reply via email to

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