From owner-freebsd-doc@FreeBSD.ORG Thu Nov 24 12:30:05 2005 Return-Path: X-Original-To: freebsd-doc@hub.freebsd.org Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 2CE9416A420 for ; Thu, 24 Nov 2005 12:30:05 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id D2E7B43D5A for ; Thu, 24 Nov 2005 12:30:02 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.13.3/8.13.3) with ESMTP id jAOCU2O0054021 for ; Thu, 24 Nov 2005 12:30:02 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.3/8.13.1/Submit) id jAOCU2QJ054017; Thu, 24 Nov 2005 12:30:02 GMT (envelope-from gnats) Resent-Date: Thu, 24 Nov 2005 12:30:02 GMT Resent-Message-Id: <200511241230.jAOCU2QJ054017@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Andriy Gapon Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id CB29C16A41F for ; Thu, 24 Nov 2005 12:23:50 +0000 (GMT) (envelope-from avg@topspin.kiev.ua) Received: from citadel.icyb.net.ua (citadel.icyb.net.ua [212.40.38.140]) by mx1.FreeBSD.org (Postfix) with ESMTP id BC45F43D5D for ; Thu, 24 Nov 2005 12:23:47 +0000 (GMT) (envelope-from avg@topspin.kiev.ua) Received: from oddity.topspin.kiev.ua (oddity-e.topspin.kiev.ua [212.40.38.87]) by citadel.icyb.net.ua (8.8.8p3/ICyb-2.3exp) with ESMTP id OAA15927 for ; Thu, 24 Nov 2005 14:23:41 +0200 (EET) (envelope-from avg@topspin.kiev.ua) Received: from oddity.topspin.kiev.ua (localhost [127.0.0.1]) by oddity.topspin.kiev.ua (8.13.3/8.13.1) with ESMTP id jAOCNf1B048775 for ; Thu, 24 Nov 2005 14:23:41 +0200 (EET) (envelope-from avg@oddity.topspin.kiev.ua) Received: (from avg@localhost) by oddity.topspin.kiev.ua (8.13.3/8.13.1/Submit) id jAOCNeTr048774; Thu, 24 Nov 2005 14:23:40 +0200 (EET) (envelope-from avg) Message-Id: <200511241223.jAOCNeTr048774@oddity.topspin.kiev.ua> Date: Thu, 24 Nov 2005 14:23:40 +0200 (EET) From: Andriy Gapon To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Cc: Subject: docs/89492: vfs doc: some VOP_*(9) manual pages are outdated with respect to vnode locking X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 24 Nov 2005 12:30:05 -0000 >Number: 89492 >Category: docs >Synopsis: vfs doc: some VOP_*(9) manual pages are outdated with respect to vnode locking >Confidential: no >Severity: non-critical >Priority: medium >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Thu Nov 24 12:30:02 GMT 2005 >Closed-Date: >Last-Modified: >Originator: Andriy Gapon >Release: FreeBSD 5.4-RELEASE-p3 i386 >Organization: >Environment: 6-STABLE, CURRENT >Description: 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. >How-To-Repeat: >Fix: >Release-Note: >Audit-Trail: >Unformatted: