Observations from an old timer playing with 64 bit numbers...

[Bruce Evans]

On Wed, 23 Jun 2010, Randall Stewart wrote:

> On Jun 23, 2010, at 12:41 PM, Julian Elischer wrote:

>> but I think it
>> should be a local define to be64toh or ntoh64
>> I do prefer the ntoh64 version but beXXtoh or whatever it looks like others 
>> are using is ok to me too since 'net' is a pretty wide definition and not 
>> ALL protocols are big endian.

A global define for ntoh64 would be reasonable.

It wouldn't be OK if 'net' were so wide, but I think it basically requires
big endian (there must be an endianness and there shouldn't be 2).

> I will make this last comment.. directed at Luigi in response to:
>
>>> people's ignorance is not an excuse for not doing things right
>
> Then I would strongly suggest you go fix the manual page for ntohl/ntohs and
> point people to the be64toh() functions... then people would NOT be ignorant.
>
> The problem is there is NO clue in the system...

The man page is indeed not good.  It is too general, and I noticed the
following errors in its details:

% BYTEORDER(3)           FreeBSD Library Functions Manual           BYTEORDER(3)

It is far from being about general byte order macros (those are mainly the
be/le ones in byteorder(9)...

% 
% NAME
%      htonl, htons, ntohl, ntohs -- convert values between host and network
%      byte order

... it is only about these network functions.

% DESCRIPTION
%      These routines convert 16 and 32 bit quantities between network byte
%      order and host byte order.  On machines which have a byte order which is
%      the same as the network order, routines are defined as null macros.

s/routines/these routines/
s/null/null filter/ [but needs more work:]

Saying that the routines are defined as null macros gives too much detail,
and the detail is wrong.  The "routines" are actually defined as deeply
nested macros in all cases (but are backed up by real routines, i.e.,
extern functions) for when the macros are #undefed).  Then, on machines
which have a byte order which is the same as the network order, the macros
end up expanding to the non-quite null filter of (type)(arg), where `type'
is the relevant type.  But this is too much detail.

% SEE ALSO
%      gethostbyname(3), getservent(3), byteorder(9)

I find cross references like this worse than useless.  The relevant
functions should be mentioned in the description, with specific
cross references there, and there should be no generic cross references
in the SEE ALSO section.

Bruce