[src/trunk]: src/share/man/man9 First draft of a long-awaited man page for ge...

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

details:   https://anonhg.NetBSD.org/src/rev/dd7b819031e3
branches:  trunk
changeset: 786564:dd7b819031e3
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Wed May 01 18:56:48 2013 +0000

description:
First draft of a long-awaited man page for genfs_rename(9).

diffstat:

 share/man/man9/genfs_rename.9 |  621 ++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 621 insertions(+), 0 deletions(-)

diffs (truncated from 625 to 300 lines):

diff -r 6fdf6cdac6b2 -r dd7b819031e3 share/man/man9/genfs_rename.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/genfs_rename.9     Wed May 01 18:56:48 2013 +0000
@@ -0,0 +1,621 @@
+.\"    $NetBSD: genfs_rename.9,v 1.1 2013/05/01 18:56:48 riastradh Exp $
+.\"
+.\" Copyright (c) 2013 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This documentation is derived from text contributed to The NetBSD
+.\" Foundation by Taylor R. Campbell.
+.\"
+.\" 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, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, 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 NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``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 FOUNDATION OR CONTRIBUTORS
+.\" 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.
+.\"
+.Dd May 1, 2013
+.Dt GENFS_RENAME 9
+.Os
+.Sh NAME
+.Nm genfs_rename ,
+.Nm genfs_insane_rename ,
+.Nm genfs_sane_rename
+.Nd generic framework for implementing
+.Xr VOP_RENAME 9
+.Sh SYNOPSIS
+.Ft int
+.Fo genfs_insane_rename
+.Fa "struct vop_rename_args *v"
+.Fa "int (*sane_rename)(struct vnode *fdvp, struct componentname *fcnp, struct vnode *tdvp, struct componentname *tcnp, kauth_cred_t, bool)"
+.Fc
+.Ft int
+.Fo genfs_sane_rename
+.Fa "const struct genfs_rename_ops *gro"
+.Fa "struct vnode *fdvp"
+.Fa "struct componentname *fcnp"
+.Fa "void *fde"
+.Fa "struct vnode *tdvp"
+.Fa "struct componentname *tcnp"
+.Fa "void *tde"
+.Fa "kauth_cred_t cred"
+.Fa "bool posixly_correct"
+.Fc
+.Ft int
+.Fo genfs_rename_knote
+.Fa "struct vnode *fdvp"
+.Fa "struct vnode *fvp"
+.Fa "struct vnode *tdvp"
+.Fa "struct vnode *tvp"
+.Fc
+.Ft void
+.Fo genfs_rename_cache_purge
+.Fa "struct vnode *fdvp"
+.Fa "struct vnode *fvp"
+.Fa "struct vnode *tdvp"
+.Fa "struct vnode *tvp"
+.Fc
+.Ft int
+.Fo genfs_ufslike_rename_check_possible
+.Fa "unsigned long fdflags"
+.Fa "unsigned long fflags"
+.Fa "unsigned long tdflags"
+.Fa "unsigned long tflags"
+.Fa "bool clobber"
+.Fa "unsigned long immutable"
+.Fa "unsigned long append"
+.Fc
+.Ft int
+.Fo genfs_ufslike_rename_check_permitted
+.Fa "kauth_cred_t cred"
+.Fa "struct vnode *fdvp"
+.Fa "mode_t fdmode"
+.Fa "uid_t fduid"
+.Fa "struct vnode *fvp"
+.Fa "uid_t fuid"
+.Fa "struct vnode *tdvp"
+.Fa "mode_t tdmode"
+.Fa "uid_t tduid"
+.Fa "struct vnode *tvp"
+.Fa "uid_t tuid"
+.Fc
+.Ft int
+.Fo genfs_ufslike_remove_check_possible
+.Fa "unsigned long dflags"
+.Fa "unsigned long flags"
+.Fa "unsigned long immutable"
+.Fa "unsigned long append"
+.Fc
+.Ft int
+.Fo genfs_ufslike_remove_check_permitted
+.Fa "kauth_cred_t cred"
+.Fa "struct vnode *dvp"
+.Fa "mode_t dmode"
+.Fa "uid_t duid"
+.Fa "struct vnode *vp"
+.Fa "uid_t uid"
+.Fc
+.Sh DESCRIPTION
+The
+.Nm
+functions provide a file-system-independent framework for implementing
+.Xr VOP_RENAME 9
+with correct locking and error-checking.
+.Pp
+Implementing rename is nontrivial.
+If you are doing it for a new file system, you should consider starting
+from
+.Fn tmpfs_rename
+as implemented in
+.Pa sys/fs/tmpfs/tmpfs_rename.c
+and adapting it to your file system's physical operations.
+.Pp
+Because there are so many moving parts to a rename operation,
+.Nm
+uses the following naming conventions:
+.Bl -tag -width indent
+.It Fa mp Pq "mount point"
+mount point of the file system in question
+.It Fa fdvp Pq "from directory vnode pointer"
+directory from which we are removing an entry
+.It Fa fcnp Pq "from componentname pointer"
+name of entry to remove from
+.Fa fdvp
+.It Fa fde Pq "from directory entry"
+fs-specific data about the entry in
+.Fa fdvp
+.It Fa fvp Pq "from vnode pointer"
+file at the entry named
+.Fa fcnp
+in
+.Fa fdvp
+.It Fa tdvp Pq "to directory vnode pointer"
+directory to which we are adding an entry
+.It Fa tcnp Pq "to componentname pointer"
+name of entry to add to
+.Fa tdvp
+.It Fa tde Pq "to directory entry"
+fs-specific data about the entry in
+.Fa tdvp
+.It Fa tvp Pq "to vnode pointer"
+file previously at the entry named
+.Fa tcnp
+in
+.Fa tdvp ,
+to be replaced, if any, or
+.Dv NULL
+if there was no entry before
+.It Fa vp Pq "vnode pointer"
+any file
+.It Fa dvp Pq "directory vnode pointer"
+any directory with an entry for
+.Fa vp
+.El
+.Pp
+A file system mumblefs should implement various file-system-dependent
+parts of the rename operation in a
+.Vt struct genfs_rename_ops ,
+and use
+.Nm
+to implement
+.Fn mumblefs_rename
+for
+.Xr VOP_RENAME 9
+as follows:
+.Bd -literal -offset indent
+static const struct genfs_rename_ops mumblefs_genfs_rename_ops;
+
+static int
+mumblefs_sane_rename(
+    struct vnode *fdvp, struct componentname *fcnp,
+    struct vnode *tdvp, struct componentname *tcnp,
+    kauth_cred_t cred, bool posixly_correct)
+{
+       struct mumblefs_lookup_results fulr, tulr;
+
+       return genfs_sane_rename(&mumblefs_genfs_rename_ops,
+           fdvp, fcnp, &fulr, tdvp, tcnp, &tulr,
+           cred, posixly_correct);
+}
+
+int
+mumblefs_rename(void *v)
+{
+
+       return genfs_insane_rename(v, &mumblefs_sane_rename);
+}
+.Ed
+.Pp
+The split between
+.Fn mumblefs_rename
+and
+.Fn mumblefs_sane_rename
+is designed to enable us to easily change the
+.Xr VOP_RENAME 9
+interface, which is currently designed for a broken (hence
+.Sq insane )
+locking scheme, to a more sensible locking scheme once all the file
+systems have their rename operations split up thus.
+.Pp
+The
+.Vt struct mumblefs_lookup_results
+structure is storage for information about directory entries which
+needs to pass from the lookups of the children (see the
+.Fa gro_lookup
+member of
+.Vt "struct genfs_rename_ops" )
+to the physical on-disk rename or remove operations (see the
+.Fa gro_rename
+and
+.Fa gro_remove
+members of
+.Vt "struct genfs_rename_ops" ) .
+.Pp
+Callers must implement the following operations as members in a
+.Vt struct genfs_rename_ops
+structure passed to
+.Nm :
+.Bl -tag -width indent
+.It Ft int Fn "(*gro_genealogy)" "struct mount *mp" "kauth_cred_t cred" "struct vnode *fdvp" "struct vnode *tdvp" "struct vnode **intermediate_node_ret"
+Walk up the directory tree from the directory vnode
+.Fa tdvp
+until hitting either
+.Fa fdvp
+or the root.
+If
+.Fa fdvp
+is hit, store the child of
+.Fa fdvp
+through which the path from
+.Fa tdvp
+passed in
+.Fa *intermediate_node_ret ,
+referenced but unlocked.
+If
+.Fa fdvp
+is not hit, store
+.Dv NULL
+in
+.Fa *intermediate_node_ret .
+Return zero on success or error on failure.
+(Failure means file-system-specific failures, not hitting or missing
+.Fa fdvp . )
+.Pp
+.Fa fdvp
+and
+.Fa tdvp
+are guaranteed to be distinct, nonnull, referenced, and unlocked.
+Since no locks are held on entry except for the file-system-wide rename
+lock,
+.Fa gro_genealogy
+may take any locks it pleases.
+.It Ft int Fn "(*gro_lock_directory)" "struct mount *mp" "struct vnode *vp"
+Lock the directory vnode
+.Fa vp ,
+but fail if it has been rmdired already.
+Return zero on success or error on failure.
+.It Ft int Fn "(*gro_lookup)" "struct mount *mp" "struct vnode *dvp" "struct componentname *cnp" "void *de" "struct vnode **vpp"
+Look up the entry in
+.Fa dvp
+for
+.Fa cnp ,
+storing the vnode in
+.Fa "*vpp"
+and using
+.Fa de ,
+one of the pointers passed to
+.Nm genfs_sane_rename ,
+to store information about the directory entry as needed by the file
+system's
+.Fa gro_rename
+operation, and return zero.
+If there is no such entry, return error.
+.Pp
+.Fa dvp
+is guaranteed to be locked, and the vnode returned in
+.Fa "*vpp"
+must be unlocked.
+However,
+.Fa gro_lookup
+may temporarily lock the vnode without causing deadlock.
+.It Ft bool Fn "(*gro_directory_empty_p)" "struct mount *mp" "kauth_cred_t cred" "struct vnode *vp" "struct vnode *dvp"
+Return true if the directory vnode
+.Fa vp