kern/45988: vnodeops(9) does not contain the locking protocol for some functions

[gnrp%komkon2.de@localhost]

>Number:         45988
>Category:       kern
>Synopsis:       vnodeops(9) does not contain the locking protocol for some 
>functions
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    kern-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Feb 12 00:45:00 +0000 2012
>Originator:     Julian Fagir
>Release:        current
>Organization:
>Environment:
>Description:
For several functions, the vnodeops(9) manpage does not say anything about the 
locking protocol of the operation.

Though people say, it's wasted effort, keeping it up to date is cheap.
Plus, adding the FILES section to add a comment for the file 
src/sys/kern/vnode_if.src so people can look the locking protocol and 
definitions up theirselves.
>How-To-Repeat:

>Fix:
--- ./share/man/man9/vnodeops.9
+++ ./share/man/man9/vnodeops.9
@@ -565,10 +565,14 @@
 .Fa vap .
 Attributes which are not available are set to the value VNOVAL.
 .Pp
 For more information on vnode attributes see
 .Xr vattr 9 .
+.Pp
+The vnode
+.Fa vp
+will be locked on entry and should remain locked on return.
 .It Fn VOP_SETATTR "vp" "vap" "cred"
 Set specific vnode attributes on a file.
 The argument
 .Fa vp
 is the locked vnode of the file to set the attributes for.
@@ -709,17 +713,25 @@
 that may have occurred for the file.
 The argument
 .Fa events
 is a set of flags as specified by
 .Xr poll 2 .
+.Pp
+The vnode
+.Fa vp
+remains unlocked throughout the whole operation.
 .It Fn VOP_KQFILTER "vp" "kn"
 Register a knote
 .Fa kn
 with the vnode
 .Fa vn .
 If the operation is successful zero is returned, otherwise an
 appropriate error code is returned.
+.Pp
+The vnode
+.Fa vp
+remains unlocked throughout the whole operation.
 .It Fn VOP_REVOKE "vp" "flags"
 Eliminate all activity associated with the vnode
 .Fa vp .
 The argument
 .Fa flags
@@ -729,10 +741,14 @@
 all vnodes aliased to the vnode
 .Fa vp
 are also eliminated.
 If the operation is successful zero is returned, otherwise an
 appropriate error is returned.
+.Pp
+The vnode
+.Fa vp
+remains unlocked throughout the whole operation.
 .It Fn VOP_MMAP "vp" "prot" "cred"
 Inform file system that
 .Fa vp
 is in the process of being memory mapped.
 The argument
@@ -1230,10 +1246,14 @@
 Whiteout pathname component in directory with vnode
 .Fa dvp .
 The argument
 .Fa cnp
 specifies the pathname component to whiteout.
+.Pp
+The vnode
+.Fa dvp
+should be locked on entry and will remain locked on return.
 .It Fn VOP_GETPAGES "vp" "offset" "m" "count" "centeridx" "access_type" 
"advice" "flags"
 Read VM pages from file.
 The argument
 .Fa vp
 is the locked vnode to read the VM pages from.
@@ -1405,11 +1425,19 @@
 specifies the extended attribute namespace.
 If full removal is not supported, the file system should return
 .Er EOPNOTSUPP
 to allow the caller to zero out the value with
 .Fn VOP_SETEXTATTR .
+.Pp
+The vnode
+.Fa vp
+should be locked on entry and will remain locked on return.
 .El
+.Sh FILES
+.Pa src/sys/kern/vnode_if.src
+contains the list of vnode functions, their definitions and an exact locking 
+protocol.
 .Sh ERRORS
 .Bl -tag -width Er
 .It Bq Er EACCES
 Access for the specified operation is denied.
 .It Bq Er EDQUOT