James Kuyper <jameskuyper@alumni.caltech.edu> writes:

Tim Rentsch <tr.17687@z991.linuxsc.com> wrote:

James Kuyper <jameskuyper@alumni.caltech.edu> writes:

...

Note: in C2023, the [predefined macro names] section says: "Any other
predefined macro names: shall begin with a leading underscore
followed by an uppercase letter; or, a second underscore...". For
earlier versions of the standard, user code should avoid using such
identifiers because they were reserved for all purposes, but that's no
longer the case. Now, they should be avoided because they may be
pre-defined by the implementation, which means that any attempt to use
them might have unpredictable results.

That's right in the sense that if the implementation is unknown then
unexpected results may occur. However, if the implementation is
known, then we can find out what results are expected by consulting
the implementation's documentation for extensions, since any such
macro name must qualify as an extension, and so much be documented.

J.5 identifies as extensions only "... predefined macros with names that
do not begin with an underscore." (J.5, J.5.13)

That doesn't invalidate what I said. And anyway Annex J is only
informative, not normative.

They are not identified as implementation-defined, so there is no
obligation to document them.

Let me clarify my earlier comment. An implementation is free to
accept almost anything at all, as long as a diagnostic is issued.
But any usage[*] that would otherwise be a syntax error or violate
a constraint, if accepted without issuing a diagnostic, must be an
extension and so must be documented.

[*] an ordinary use, not a declaring or defining use.

--- PyGate Linux v1.5.2
* Origin: Dragon's Lair, PyGate NNTP<>Fido Gate (3:633/10)

Keith Thompson <Keith.S.Thompson+u@gmail.com> writes:

Tim Rentsch <tr.17687@z991.linuxsc.com> writes:

James Kuyper <jameskuyper@alumni.caltech.edu> writes:

[...]

Note: in C2023, the [predefined macro names] section says: "Any other
predefined macro names: shall begin with a leading underscore
followed by an uppercase letter; or, a second underscore...". For
earlier versions of the standard, user code should avoid using such
identifiers because they were reserved for all purposes, but that's no
longer the case. Now, they should be avoided because they may be
pre-defined by the implementation, which means that any attempt to use
them might have unpredictable results.

That's right in the sense that if the implementation is unknown then
unexpected results may occur. However, if the implementation is
known, then we can find out what results are expected by consulting
the implementation's documentation for extensions, since any such
macro name must qualify as an extension, and so much be documented.

Note by the way that the description in N3220 section 6.10.10.1
paragraph 2 makes using #define or #undef be undefined behavior only
for macro names in the subclause (and also a short list of other
identifiers). Hence any other predefined macro name may be used,
definedly, simply by using #undef and then #define for the macro
name in question (in particular, under C23 rules, but not earlier
versions of the C standard).

I don't *think* that all implementation-specific predefined macros have
to be documented -- at least, I'd be surprised if that were the intent.

For example, I don't think an implementation is required to document its
use of _STDIO_H (the include guard header in the glibc implementation of <stdio.h>).

Though it's not normative, N3220 J.5.1 (Common extensions) says:

Examples of such extensions are new keywords, extra library
functions declared in standard headers, or predefined macros with
names that do not begin with an underscore.

I gave a clarifying response to this question in my recent
followup to the post from James Kuyper.

--- PyGate Linux v1.5.2
* Origin: Dragon's Lair, PyGate NNTP<>Fido Gate (3:633/10)

Keith Thompson <Keith.S.Thompson+u@gmail.com> writes:

Tim Rentsch <tr.17687@z991.linuxsc.com> writes:

antispam@fricas.org (Waldek Hebisch) writes:

Tim Rentsch <tr.17687@z991.linuxsc.com> wrote:

James Kuyper <jameskuyper@alumni.caltech.edu> writes:

[...]

Note: in C2023, the [predefined macro names] section says: "Any
other predefined macro names: shall begin with a leading
underscore followed by an uppercase letter; or, a second
underscore...". For earlier versions of the standard, user code
should avoid using such identifiers because they were reserved
for all purposes, but that's no longer the case. Now, they
should be avoided because they may be pre-defined by the
implementation, which means that any attempt to use them might
have unpredictable results.

That's right in the sense that if the implementation is unknown
then unexpected results may occur. However, if the
implementation is known, then we can find out what results are
expected by consulting the implementation's documentation for
extensions, since any such macro name must qualify as an
extension, and so much be documented.

Hmm, looking at '/usr/include/string.h' on my machine I see
definitions of things like

__GLIBC_INTERNAL_STARTING_HEADER_IMPLEMENTATION
__need_size_t

and lot of similar things. I do not recall seeing any user
documentation listing them. Does this mean that gcc+glibc
is noncompilant in this aspect?

I think it's reasonable to say that the appearance of a macro
name being #define'd in a standard header qualifies as
documenting the name being #define'd.

I disagree. I don't think it's reasonable to say that.

Some people think it's reasonable. It's okay if you don't.

Headers are not documentation. They're often barely human-readable,
and the system headers aren't necessarily even files.

Yes, I might have said "standard header file", with the
understanding that the files in question are encoded in regular
ascii. There isn't any requirement that the document(s) be easy
to read.

As long as the #define is
readable in an ordinary source file, there isn't any mystery
about the name being used or what its definition is.

System headers can be arbitrarily complex, with #includes for other system-specific headers, nests of #ifs and #ifdefs, and so on.

As long as they define all implementation-defined characteristics
(and I suppose can be understood by humans), how complex they are
doesn't matter. That's a QOI issue, not a conformance issue.

I suppose
that to satisfy the letter of the C standard, the accompanying
document would need to incorporate the system header files by
reference, but surely the header files satisfy the spirit of
providing the required documentation. Implementation-defined
values for things like CHAR_BIT and INT_MAX fall under the same
rule for documentation as do extensions, yet as far as I know
these values are defined only in system header files, and not in
any separate document.

gcc's documentation does have a "C Implementation-Defined Behavior"
section. It doesn't mention CHAR_BIT by name, but it does document
"The number of bits in a byte" as "Determined by ABI". I didn't
find anything similar for INT_MAX.

I find it implausible that the standard intended to require
implementations to document all macros defined in standard headers,

The language in the C standard is clearcut: "An implementation shall
be accompanied by a document that defines all implementation-defined
and locale-specified characteristics and all extensions." If gcc
(together with glibc) doesn't provide such a document, that defines
ALL implementation-defined characteristics, etc, and system header
files don't count, then that implementation is not conforming. See
also my followup to James Kuyper in a closely related sub-thread.

--- PyGate Linux v1.5.2
* Origin: Dragon's Lair, PyGate NNTP<>Fido Gate (3:633/10)