https://gcc.gnu.org/bugzilla/show_bug.cgi?id=115525
Bug ID: 115525
Summary: Documentation: "sentinel" attribute should suggest
"nullptr" instead of NULL
Product: gcc
Version: 14.1.0
Status: UNCONFIRMED
Severity: normal
Priority: P3
Component: other
Assignee: unassigned at gcc dot gnu.org
Reporter: Explorer09 at gmail dot com
Target Milestone: ---
"sentinel" function attribute in GCC documentation:
https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-sentinel-function-attribute
The section mentioned `NULL` for the null pointer. But for C and C++ this is a
bad idea (read this as for why: https://ewontfix.com/11/)
We are now in the era where "nullptr" is standardized in both C and C++, and so
the documentation should suggest that instead, whenever possible. (For pre-C23
code, `(void *)0` may be used as an alternative to `nullptr`, but `NULL` (the
constant) should be deprecated for use in function sentinels now.)
I suggest changing the paragraph to the following:
```
This function attribute indicates that a call to the function is expected to
have a null pointer as the sentinel. The attribute is only valid on variadic
functions. If the optional <i>position</i> argument is specified to the
attribute, the function expects the sentinel to be present at <i>position</i>
counting backwards from the end of the argument list. If <i>position</i> is
unspecified or 0, the sentinel is expected to be the last argument of the
function call, that is,
__attribute__ ((sentinel))
is equivalent to
__attribute__ ((sentinel(0)))
The attribute is automatically set with a position of 0 for the built-in
functions <code>execl</code> and <code>execlp</code>. The built-in function
<code>execle</code> has the attribute set with a position of 1.
Starting with C++11 and C23, <code>nullptr</code> is the preferred keyword for
passing a null pointer argument. For code that need to support older standards,
a zero value with a pointer cast may be used as an alternative.
The warnings for missing or incorrect sentinels are enabled with
<code>-Wformat</code>.
```
