Re: Query about uname.

Re: Query about uname.

[Michael Kerrisk]

[CC+= linux-msan@, which is where man-pages discussions really belong...]

On Sat, Nov 29, 2008 at 3:07 AM, Rob Landley <rob@landley.net> wrote:
> On Friday 28 November 2008 15:00:23 Michael Kerrisk wrote:
>> Rob,
>>
>> On Thu, Nov 27, 2008 at 8:35 AM, Rob Landley <rob@landley.net> wrote:
>> > http://kernel.org/doc/man-pages/online/pages/man2/uname.2.html
>> >
>> > It says the length of the fields was unspecified.
>>
>> Yup -- that's what POSIX says.
>
> Posix doesn't specify init or mount either.  "Posix doesn't specify" doesn't
> forbid something else from specifying it.

I think you somewhat misunderstand "unspecified".  For a wise
application writer, this means: avoid relying on specific behaviors
here if you want to write portable and future-proof programs.

>> As noted in the first para of the description,
>> the fields of the structure are null-terminated, which, in the typical
>> case, makes it quite possible to use them without knowing their
>> (maximum) lengths.
>
> Use a field, yes.  Iterate though the fields/find the next field, no.

(This strikes me as a somewhat unusual requirement in the context of uname())

> (I
> suppose you can memset the memory block you feed to the syscall to "null" and
> iterate through to the next non-null character, as long there's a guarantee
> none of the fields will be zero length.)
>
>> And indeed, a portable program should not care.
>
> When I start writing portable programs that I intend to support on Dragonfly
> BSD, I'll let you know.  "Posix portable" includes Windows NT and strange IBM
> mainframes.

Sure, but the man-pages are written for a general audience, many of
whom most certainly *do* care about portability.

>> > so leaving it unspecified is silly.  It's part of the current kernel's
>> > binary abi, and the value is currently 65.
>>
>> And that last piece is exactly part of the problem, because once upon
>> a time (okay: a long time ago, now), it was true that "the value is
>> currently 9".
>>
>> It seems to me that all the info you needed was there in the page, but
>> you didn't read the whole page.
>
> True.  I didn't notice that there was a "notes" field (my screen ended with
> "return value", "errors", and "conforming to", didn't hit page down) that was
> larger than the rest of the page.  My bad.
>
>> The question is, whether the page
>> could/should provide more clues to make sure that the reader is
>> pointed to the fine details (which, for the reasons I described above,
>> are often not needed).
>
> I thought the point of the man pages on kernel.org was to document the kernel
> API.

See http://www.kernel.org/doc/man-pages/

And especially, have a good look at
http://www.kernel.org/doc/man-pages/maintaining.html

Man-pages serves many purposes -- a probably incomplete list, in no
particular order:

1.Documenting the kernel API
2. Documenting the glibc API
3. Managing the sometimes tricky balance between the first two goals
when there is a glibc wrapper that is non-trivial and changes the
interface of the underlying system call.
4. Providing guidance on writing programs portable across Unix systems.
5. Providing information on historical variations in the Linux kernel
and glibc interfaces -- in other words, providing guidance for
programmers writing programs portable across Linux kernel and glibc
versions.

> (If you're programming against glibc I assume that has its own
> documentation somewhere.)

An interesting surmise.  There is the glibc manual.  But

1. Many people (greatly) prefer man(1) format
2. The glibc manual is far from complete.  (Often there is a man page
for a glibc function, but no info page; sometimes the reverse is also
true.)
3. The glibc manual often doesn't seem to cover details of historical
changes in the glibc interface, or to document bugs.
4. Oftentimes a function's man page is better (more info, and/or a
better (or any) example program) than the glibc info page (sometimes,
the reverse is true, but often that changes after I find out about
it).

> I suppose those of us programming against uClibc or
> other low level interfaces can always just look at the kernel source code.

(Not sure of where you mean to go with that statement.)

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html

Re: Query about uname.

[Rob Landley]

On Saturday 29 November 2008 07:08:43 Michael Kerrisk wrote:
> [CC+= linux-msan@, which is where man-pages discussions really belong...]

I wonder what linux-doc is for?

> > Posix doesn't specify init or mount either.  "Posix doesn't specify"
> > doesn't forbid something else from specifying it.
>
> I think you somewhat misunderstand "unspecified".  For a wise
> application writer, this means: avoid relying on specific behaviors
> here if you want to write portable and future-proof programs.

Perhaps I'm strange in trying to treat Linux as a platform I want to write 
software for.  I'm all for future-proofing, but after a binary's compiled 
there's not a whole lot you can do about it, and if they're happy to break 
binary compatibility all bets are off anyway.

> >> As noted in the first para of the description,
> >> the fields of the structure are null-terminated, which, in the typical
> >> case, makes it quite possible to use them without knowing their
> >> (maximum) lengths.
> >
> > Use a field, yes.  Iterate though the fields/find the next field, no.
>
> (This strikes me as a somewhat unusual requirement in the context of
> uname())

Implementing "uname -a", or having uname's command line argument parsing that 
treats "snrvm" as a series of fields in order.

> >> And indeed, a portable program should not care.
> >
> > When I start writing portable programs that I intend to support on
> > Dragonfly BSD, I'll let you know.  "Posix portable" includes Windows NT
> > and strange IBM mainframes.
>
> Sure, but the man-pages are written for a general audience, many of
> whom most certainly *do* care about portability.

As long as that general audience doesn't _exclude_ people who think that Linux 
is a platform in its own right, and that just as some MacOS X programs won't 
run on Linux, it's perfectly acceptable for a Linux program to open 
/proc/cpuinfo and look at its contents if they've been stable for over 10 
years now and there's no other obvious way to get that info.


> >> It seems to me that all the info you needed was there in the page, but
> >> you didn't read the whole page.
> >
> > True.  I didn't notice that there was a "notes" field (my screen ended
> > with "return value", "errors", and "conforming to", didn't hit page down)
> > that was larger than the rest of the page.  My bad.
> >
> >> The question is, whether the page
> >> could/should provide more clues to make sure that the reader is
> >> pointed to the fine details (which, for the reasons I described above,
> >> are often not needed).
> >
> > I thought the point of the man pages on kernel.org was to document the
> > kernel API.
>
> See http://www.kernel.org/doc/man-pages/
>
> And especially, have a good look at
> http://www.kernel.org/doc/man-pages/maintaining.html

I read the first five screens full, and skimmed the first three pages of the 
first link (man 7 man-pages).  I assume there's a policy statement buried 
somewhere under there, but didn't dig far enough to find it.

I was under the impression that man page section 2 was about the kernel, and 
man page section 3 was about glibc.

> Man-pages serves many purposes -- a probably incomplete list, in no
> particular order:
>
> 1.Documenting the kernel API
> 2. Documenting the glibc API
> 3. Managing the sometimes tricky balance between the first two goals
> when there is a glibc wrapper that is non-trivial and changes the
> interface of the underlying system call.

I'm aware of this.  I thought the kernel.org pages would document the kernel, 
because glibc has its own documentation and nothing else is going to.  If it 
wants to document how glibc does things as well, I'd like to if people using 
klibc or uClibc or dietlibc or newlib or one of the others had at least the 
capability to distinguish and ignore it.  Glibc isn't the only C library used 
on Linux.

> 4. Providing guidance on writing programs portable across Unix systems.

SUSv3 is available online:
http://www.opengroup.org/onlinepubs/009695399/
http://www.opengroup.org/onlinepubs/009695399/idx/xsh_chap02.html
http://www.opengroup.org/onlinepubs/009695399/idx/functions.html

When I want "portable", I look there.

> 5. Providing information on historical variations in the Linux kernel
> and glibc interfaces -- in other words, providing guidance for
> programmers writing programs portable across Linux kernel and glibc
> versions.

Sure.  As a computer history buff, I'm all for it.

As a programmer, it's not usually what I'm looking for when I open a man page, 
and if I wanted to look at Red Hat 7's man pages I have 
http://archive.download.redhat.com and qemu...

> > (If you're programming against glibc I assume that has its own
> > documentation somewhere.)
>
> An interesting surmise.  There is the glibc manual.  But
>
> 1. Many people (greatly) prefer man(1) format
> 2. The glibc manual is far from complete.  (Often there is a man page
> for a glibc function, but no info page; sometimes the reverse is also
> true.)
> 3. The glibc manual often doesn't seem to cover details of historical
> changes in the glibc interface, or to document bugs.
> 4. Oftentimes a function's man page is better (more info, and/or a
> better (or any) example program) than the glibc info page (sometimes,
> the reverse is true, but often that changes after I find out about
> it).

Doing the whole codependent enabler thing and compensating for deficiencies 
glibc's own documentation so they don't feel the need to is fine, but if it 
gets in the way of documenting the actual kernel system calls in section 2, I 
personally find the result less useful.

I try not to criticize the work of volunteers, I just sent the original email 
to point out that the documentation hadn't proved useful for _me_.  That 
turned out to be because my screen ended at what seemed like the end of the 
documentation, and I didn't hit page down to make sure.  My mistake.

> > I suppose those of us programming against uClibc or
> > other low level interfaces can always just look at the kernel source
> > code.
>
> (Not sure of where you mean to go with that statement.)

What I meant is that if section 2 man pages prefer to document some glibc 
wrapper rather than the actual kernel interface, if all else fails I can 
always look at the kernel's source code to see what interface the kernel 
actually exposes to userspace.

I occasionally run a program built against glibc under strace to see what 
system call it's making and what parameters are passed into that call, then 
look at the kernel source code to see what function that gets dispatched to 
and what it does with those arguments.  I really really really prefer not to 
do this, but if all else fails it's a useful debugging trick.

I can also look at the glibc headers, which is good for most system calls.  (I 
have yet to bother looking at the glibc source code.)

In this case, the information was documented, I just didn't see it.  As I 
said, my bad for not knowing that a page ending with:

> RETURN VALUE
>        On  success,  zero is returned.  On error, -1 is returned, and errno
> is set appropriately.
>
> ERRORS
>        EFAULT buf is not valid.
>
> CONFORMING TO
>        SVr4, POSIX.1-2001.  There is no uname() call in 4.3BSD.

Was not actually the end of the page, but that if I paged down there were 
"notes", "see also", and "colophon" sections.  (Idiosyncrasy of the way "less" 
works on Ubuntu; if you scroll down to the end of the page it then says you're 
on line "1/90 28%", but until you've scrolled to the end it won't do any 
readahead to figure out how much is left, so it looks like there isn't any.  
Learn something new every day...)

Rob

Re: Query about uname.

[Michael Kerrisk]

On Sun, Nov 30, 2008 at 8:27 PM, Rob Landley <rob@landley.net> wrote:
> On Saturday 29 November 2008 07:08:43 Michael Kerrisk wrote:
>> [CC+= linux-msan@, which is where man-pages discussions really belong...]
>
> I wonder what linux-doc is for?

Something else.

>> > Posix doesn't specify init or mount either.  "Posix doesn't specify"
>> > doesn't forbid something else from specifying it.
>>
>> I think you somewhat misunderstand "unspecified".  For a wise
>> application writer, this means: avoid relying on specific behaviors
>> here if you want to write portable and future-proof programs.
>
> Perhaps I'm strange in trying to treat Linux as a platform I want to write
> software for.  I'm all for future-proofing, but after a binary's compiled
> there's not a whole lot you can do about it,

Untrue.  There are often things you can do *before* the binary is
compiled, so as to avoid relying on unspecified details.

[...]

>> >> And indeed, a portable program should not care.
>> >
>> > When I start writing portable programs that I intend to support on
>> > Dragonfly BSD, I'll let you know.  "Posix portable" includes Windows NT
>> > and strange IBM mainframes.
>>
>> Sure, but the man-pages are written for a general audience, many of
>> whom most certainly *do* care about portability.
>
> As long as that general audience doesn't _exclude_ people who think that Linux
> is a platform in its own right,

I'm not sure where this idea of yours even comes from?  It's certainly
not the intent of man-pages...

[...]

>> >> It seems to me that all the info you needed was there in the page, but
>> >> you didn't read the whole page.
>> >
>> > True.  I didn't notice that there was a "notes" field (my screen ended
>> > with "return value", "errors", and "conforming to", didn't hit page down)
>> > that was larger than the rest of the page.  My bad.
>> >
>> >> The question is, whether the page
>> >> could/should provide more clues to make sure that the reader is
>> >> pointed to the fine details (which, for the reasons I described above,
>> >> are often not needed).
>> >
>> > I thought the point of the man pages on kernel.org was to document the
>> > kernel API.
>>
>> See http://www.kernel.org/doc/man-pages/
>>
>> And especially, have a good look at
>> http://www.kernel.org/doc/man-pages/maintaining.html
>
> I read the first five screens full, and skimmed the first three pages of the
> first link (man 7 man-pages).  I assume there's a policy statement buried
> somewhere under there, but didn't dig far enough to find it.
>
> I was under the impression that man page section 2 was about the kernel, and
> man page section 3 was about glibc.

Life is not so simple, because of (g)libc wrappers.

>> Man-pages serves many purposes -- a probably incomplete list, in no
>> particular order:
>>
>> 1.Documenting the kernel API
>> 2. Documenting the glibc API
>> 3. Managing the sometimes tricky balance between the first two goals
>> when there is a glibc wrapper that is non-trivial and changes the
>> interface of the underlying system call.
>
> I'm aware of this.  I thought the kernel.org pages would document the kernel,
> because glibc has its own documentation and nothing else is going to.  If it
> wants to document how glibc does things as well, I'd like to if people using
> klibc or uClibc or dietlibc or newlib or one of the others had at least the
> capability to distinguish and ignore it.

Ideally (the pages in man-pages are not perfect), this capability
exists.  If you look in section 2 pages, you'll *often* see notes that
point out what's added to the kernel by glibc.

> Glibc isn't the only C library used
> on Linux.

But it is the one used by the overwhelming majority of applications.

>> 4. Providing guidance on writing programs portable across Unix systems.
>
> SUSv3 is available online:
> http://www.opengroup.org/onlinepubs/009695399/
> http://www.opengroup.org/onlinepubs/009695399/idx/xsh_chap02.html
> http://www.opengroup.org/onlinepubs/009695399/idx/functions.html
>
> When I want "portable", I look there.

Good for you.

>> 5. Providing information on historical variations in the Linux kernel
>> and glibc interfaces -- in other words, providing guidance for
>> programmers writing programs portable across Linux kernel and glibc
>> versions.
>
> Sure.  As a computer history buff, I'm all for it.
>
> As a programmer, it's not usually what I'm looking for when I open a man page,
> and if I wanted to look at Red Hat 7's man pages I have
> http://archive.download.redhat.com and qemu...

Maybe you don't; some programmers do though.

>> > (If you're programming against glibc I assume that has its own
>> > documentation somewhere.)
>>
>> An interesting surmise.  There is the glibc manual.  But
>>
>> 1. Many people (greatly) prefer man(1) format
>> 2. The glibc manual is far from complete.  (Often there is a man page
>> for a glibc function, but no info page; sometimes the reverse is also
>> true.)
>> 3. The glibc manual often doesn't seem to cover details of historical
>> changes in the glibc interface, or to document bugs.
>> 4. Oftentimes a function's man page is better (more info, and/or a
>> better (or any) example program) than the glibc info page (sometimes,
>> the reverse is true, but often that changes after I find out about
>> it).
>
> Doing the whole codependent enabler thing and compensating for deficiencies

Okay -- at this point your tone is starting to grate (more).  By your
own admission, you are unaware of many details of the origins, goals,
and operation of the man-pages project.  If you have specific
suggestions on how to improve specific pages, send them,  So far,
mostly it looks like you are arm waving, and, by now, starting to get
disrespectful with it.  If you want to offer suggestions or advice
about what the project does, or should do, they'll be much better
received if you first educate yourself about the project and why it
does things the way it does.

[...]

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html

Re: Query about uname.

[Randy Dunlap]

On Sun, 30 Nov 2008 19:27:27 -0600 Rob Landley wrote:

> On Saturday 29 November 2008 07:08:43 Michael Kerrisk wrote:
> > [CC+= linux-msan@, which is where man-pages discussions really belong...]
> 
> I wonder what linux-doc is for?

It's for Linux documentation that's in the kernel tree.
Or for doc tools that the Linux kernel uses.

---
~Randy

Re: Query about uname.

[Michael Kerrisk]

On Fri, Nov 28, 2008 at 4:00 PM, Michael Kerrisk
<mtk.manpages-gM/Ye1E23mwN+BqQ9rBEUg@public.gmane.org> wrote:
[...]
> It seems to me that all the info you needed was there in the page, but
> you didn't read the whole page.  The question is, whether the page
> could/should provide more clues to make sure that the reader is
> pointed to the fine details (which, for the reasons I described above,
> are often not needed).

I added the words "(see NOTES)" to the sentence on in DESCRIPTION
mentioning that the field lengths are unspecified.  This will give the
reader a clue whetre to get more details, if needed.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Query about uname.

[Rob Landley]

On Thursday 04 December 2008 08:07:19 Michael Kerrisk wrote:
> I added the words "(see NOTES)" to the sentence on in DESCRIPTION
> mentioning that the field lengths are unspecified.  This will give the
> reader a clue whetre to get more details, if needed.

Thanks.

Rob