svn commit: r249355 - head/lib/libkvm

[Bruce Evans]

On Thu, 11 Apr 2013, Gleb Smirnoff wrote:

> On Thu, Apr 11, 2013 at 06:49:02PM +1000, Bruce Evans wrote:
> B> > On Thu, Apr 11, 2013 at 05:59:24PM +1000, Bruce Evans wrote:
> B> > B> > Modified:
> B> > B> >  head/lib/libkvm/kvm.h
> B> > B> >
> B> > B> > Modified: head/lib/libkvm/kvm.h
> B> > B> > ==============================================================================
> B> > B> > --- head/lib/libkvm/kvm.h	Thu Apr 11 07:02:27 2013	(r249354)
> B> > B> > +++ head/lib/libkvm/kvm.h	Thu Apr 11 07:30:49 2013	(r249355)
> B> > B> > @@ -34,7 +34,7 @@
> B> > B> > #define	_KVM_H_
> B> > B> >
> B> > B> > #include <sys/cdefs.h>
> B> > B> > -#include <sys/_types.h>
> B> > B>
> B> > B> The __uintXX_t types are declared here, and should be used, like the
> B> > B> __Xsize_t types already are.
> B> >
> B> > Why non-standard types should be used instead of standard ones?
> B>
> B> Sometimes because the namespace doesn't allow the standard ones, but
> B> here I was just saying to typedef just the standard ones that you need
> B> (only uint64_t?) as is done for size_t and ssize_t.  Including
> B> <sys/types.h> also turns the careful ifdefs for the latter into
> B> no-ops.
>
> What was the reason to avoid including types.h and typedefing size_t
> and ssize_t manually?

Just routine avoidance of namespace pollution.  This is easy in such a
simple header.

In 4.4BSD, kvm.h only included nlist.h and (redundantly) sys/cdefs.h.
Its read/write functions returned int and took unsigned count args,
with the latter not abbreviated as u_int, so it didn't need size_t or
ssize_t and didn't depend on sys/types.h.  FreeBSD broke this by using
size_t and ssize_t for its read/write functions, without even polluting
it by including sys/types.h, so it grew a dependency on sys/types.h.
Its old and new dependencies were and remain undocumented.

I fixed this using the typedefs (the old 4.4BSD ones in
<machine/ansi.h>, where many fewer than now had underscored versions
but ones for these 2 were already there).  I was fixing lots of
namespace pollution at the time including automatically detecting new
prerequisites but not new pollution for many headers.  So its namespace
grew minimally.  Its old and new namespace were and remain undocumented.

If it were a POSIX header, then it would be specified to to declare
size_t and ssize_t and to reserve kvm_, and not much else.  Except
newer versions of POSIX tend to be broken and say "the foo.h header
may make visible all of the symbols in [a long list of headers]".
POSIX has always allowed all symbols ending in _t to be declared as a
typedef in any header, so including sys/types.h would not be not
namespace pollution for it.  However, FreeBSD's sys/types.h declares
many other symbols.  So many that they are hard to list and harder to
document.

The list of symbols declared in or reserved for for kvm.h is fairly short:
- size_t, ssize_t and kvm_*, as above 
- all symbols in nlist.h.  This is a bug, but nlist.h is fairly clean
- VRS_SYM and VRS_KEY.  These probably shouldn't be public.  They are
   not documented in kvm.h of course.
- struct tags kinfo_proc and proc
- struct member names ksw_*
- SWIF_DEV_PREFIX.  This is needed for using kvm_getswapinfo(), but it
   is not documented.  More precisely, it is misdocumented as "the flags
   argument is currently unused and must be 0", but the flags argument
   is used for this flag.  This flag is passed mainly by pstat/pstat.c.

Your change to use uint64_t without declaring it gave a new prerequisite
just like the old change that I fixed.  It is interesting that the
problem was found much more quickly.  It lived for 3 months in 1998.
Now there is the tinderbox to find such problems, and apparently less
pollution that hides them.

Bruce