GNU bug report logs - #21098
uname man page

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 21098 in the body.
You can then email your comments to 21098 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Norbert de Jonge <mail <at> norbertdejonge.nl>
To: bug-coreutils <at> gnu.org, djm <at> djmnet.org
Subject: uname man page
Date: Mon, 20 Jul 2015 21:26:59 +0200

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

Message #8 received at 21098 <at> debbugs.gnu.org (full text, mbox):

From: Assaf Gordon <assafgordon <at> gmail.com>
To: Norbert de Jonge <mail <at> norbertdejonge.nl>, 21098 <at> debbugs.gnu.org, 
 djm <at> djmnet.org
Subject: Re: bug#21098: uname man page
Date: Mon, 20 Jul 2015 17:16:40 -0400

tag 21098 notabug
stop

Hello,

On 07/20/2015 03:26 PM, Norbert de Jonge wrote:
> 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.

The man-page could be re-worded, but,
the values that are reported by uname are very system specific.

The Coreutil FAQ contains an entry for uname:
 http://www.gnu.org/software/coreutils/faq/coreutils-faq.html#uname-is-system-specific

And some past discussions contain more information:
  http://debbugs.gnu.org/cgi/bugreport.cgi?bug=14388
  http://lists.gnu.org/archive/html/bug-coreutils/2003-10/msg00098.html
  http://lists.gnu.org/archive/html/bug-coreutils/2004-11/msg00032.html

> 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".
[...]
> "If you want to determine whether a system is 32-bit or 64-bit, use this option."

mentioning "x86_64/i686" in the documentation is Linux-kernel specific, and coreutils is not limited to Linux-kernel, and would be incorrect/misleading on other systems (e.g. on BSD systems the returned value is "amd64").

In practice,
The values of 'uname' are not standardized over all OSes/hardwares.
The recommended way is to first detect the system/kernel type (e.g. just 'uname'),
and then decode the hardware type, using the values that are common to that kernel.
An example to such code is given here:
  http://debbugs.gnu.org/cgi/bugreport.cgi?bug=14388#14

> 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.

I'm not familiar with Arch;
some GNU/Linux distros return the values reported by the Linux Kernel, and GNU coreutils does not change that value.
Other distros patch GNU coreutils (or the kernel?) to return other values.
See related discussion here:
   http://lists.gnu.org/archive/html/bug-coreutils/2012-11/msg00173.html
   http://lists.gnu.org/archive/html/bug-coreutils/2012-11/msg00177.html

I believe that if the kernel is detected as "Linux", then the developer can assume that "uname -m" would suffice (based on known Linux kernel values) [other participants - please correct me if that's wrong]:

e.g:
    test "$(uname)" = Linux \
       && test "$(uname -m)" = x86_64 \
       && echo 64bit-linux || echo other

For some 'uname -m' values of common OSes (not just Linux-based), see here:
   http://pretest.nongnu.org/versions/

HTH,
 - assaf

Message #11 received at 21098 <at> debbugs.gnu.org (full text, mbox):

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Norbert de Jonge <mail <at> norbertdejonge.nl>, 21098 <at> debbugs.gnu.org, 
 djm <at> djmnet.org
Subject: Re: bug#21098: uname man page
Date: Tue, 21 Jul 2015 07:26:22 +0200

On 07/20/2015 09:26 PM, Norbert de Jonge wrote:
> 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.

Thanks for the report.

Additionally to Assaf's answer, I want to mention that the man page
of GNU coreutils utilities is (almost) identically to the --help output
which we want to keep terse.  Actually the former is generated from the
latter.

At the end of the man page, there is the reference to the real
documentation:

  The full documentation for uname is maintained as a Texinfo manual.
  If the info and uname programs are properly installed at your site,
  the command

              info '(coreutils) uname invocation'

  should give you access to the complete manual.

Now let's look at -m, -p, and -i there:

  `-i'
  `--hardware-platform'
       Print the hardware platform name (sometimes called the hardware
       implementation).  Print `unknown' if the kernel does not make this
       information easily available, as is the case with Linux kernels.

  `-m'
  `--machine'
       Print the machine hardware name (sometimes called the hardware
       class or hardware type).

  `-p'
  `--processor'
       Print the processor type (sometimes called the instruction set
       architecture or ISA).  Print `unknown' if the kernel does not make
       this information easily available, as is the case with Linux
       kernels.

Is this sufficient for you?
Otherwise feel free to suggest a better wording - preferably as a git
patch or a regular diff, but we could also wrap it into a proper patch
for you.

Thanks & have a nice day,
Berny

Message #14 received at 21098 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Assaf Gordon <assafgordon <at> gmail.com>, 
 Norbert de Jonge <mail <at> norbertdejonge.nl>,
 21098 <at> debbugs.gnu.org, djm <at> djmnet.org
Subject: Re: bug#21098: uname man page
Date: Tue, 21 Jul 2015 10:51:59 +0100

[Message part 1 (text/plain, inline)]

On 20/07/15 22:16, Assaf Gordon wrote:
> tag 21098 notabug
> stop
> 
> Hello,
> 
> On 07/20/2015 03:26 PM, Norbert de Jonge wrote:
>> 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.
> 
> The man-page could be re-worded, but,
> the values that are reported by uname are very system specific.
> 
> The Coreutil FAQ contains an entry for uname:
>   http://www.gnu.org/software/coreutils/faq/coreutils-faq.html#uname-is-system-specific
> 
> And some past discussions contain more information:
>    http://debbugs.gnu.org/cgi/bugreport.cgi?bug=14388
>    http://lists.gnu.org/archive/html/bug-coreutils/2003-10/msg00098.html
>    http://lists.gnu.org/archive/html/bug-coreutils/2004-11/msg00032.html
> 
>> 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".
> [...]
>> "If you want to determine whether a system is 32-bit or 64-bit, use this option."
> 
> mentioning "x86_64/i686" in the documentation is Linux-kernel specific, and coreutils is not limited to Linux-kernel, and would be incorrect/misleading on other systems (e.g. on BSD systems the returned value is "amd64").
> 
> In practice,
> The values of 'uname' are not standardized over all OSes/hardwares.
> The recommended way is to first detect the system/kernel type (e.g. just 'uname'),
> and then decode the hardware type, using the values that are common to that kernel.
> An example to such code is given here:
>    http://debbugs.gnu.org/cgi/bugreport.cgi?bug=14388#14
> 
>> 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.
> 
> I'm not familiar with Arch;
> some GNU/Linux distros return the values reported by the Linux Kernel, and GNU coreutils does not change that value.
> Other distros patch GNU coreutils (or the kernel?) to return other values.
> See related discussion here:
>     http://lists.gnu.org/archive/html/bug-coreutils/2012-11/msg00173.html
>     http://lists.gnu.org/archive/html/bug-coreutils/2012-11/msg00177.html
> 
> I believe that if the kernel is detected as "Linux", then the developer can assume that "uname -m" would suffice (based on known Linux kernel values) [other participants - please correct me if that's wrong]:
> 
> e.g:
>      test "$(uname)" = Linux \
>         && test "$(uname -m)" = x86_64 \
>         && echo 64bit-linux || echo other

BTW for a more direct/portable method, one might consider:

  test "$(getconf LONG_BIT)" = '64'

Also that would work better in a 32 chroot on 64 bit kernel.

> 
> For some 'uname -m' values of common OSes (not just Linux-based), see here:
>     http://pretest.nongnu.org/versions/

Very useful info thanks!

I see this was also discussed at:
http://bugs.gnu.org/13001
http://bugs.gnu.org/15757

Some quick testing here gives:

System                  uname -i        uname -m        uname -p
----------------------------------------------------------------
OS X - coreutils        Macmini7,1      x86_64          i386
OS X - native           illegal option  x86_64          i386
Solaris 10              SUNW,SPARC...   sun4v           sparc
Fedora 22               x86_64          x86_64          x86_64
GNU/Linux               unknown         x86_64          unknown

I find it incorrect that the Linux distros just copied -m to -i and -p.

BTW for a script using -m and -p (but not -i) values see:
http://git.sv.gnu.org/gitweb/?p=gnulib.git;f=build-aux/config.guess;hb=HEAD

I wonder should be just be more explicit about discouraging
use of the -i and -p options, and leave it at that.
That's done in the attached.

thanks,
Pádraig.

[coreutils-uname-ip.patch (text/x-patch, attachment)]

Message #17 received at 21098 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Pádraig Brady <P <at> draigBrady.com>, 
 Assaf Gordon <assafgordon <at> gmail.com>,
 Norbert de Jonge <mail <at> norbertdejonge.nl>, 21098 <at> debbugs.gnu.org, 
 djm <at> djmnet.org
Subject: Re: bug#21098: uname man page
Date: Tue, 21 Jul 2015 06:34:47 -0700

Thanks, that patch looks good, except for some nits.  POSIX spells the phrase 
"non-portable" and we might as well be consistent.  The --help lines would look 
better as:

  -p, --processor          print the processor type (non-portable)\n\
  -i, --hardware-platform  print the hardware platform (non-portable)\n\

as the period would look funny after a non-capitalized sentence.

Message #20 received at 21098 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>, Assaf Gordon <assafgordon <at> gmail.com>,
 Norbert de Jonge <mail <at> norbertdejonge.nl>, 21098 <at> debbugs.gnu.org, 
 djm <at> djmnet.org
Subject: Re: bug#21098: uname man page
Date: Wed, 22 Jul 2015 01:54:58 +0100

unarchive 13001
unarchive 15757
forcemerge 13001 15757 21098
close 13001
stop

On 21/07/15 14:34, Paul Eggert wrote:
> Thanks, that patch looks good, except for some nits.  POSIX spells the phrase 
> "non-portable" and we might as well be consistent.  The --help lines would look 
> better as:
> 
>    -p, --processor          print the processor type (non-portable)\n\
>    -i, --hardware-platform  print the hardware platform (non-portable)\n\
> 
> as the period would look funny after a non-capitalized sentence.

Done and pushed.
I've closed the bugs now since we've discouraged use of these options.
Since they're platform specific, any logic changes should be
in uname(1) and/or the kernel.

thanks,
Pádraig.

Message #27 received at 21098 <at> debbugs.gnu.org (full text, mbox):

From: Stephane Chazelas <stephane.chazelas <at> gmail.com>
To: Pádraig Brady <P <at> draigBrady.com>
Cc: Norbert de Jonge <mail <at> norbertdejonge.nl>,
 Assaf Gordon <assafgordon <at> gmail.com>, Paul Eggert <eggert <at> cs.ucla.edu>,
 21098 <at> debbugs.gnu.org, djm <at> djmnet.org
Subject: Re: bug#21098: uname man page
Date: Wed, 22 Jul 2015 10:33:55 +0100

2015-07-22 01:54:58 +0100, Pádraig Brady:
[...]
> On 21/07/15 14:34, Paul Eggert wrote:
> > Thanks, that patch looks good, except for some nits.  POSIX spells the phrase 
> > "non-portable" and we might as well be consistent.  The --help lines would look 
> > better as:
> > 
> >    -p, --processor          print the processor type (non-portable)\n\
> >    -i, --hardware-platform  print the hardware platform (non-portable)\n\
> > 
> > as the period would look funny after a non-capitalized sentence.
> 
> Done and pushed.
> I've closed the bugs now since we've discouraged use of these options.
> Since they're platform specific, any logic changes should be
> in uname(1) and/or the kernel.
[...]

Note that for Solaris, it's -m that's discouraged
http://docs.oracle.com/cd/E23824_01/html/821-1461/uname-1.html

-p is useful as it gives (is meant to give) the instruction-set. 

Although not POSIX, it's fairly portable. Among the modern (and
less modern) Unix players, I could only find HP/UX not
supporting it.

-- 
Stephane

Message #30 received at 21098 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Stephane Chazelas <stephane.chazelas <at> gmail.com>
Cc: Norbert de Jonge <mail <at> norbertdejonge.nl>,
 Assaf Gordon <assafgordon <at> gmail.com>, Paul Eggert <eggert <at> cs.ucla.edu>,
 21098 <at> debbugs.gnu.org, djm <at> djmnet.org
Subject: Re: bug#21098: uname man page
Date: Wed, 22 Jul 2015 11:27:08 +0100

On 22/07/15 10:33, Stephane Chazelas wrote:
> 2015-07-22 01:54:58 +0100, Pádraig Brady:
> [...]
>> On 21/07/15 14:34, Paul Eggert wrote:
>>> Thanks, that patch looks good, except for some nits.  POSIX spells the phrase 
>>> "non-portable" and we might as well be consistent.  The --help lines would look 
>>> better as:
>>>
>>>    -p, --processor          print the processor type (non-portable)\n\
>>>    -i, --hardware-platform  print the hardware platform (non-portable)\n\
>>>
>>> as the period would look funny after a non-capitalized sentence.
>>
>> Done and pushed.
>> I've closed the bugs now since we've discouraged use of these options.
>> Since they're platform specific, any logic changes should be
>> in uname(1) and/or the kernel.
> [...]
> 
> Note that for Solaris, it's -m that's discouraged
> http://docs.oracle.com/cd/E23824_01/html/821-1461/uname-1.html
> 
> -p is useful as it gives (is meant to give) the instruction-set. 
> 
> Although not POSIX, it's fairly portable. Among the modern (and
> less modern) Unix players, I could only find HP/UX not
> supporting it.

Thanks for the extra info.
Just to be clear, for portability I was referring
to the POSIX options, but mainly to the value itself.
I.E. it's meant as a warning to have users consider
use of these values.  Also it's better to align
with the standards and most popular platforms.

thanks,
Pádraig.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.