svn commit: r303033 - head/share/man/man7

[Bruce Evans]

On Tue, 19 Jul 2016, Warner Losh wrote:

> On Tue, Jul 19, 2016 at 9:01 PM, Jan Beich <jbeich at vfemail.net> wrote:
>> Ed Maste <emaste at FreeBSD.org> writes:
>>
>>> +.Ss Predefined Macros
>>> +The compiler provides a number of predefined macros.
>>> +Some of these provide architecture-specific details and are explained below.
>>> +Other macros, including those required by the language standard, are not
>>> +included here.
>> [...]
>>> +cc -x c -Dm -E /dev/null
>>
>> Typo: -Dm vs. -dM
>>
>>> +.It Dv BYTE_ORDER Ta Either Dv BIG_ENDIAN or Dv LITTLE_ENDIAN .
>>
>> Are these really compiler macros? I think, <machine/endian.h> defines them.

These are non-compiler-predefined macros.  They are namespace pollution
in <machine/endian.h> which is only there in the __BSD_VISIBLE case.

> sys/endian.h defines them (and it implements that by including machine/endian.h
> in part).
>
>> $ clang38 -x c -dM -E /dev/null | fgrep ENDIAN
>> #define __BYTE_ORDER__ __ORDER_LITTLE_ENDIAN__
>> #define __LITTLE_ENDIAN__ 1
>> #define __ORDER_BIG_ENDIAN__ 4321
>> #define __ORDER_LITTLE_ENDIAN__ 1234
>> #define __ORDER_PDP_ENDIAN__ 3412

These are the related compiler definitions in the implementation
namespace.  Their spelling is quite different and there are no
consistency checks between values, but the ABI requires similar values.
The values are as different as the spellings in some cases.
__LITTLE_ENDIAN__ is 1, but FreeBSD's _LITTLE_ENDIAN is 1234.
Actually, the semantics of these is very different too.  FreeBSD's
_LITTLE_ENDIAN corresponds to __ORDER_LITTLE_ENDIAN.

>> $ gcc5 -x c -dM -E /dev/null | fgrep ENDIAN
>> #define __ORDER_LITTLE_ENDIAN__ 1234
>> #define __FLOAT_WORD_ORDER__ __ORDER_LITTLE_ENDIAN__
>> #define __ORDER_PDP_ENDIAN__ 3412
>> #define __ORDER_BIG_ENDIAN__ 4321
>> #define __BYTE_ORDER__ __ORDER_LITTLE_ENDIAN__

gcc apparently doesn't even have the confusing __LITTLE_ENDIAN__.

> This is why they are defined in machine/endian.h. Compilers have been
> somewhat inconsistent in the past.

But they aren't defined in machine/endian.h.  Compilers had no trace
of them in the past.  Even gcc-4.2 in the present /usr/src doesn't have
them.  The FreeBSD macros should be used since they have been portable
in BSD for at last 25 years, with a better spelling which is unsuitable
for standards because it is not ugly enough to not be already in use
with possibly inconsistent semantics.

glibc is different again.  In an old version (2.6), it uses __BYTE_ORDER
where FreeBSD uses _BYTE_ORDER and compilers use __BYTE_ORDER__.  It
also defines the FreeBSD pollution BYTE_ORDER in string/endian.h and
uses this in dangerous places like netinet/icmp6.h, but in the
standard netinet/in.h which doesn't allow this, it is more careful
and uses __BYTE_ORDER.

The man page might need to be more careful about this.  BYTE_ORDER is
not a compiler predefine or standard spelling and determing the
applicable spelling is time-consuming.

Bruce