bug#21098: uname man page

[Norbert de Jonge]

Maybe someone has time and energy to make some minor improvements to
uname's man page. The problem lies in the vagueness and similarity of
the options -m, -p and -i, combined with the program's unpredictable
output.

I think a good way to explain the problem is by giving an example.
My example mentions proprietary software, but the problem occurs in
many other settings. The game engine Unity can deploy to GNU/Linux. A
game developer creates a 64-bit executable and a customer requests
32-bit support in a post on the game's Steam Community Hub. Someone
mentions to the indie developer that a shell script that uses uname
could do the trick. The developer looks at the uname man page, reads
"print the hardware platform" for -i and decides to try this out on
Ubuntu. It returns "x86_64" for the developer's 64-bit machine. After a
bit of reading about bash the result is something like: if [ `uname -i`
= x86_64 ] then ./game_64 else ./game_32 fi

Now, that works on Ubuntu, but not on, for example, Arch. Ubuntu, Mint
and probably also Debian, return the same thing for -m, -p and -i. But,
if I'm not mistaken, the only POSIX option of those three is -m:
http://pubs.opengroup.org/onlinepubs/9699919799/utilities/uname.html
For -m, The Open Group's publication says "Write the name of the
hardware TYPE" (emphasis mine). The GNU coreutils man page for uname
says -m will "print the machine hardware NAME", while -i says "print
the hardware PLATFORM". The latter /seems/ to be the most relevant
option even though it's not.

To make people's lives easier, the description for -m should be
changed. I also think it would be useful to add to the description, in
parentheses, "e.g. x86_64, i686". The man page could also use a POSIX
section. In fact, it would be better if the section that describes the
options, near those three similar ones, would say which of
those is the POSIX variant and maybe even that "If you want to
determine whether a system is 32-bit or 64-bit, use this option."
Really. I really think we can't help out people enough. Even "processor
type" (-p) returns x86_64 on many/most distros, and may (thus) also
trick developers and users into thinking that's the thing they're
looking for.

Best regards,
Norbert de Jonge