summaryrefslogtreecommitdiffstats
path: root/man/man3const/NULL.3const
diff options
context:
space:
mode:
Diffstat (limited to 'man/man3const/NULL.3const')
-rw-r--r--man/man3const/NULL.3const74
1 files changed, 74 insertions, 0 deletions
diff --git a/man/man3const/NULL.3const b/man/man3const/NULL.3const
new file mode 100644
index 0000000..c9cdc37
--- /dev/null
+++ b/man/man3const/NULL.3const
@@ -0,0 +1,74 @@
+.\" Copyright (c) 2022 by Alejandro Colomar <alx@kernel.org>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.TH NULL 3const 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+NULL \- null pointer constant
+.SH LIBRARY
+Standard C library
+.RI ( libc )
+.SH SYNOPSIS
+.nf
+.B #include <stddef.h>
+.P
+.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.
+.P
+It is also undefined behavior to perform pointer arithmetic on it.
+.P
+.I NULL \- NULL
+is undefined behavior, according to ISO C, but is defined to be 0 in C++.
+.P
+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 .
+.P
+.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
+represent a null pointer.
+See the EXAMPLES section in
+.BR getaddrinfo (3)
+for an example program that does this correctly.
+.SH SEE ALSO
+.BR void (3type)