Re: [PATCH 09/11] exportfs: update Exporting documentation

["J. Bruce Fields" <bfields@redhat.com>]

On Thu, Jun 05, 2014 at 08:51:21AM -0400, Marc Dionne wrote:
> On Wed, Jun 4, 2014 at 5:21 PM, J. Bruce Fields <bfields@redhat.com> wrote:
> > From: "J. Bruce Fields" <bfields@redhat.com>
> >
> > Minor documentation updates:
> >         - refer to d_obtain_alias rather than d_alloc_anon
> >         - explain when to use d_splice_alias and when
> >           d_materialise_unique.
> >         - cut some details of d_splice_alias/d_materialise_unique
> >           implementation.
> >
> > Signed-off-by: J. Bruce Fields <bfields@redhat.com>
> > ---
> >  Documentation/filesystems/nfs/Exporting |   38 +++++++++++++++++++------------
> >  1 file changed, 23 insertions(+), 15 deletions(-)
> >
> > diff --git a/Documentation/filesystems/nfs/Exporting b/Documentation/filesystems/nfs/Exporting
> > index e543b1a..9b7de5b 100644
> > --- a/Documentation/filesystems/nfs/Exporting
> > +++ b/Documentation/filesystems/nfs/Exporting
> > @@ -66,23 +66,31 @@ b/ A per-superblock list "s_anon" of dentries which are the roots of
> >
> >  c/ Helper routines to allocate anonymous dentries, and to help attach
> >     loose directory dentries at lookup time. They are:
> > -    d_alloc_anon(inode) will return a dentry for the given inode.
> > +    d_obtain_alias(inode) will return a dentry for the given inode.
> >        If the inode already has a dentry, one of those is returned.
> >        If it doesn't, a new anonymous (IS_ROOT and
> >          DCACHE_DISCONNECTED) dentry is allocated and attached.
> >        In the case of a directory, care is taken that only one dentry
> >        can ever be attached.
> > -    d_splice_alias(inode, dentry) will make sure that there is a
> > -      dentry with the same name and parent as the given dentry, and
> > -      which refers to the given inode.
> > -      If the inode is a directory and already has a dentry, then that
> > -      dentry is d_moved over the given dentry.
> > -      If the passed dentry gets attached, care is taken that this is
> > -      mutually exclusive to a d_alloc_anon operation.
> > -      If the passed dentry is used, NULL is returned, else the used
> > -      dentry is returned.  This corresponds to the calling pattern of
> > -      ->lookup.
> > -
> > +    d_splice_alias(inode, dentry) or d_materialise_unique(dentry, inode)
> > +      will introduce a new dentry into the tree; either the passed-in
> > +      dentry or a preexisting alias for the given inode (such as an
> > +      anonymous one created by d_obtain_alias), if appropriate.  The two
> > +      functions differ in their handling of directories with preexisting
> > +      aliases:
> > +        d_splice_alias will use any existing IS_ROOT dentry, but it will
> > +         return -EIO rather than try to move a dentry with a different
> > +         parent.  This is appropriate for local filesystems, which
> > +         should never see such an alias unless the filesystem is
> > +         corrupted somehow (for example, if two on-disk directory
> > +         entries refer to the same directory.)
> > +       d_obtain_alias will attempt to move any dentry.  This is
> 
> Should this be d_materialise_unique instead of d_obtain_alias ?

Whoops, thanks for catching that.

Fixed in the version at

	git://linux-nfs.org/~bfields/linux-topics.git for-viro

--b.