NetBSD Problem Report #45988

From www@NetBSD.org  Sun Feb 12 00:41:30 2012
Return-Path: <www@NetBSD.org>
Received: from mail.netbsd.org (mail.netbsd.org [149.20.53.66])
	by www.NetBSD.org (Postfix) with ESMTP id 7C93363D90F
	for <gnats-bugs@gnats.NetBSD.org>; Sun, 12 Feb 2012 00:41:30 +0000 (UTC)
Message-Id: <20120212004129.A510763B86B@www.NetBSD.org>
Date: Sun, 12 Feb 2012 00:41:29 +0000 (UTC)
From: gnrp@komkon2.de
Reply-To: gnrp@komkon2.de
To: gnats-bugs@NetBSD.org
Subject: vnodeops(9) does not contain the locking protocol for some functions
X-Send-Pr-Version: www-1.0

>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:          closed
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Feb 12 00:45:00 +0000 2012
>Closed-Date:    Mon Feb 13 12:50:23 +0000 2012
>Last-Modified:  Mon Feb 13 12:50:23 +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

>Release-Note:

>Audit-Trail:
From: "Thomas Klausner" <wiz@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/45988 CVS commit: src/share/man/man9
Date: Mon, 13 Feb 2012 12:49:35 +0000

 Module Name:	src
 Committed By:	wiz
 Date:		Mon Feb 13 12:49:35 UTC 2012

 Modified Files:
 	src/share/man/man9: vnodeops.9

 Log Message:
 Add locking description to some functions.
 Add FILES section referencing source code.
 From Julian Fagir in PR 45988.


 To generate a diff of this commit:
 cvs rdiff -u -r1.83 -r1.84 src/share/man/man9/vnodeops.9

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

State-Changed-From-To: open->closed
State-Changed-By: wiz@NetBSD.org
State-Changed-When: Mon, 13 Feb 2012 12:50:23 +0000
State-Changed-Why:
Committed, thanks!


>Unformatted:

Home	PR Database Search