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

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

 



Reported-by: "G. Branden Robinson" <g.branden.robinson@xxxxxxxxx>
Cc: Ralph Corderoy <ralph@xxxxxxxxxxxxxxx>
Cc: Ingo Schwarze <schwarze@xxxxxxx>
Cc: Jakub Wilk <jwilk@xxxxxxxxx>
Signed-off-by: Alejandro Colomar <alx.manpages@xxxxxxxxx>
---

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@xxxxxxxxx>
+.\"
+.\" 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




[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux