cdefs.h: Document the _XOPEN_SOURCE - 0 construct

Various System V Interface Definition editions, as well as the X/Open
group portability guide issue 4, recommend defining _XOPEN_SOURCE and
broadly intimating it means the same thing as _POSIX_SOURCE == 2.

Starting in X/Open issue 5 (1995), _XOPEN_SOURCE needs to be defined to
be 500 to bring in the newer interfaces. However, it is still common hat
sources define _XOPEN_SOURCE to be blank. To deal with that, we subtract
0 from _XOPEN_SOURCE to make the other expressions well formed.

While here, document that we should define _POSIX_C_SOURCE to be 199209
based on the SVID, the first version of the Single Unix Specification,
and X/Open CAE issue 4, version 2. Also document that historically this
has been a NOP. Any value of _XOPEN_SOURCE < 500 (including it being
blank) was not viewed as a request for a restricted namespace.

Reviewed by:		brooks (earlier version)
Differential Revision:	https://reviews.freebsd.org/D47584
Sponsored by:		Netflix

sys/sys/cdefs.h

@@ -513,7 +513,16 @@
 #define	_POSIX_C_SOURCE		199209
 #endif
 
-/* Deal with various X/Open Portability Guides and Single UNIX Spec. */
+/*
+ * Deal with various X/Open Portability Guides and Single UNIX Spec. We use the
+ * '- 0' construct so software that defines _XOPEN_SOURCE to nothing doesn't
+ * cause errors. X/Open CAE Specification, August 1994, System Interfaces and
+ * Headers, Issue 4, Version 2 section 2.2 states an empty definition means the
+ * same thing as _POSIX_C_SOURCE == 2. This broadly mirrors "System V Interface
+ * Definition, Fourth Edition", but earlier editions suggest some ambiguity.
+ * However, FreeBSD has histoically implemented this as a NOP, so we just
+ * document what it should be for now to not break ports gratuitously.
+ */
 #ifdef _XOPEN_SOURCE
 #if _XOPEN_SOURCE - 0 >= 800
 #define	__XSI_VISIBLE		800
@@ -531,6 +540,8 @@
 #define	__XSI_VISIBLE		500
 #undef _POSIX_C_SOURCE
 #define	_POSIX_C_SOURCE		199506
+#else
+/* #define	_POSIX_C_SOURCE		199209 */
 #endif
 #endif