Re: CVS commit: src/lib/libc/stdio

[Jukka Ruohonen <jruohonen%iki.fi@localhost>]

On Wed, May 05, 2010 at 12:58:13AM +0700, Robert Elz wrote:
>   | As something like gets() has been standardized for ages, it makes sense to
>   | explicitly note that this may no longer be true (with respect to POSIX).
> 
> That's where I disagree, it is just bloat - once it stops being a standardised
> function, just stop calling it one.   If the doc notes that fgets() is
> POSIX, and says nothing about gets(), the implication is quite clear, isn't
> it?

I think the term "bloat" hardly ever applies to manual pages. If anything,
they are often too terse. A paragraph or two about history or standards
never hurts anyone. Two additional things:

1.  This would make sense if we can be 100 % sure that possible
    standardization is always mentioned in the manual pages. But based
    on my experience with the manual pages, this is not true at all.

2.  The standards differ. Someone may target SUSv3 but not SUSv4. Just as
    people still may want to write ANSI C instead of C99 in some settings.

> That history will be in the CVS logs.   That's enough for maintainers.
> For others reading the man page, this is all irrelevant (it would almost

I think the history is relevant or at least interesting; one of the
intriguing things about UNIX, really.

Often, as a reader, the most interesting thing about a manual page is not
the prototype nor the description, but maybe a note about a history ("this
came from v7 UNIX, who would've guessed?"), some small insight or detail,
recommended usage scenarios, an example, the caveats, or the references.
Standards-jargon is part of all this.

> be better if doc of gets() was deleted completely - the function has to
> remain, but there's no good reason to tell people they can use it if
> they're not already doing that.(

As it is documented in gets(3), ANSI C is the only reason for it to exist.
Because of this, it probably can never be removed.

> I doubt glibc would ever remove anything that important, and I'm very 
> confident
> that NetBSD never will - recommend against using it, sure - change all
> NetBSD code to avoid its use, definitely (that's probably already happened),
> but remove it (from libc, regardless of where else it might be added) - not
> a chance.   That's not just gets(), it is everything (that's documented)
> which is in libc.

As Jörg noted, gets() is not really a good example here. A lot of legacy
functions were (rightly) marked as obsolete and removed from the IEEE/POSIX
standards. I wouldn't put my money on the assumption that Linux maintainers
would not ever remove these. And in NetBSD some libc-functions have already
been moved to compat -- I would welcome such transitions even more, but that
is a different story.

- Jukka.