Bug 89492 - vfs doc: some VOP_*(9) manual pages are outdated with respect to vnode locking
Summary: vfs doc: some VOP_*(9) manual pages are outdated with respect to vnode locking
Status: Open
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: freebsd-bugs (Nobody)
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2005-11-24 12:30 UTC by Andriy Gapon
Modified: 2018-04-10 18:12 UTC (History)
2 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Andriy Gapon 2005-11-24 12:30:02 UTC
After many fixes and enhancements done by jeff@ in the Spring of 2005 to
VFS code, some VOP_*(9) manual pages no longer contain valid information.
This can greately mislead people working on new filesystems for FreeBSD, 
or people maintainingg filesystems outside of FreeBSD source tree or people
porting filesystem code from/to earlier versions of FreeBSD.
The most notable change is different expectations on state of vnode lock
after completion of VOP_* calls. For example, VOP_LOOKUP(9) states:

http://www.freebsd.org/cgi/man.cgi?query=VOP_LOOKUP&apropos=0&sektion=9&manpath=FreeBSD+7.0-current&format=html
LOCKS
     The directory, dvp should be locked on entry.  If an error (note: the
     return value EJUSTRETURN is not considered an error) is detected, it will
     be returned locked.  Otherwise, it will be unlocked unless both
     LOCKPARENT and ISLASTCN are specified in cnp-_cn_flags.  If an entry is
     found in the directory, it will be returned locked.

This does not seem to be true any longer and dvp seems to be expected to
stay locked in all cases, because unlocking is done by code in vfs_lookup.c.
PSEUDOCODE section is also outdated in this respect.

Another example of such locking semantics change seems to be VOP_INACTIVE.

Although it is possible to reverse-engineer such changes from differences
in VFS code, this approach is time-consuming and error prone.
I think that it is best to kindly ask jeff@ to update the manual pages in
accordance to the changes that he made.
Comment 1 Tom Rhodes freebsd_committer 2008-01-24 00:07:44 UTC
Responsible Changed
From-To: freebsd-doc->attilio

Assign this to Attilio, who has been working on much of the locking and has 
interest in this as well.  Thanks!
Comment 2 Andriy Gapon freebsd_committer 2010-12-05 15:31:36 UTC
just curious what the current status of this is :-)

-- 
Andriy Gapon
Comment 3 Mark Linimon freebsd_committer freebsd_triage 2015-01-04 20:27:24 UTC
attilio has turned in  his commit bit.

To submitter: has this problem been fixed since it was filed?
Comment 4 Andriy Gapon freebsd_committer 2015-01-04 20:38:34 UTC
As far as I can see LOCKS section of VOP_LOOKUP(9) still has incorrect information.