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

[G. Branden Robinson]

Hi Alex,

I'm a bit late to the review party.

At 2022-07-26T14:48:01+0200, Alejandro Colomar wrote:
> 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@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,
> +that is, a pointer that does not point to anything.
> +.SH CONFORMING TO
> +C99 and later;
> +POSIX.1-2001 and later.
[...relocated material for a topic shift...]
> +.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.

s/artithmetics/arithmetic/

This word is always singular in English.

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

Tighten: s/would represent/represents/

> +Instead, pointer variables need to be explicitly set to a null pointer
> +when they need to hold a null pointer.

This feels nearly circular to me.  I suggest

s/explicitly set to a null pointer/assigned the null pointer constant/

That's all I have review-wise.

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

Not exactly on topic (sorry), but apropos of our concurrent discussion
on man pages for constants with external linkage and data types, the
foregoing is an excellent counterexample of what I contend is good
practice: document them in the man page for the header file.

It is only the standard C library that avails itself of such a rampant
multiplicity of definition sites for constants.  This is of course
because of the synergy of 2 factors: (1) the library header design is
modular, and yet (2) the null pointer is ubiquitous and supports
applications in many application areas.

To me, this supports rather than undermines my argument for header file
man page contents, because as we can see here, what we've diagnosed is
really a missed opportunity to define the null pointer constant _at the
language level_ instead of relegating it to an optional feature of the
standard library which you nevertheless will have a hard time doing
without.  C programmers can code freestanding applications without
resource to the standard C library.  What are these freestanding
applications, invariably?  Operating system kernels, or machine-mode
code doing the work of an OS alongside its (presumably embedded,
microcontroller-like) function.  Are _those_ going to have a use for a
null pointer constant?  What do you think?  ;-)

POSIX supplements to the standard C library, and other libraries for C,
will not typically have this difficulty, and will have one definition
site only for their constants with external linkage.

Regards,
Branden

signature.asc
Description: PGP signature