[src/trunk]: src/share/man/man9 Adjustments based on suggestions from gnrp in...

[dholland <dholland%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/d751cd16b673
branches:  trunk
changeset: 330786:d751cd16b673
user:      dholland <dholland%NetBSD.org@localhost>
date:      Mon Jul 21 05:56:26 2014 +0000

description:
Adjustments based on suggestions from gnrp in PR 45276:
 - fix argument names of VOP_REMOVE
 - mention deprecated behavior of calling VOP_GETATTR unlocked
 - mention rename lock

diffstat:

 share/man/man9/vnodeops.9 |  17 ++++++++++++++---
 1 files changed, 14 insertions(+), 3 deletions(-)

diffs (57 lines):

diff -r 1e969baac6a3 -r d751cd16b673 share/man/man9/vnodeops.9
--- a/share/man/man9/vnodeops.9 Sun Jul 20 23:17:27 2014 +0000
+++ b/share/man/man9/vnodeops.9 Mon Jul 21 05:56:26 2014 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: vnodeops.9,v 1.93 2014/02/27 16:51:37 hannken Exp $
+.\"     $NetBSD: vnodeops.9,v 1.94 2014/07/21 05:56:26 dholland Exp $
 .\"
 .\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd February 27, 2014
+.Dd July 21, 2014
 .Dt VNODEOPS 9
 .Os
 .Sh NAME
@@ -135,7 +135,7 @@
 .Fn VOP_SEEK "struct vnode *vp" "off_t oldoff" "off_t newoff" \
 "kauth_cred_t cred"
 .Ft int
-.Fn VOP_REMOVE "struct vnode *vp" "struct vnode *vp" \
+.Fn VOP_REMOVE "struct vnode *dvp" "struct vnode *vp" \
 "struct componentname *cnp"
 .Ft int
 .Fn VOP_LINK "struct vnode *dvp" "struct vnode *vp" \
@@ -555,6 +555,10 @@
 .Pp
 For more information on vnode attributes see
 .Xr vattr 9 .
+Historically it was considered acceptable to call
+.Fn VOP_GETATTR
+without first locking the vnode.
+This usage is deprecated.
 .Pp
 The vnode
 .Fa vp
@@ -851,11 +855,18 @@
 If the operation is successful zero is returned, otherwise an error
 code is returned.
 .Pp
+The caller must hold the target file system's rename lock.
 The source directory and file vnodes should be unlocked and their
 reference counts should be incremented before entry.
 The target directory and file vnodes should both be locked on entry.
 .Fn VOP_RENAME
 updates the reference counts prior to returning.
+.Pp
+Because of the complexity and nastiness of the interface, please do
+not write new code that calls
+.Fn VOP_RENAME
+directly until such time as ongoing cleanup work reaches a point where
+the interface has been rendered halfway sane.
 .It Fn VOP_MKDIR "dvp" "vpp" "cnp" "vap"
 Make a new directory in a given directory.
 The argument