From owner-cvs-sys  Mon Sep 15 05:02:36 1997
Return-Path: <owner-cvs-sys>
Received: (from root@localhost)
          by hub.freebsd.org (8.8.7/8.8.7) id FAA24637
          for cvs-sys-outgoing; Mon, 15 Sep 1997 05:02:36 -0700 (PDT)
Received: from labinfo.iet.unipi.it (labinfo.iet.unipi.it [131.114.9.5])
          by hub.freebsd.org (8.8.7/8.8.7) with SMTP id FAA24607;
          Mon, 15 Sep 1997 05:01:59 -0700 (PDT)
Received: from localhost (luigi@localhost) by labinfo.iet.unipi.it (8.6.5/8.6.5) id MAA02405; Mon, 15 Sep 1997 12:38:44 +0200
From: Luigi Rizzo <luigi@labinfo.iet.unipi.it>
Message-Id: <199709151038.MAA02405@labinfo.iet.unipi.it>
Subject: Re: cvs commit: src/sys/i386/isa/snd - Imported sources
To: bde@zeta.org.au (Bruce Evans)
Date: Mon, 15 Sep 1997 12:38:44 +0200 (MET DST)
Cc: mike@smith.net.au, cvs-all@FreeBSD.ORG, cvs-committers@FreeBSD.ORG,
        cvs-sys@FreeBSD.ORG, jmg@FreeBSD.ORG
In-Reply-To: <199709150922.TAA08480@godzilla.zeta.org.au> from "Bruce Evans" at Sep 15, 97 07:22:19 pm
X-Mailer: ELM [version 2.4 PL23]
Content-Type: text
Sender: owner-cvs-sys@FreeBSD.ORG
X-Loop: FreeBSD.org
Precedence: bulk

> >I am trying to figure out the difference between select and poll,
> >it does not appear to be anything substantial, i.e. just a change
> >in arguments in ("events" instead of "rw") and out ("revents"
> >instead of 0/1). Is there any documentation somewhere ?
> 
> There are many examples in *.c.

The initial reason why I used FreeBSD was that it was _documented_ in
the 4.3 BSD book, and now 4.4 BSD book. I can study how a kernel
mechanism or interface is supposed to work, compare the description in
the book with actual code samples, etc.

Code alone is not enough, it might be broken and what is worse, people
might use it as a reference and duplicate it.

As an example, the select->poll change to asc.c has a missing

	return (revents)

in this case it is relatively easy to spot it out but this is not
always the case.

Documentation is of fundamental importance, especially for basic
mechanisms of large use.

> selrecord() is a BSD4.4Lite interface.  The above drivers apparently
> haven't been converted to it yet.

I have just filed a PR :)

	Cheers
	Luigi