Re: Document EVFILT_FS and VQ_*

On Tuesday, September 21, 2010 8:22:24 am Baptiste Daroussin wrote:
> Hi,
> 
> For a projects I needed to use EVFILT_FS and saw that it hasn't been documented
> so here is a patch to document it http://planet.etoilebsd.net/kqueue.2.diff
> 
> It is based on the commit message for the implementation of EVFILT_FS, sorry I
> don't know how to better document it
> (http://lists.freebsd.org/pipermail/cvs-src/2005-September/052288.html)

Hmm, the code for this seems quite broken.  For example, when an NFS mount is
marked up, it posts an event saying it is down.  Right now when the user gets
an EVFILT_FS event, the info in the event contains a mask of states that have
changed, but the code would still need to issue a VFS_CTL_QUERY sysctl to get
the actual state.  It would be more useful if the kevent could return two
values: 1) would be a bitmask of changed flags, and 2) would be the current
state of the vfs query flags.  Perhaps 2) could be implemented in kn_data,
but we would need to change the kernel to keep the current state of the
vfs query flags in 'struct mount' (this could be done in vfs_event_signal()).
Doing so would also allow VFS_CTL_QUERY to be implemented generically.

> While using it I also discover that VQ_MOUNT, VQ_UMOUNT, VQ_NOTRESP and
> VQ_NOTRESPLOCK are not documented either but I don't know where to document
> them.

VFS_CTL_QUERY is not really documented either.  For now I think you could
document all of this in kevent(2).  At the very least, you should note that
for EVFILT_FS, the 'flags' field is a bitmask of changed flags that can be
queried via VFS_CTL_QUERY.  If the code is changed to provide the current
flags in 'data', then you could just document the flags explicitly and not
bother mentioning VFS_CTL_QUERY.

-- 
John Baldwin