diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index f1f14e15309a..0afeb43d608a 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -231,6 +231,7 @@ MAN= accept_filter.9 \ VFS_FHTOVP.9 \ vfs_getnewfsid.9 \ vfs_getvfs.9 \ + VFS_LOCK_GIANT.9 \ VFS_MOUNT.9 \ vfs_mount.9 \ vfs_mountedon.9 \ @@ -973,6 +974,7 @@ MLINKS+=vcount.9 count_dev.9 MLINKS+=vfsconf.9 vfs_modevent.9 \ vfsconf.9 vfs_register.9 \ vfsconf.9 vfs_unregister.9 +MLINKS+=VFS_LOCK_GIANT.9 VFS_UNLOCK_GIANT.9 MLINKS+=vgone.9 vgonel.9 MLINKS+=vhold.9 vdrop.9 MLINKS+=vm_map_lock.9 vm_map_lock_downgrade.9 \ diff --git a/share/man/man9/VFS_LOCK_GIANT.9 b/share/man/man9/VFS_LOCK_GIANT.9 new file mode 100644 index 000000000000..11aee93886d3 --- /dev/null +++ b/share/man/man9/VFS_LOCK_GIANT.9 @@ -0,0 +1,90 @@ +.\" +.\" Copyright (c) 2005 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +.\" DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 21, 2005 +.Dt VFS_LOCK_GIANT 9 +.Os +.Sh NAME +.Nm VFS_LOCK_GIANT , +.Nm VFS_UNLOCK_GIANT +.Nd "Conditionally lock and unlock Giant around entry into VFS" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VFS_LOCK_GIANT "struct mount *mp" +.Ft void +.Fn VFS_UNLOCK_GIANT "int vfslocked" +.Sh DESCRIPTION +.Fn VFS_LOCK_GIANT +will conditionally acquire the +.Dv Giant +lock if the file system referenced by +.Fa mp +is marked as MPSAFE or not, returning a flag indicating whether Giant was +set, which may later be passed to +.Fn VFS_UNLOCK_GIANT . +The value of +.Fa mp +will typically be derived from the mount pointer in a +.Xr vnode +on which a VFS operation will be performed. +.Pp +.Fn VFS_UNLOCK_GIANT +conditionally releases the +.Va Giant +lock if the passed +.Fa vfslocked +argument is non-zero. +It is expected that the argument will be derived from the return values of +.Vn VFS_LOCK_GIANT +or +.Xr NDHASGIANT 9 . +.Sh RETURN VALUES +.Fn VFS_LOCK_GIANT +returns a boolean indicating whether or not +.Va Giant +was acquired. +.Sh SEE ALSO +.Xr mutex 9 , +.Xr NDHASGIANT 9 , +.Xr vnode 9 +.Sh AUTHORS +MPSAFE VFS support for +.Fx +was implemented by +.An Jeff Roberson . +.Pp +This manual page was written by +.An Robert Watson . +.Sh BUGS +.Pp +Non-MPSAFE file systems exist, requiring callers conditional locking and +unlocking of +.Va Giant . diff --git a/share/man/man9/namei.9 b/share/man/man9/namei.9 index 9ddf5915f65e..7429a2790b78 100644 --- a/share/man/man9/namei.9 +++ b/share/man/man9/namei.9 @@ -1,6 +1,7 @@ .\" .\" Copyright (c) 1998, 1999 Eivind Eklund .\" Copyright (c) 2003 Hiten M. Pandya +.\" Copyright (c) 2005 Robert N. M. Watson .\" .\" All rights reserved. .\" @@ -38,7 +39,8 @@ .Sh NAME .Nm namei , .Nm NDINIT , -.Nm NDFREE +.Nm NDFREE , +.Nm NDHASGIANT .Nd pathname translation and lookup operations .Sh SYNOPSIS .In sys/param.h @@ -53,6 +55,8 @@ .Fc .Ft void .Fn NDFREE "struct nameidata *ndp" "const uint flags" +.Ft int +.Fn NDHASGIANT "struct nameidata *ndp" .Sh DESCRIPTION The .Nm @@ -69,6 +73,16 @@ or depending on whether the .Dv LOCKLEAF flag was specified or not. +If the +.Va Giant +lock is required, +.Nm +will acquire it if the caller indicates it is +.Dv MPSAFE , +in which case the caller must later release +.Va Giant +based on the results of +.Fn NDHASGIANT. .Pp The .Fn NDINIT @@ -154,6 +168,19 @@ This flag allows the function to return the parent (directory) vnode in an unlocked state. The parent vnode must be released separately by using .Xr vrele 9 . +.It Dv MPSAFE +With this flag set, +.Fn namei +will conditionally acquire +.Va Giant +if it is required by a traversed file system. +MPSAFE callers should pass the results of +.Fn NDHASGIANT +to +.Xr VFS_UNLOCK_GIANT +in order to conditionally release +.Va Giant +if necessary. .It Dv NOCACHE Avoid .Fn namei @@ -296,6 +323,7 @@ function. .Xr uio 9 , .Xr uma 9 , .Xr VFS 9 , +.Xr VFS_UNLOCK_GIANT 9 , .Xr vnode 9 , .Xr vput 9 , .Xr vref 9 @@ -317,3 +345,6 @@ In order to solve this for the cases where both and .Dv LOCKLEAF are used, it is necessary to resort to recursive locking. +.Pp +Non-MPSAFE file systems exist, requiring callers to conditionally unlock +.Va Giant .