Merge branch 'd_real' of git://git.kernel.org/pub/scm/linux/kernel/git/mszeredi/vfs...

[cascardo/linux.git] / Documentation / filesystems / vfs.txt

diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt
index d4e07c0..70a056f 100644 (file)
--- a/Documentation/filesystems/vfs.txt
+++ b/Documentation/filesystems/vfs.txt
@@ -364,7 +364,6 @@ struct inode_operations {
        int (*atomic_open)(struct inode *, struct dentry *, struct file *,
                        unsigned open_flag, umode_t create_mode, int *opened);
        int (*tmpfile) (struct inode *, struct dentry *, umode_t);
-       int (*dentry_open)(struct dentry *, struct file *, const struct cred *);
 };
 
 Again, all methods are called without any locks being held, unless
@@ -694,13 +693,6 @@ struct address_space_operations {
        but instead uses bmap to find out where the blocks in the file
        are and uses those addresses directly.
 
-  dentry_open: *WARNING: probably going away soon, do not use!* This is an
-       alternative to f_op->open(), the difference is that this method may open
-       a file not necessarily originating from the same filesystem as the one
-       i_op->open() was called on.  It may be useful for stacking filesystems
-       which want to allow native I/O directly on underlying files.
-
-
   invalidatepage: If a page has PagePrivate set, then invalidatepage
         will be called when part or all of the page is to be removed
        from the address space.  This generally corresponds to either a
@@ -936,6 +928,8 @@ struct dentry_operations {
        char *(*d_dname)(struct dentry *, char *, int);
        struct vfsmount *(*d_automount)(struct path *);
        int (*d_manage)(struct dentry *, bool);
+       struct dentry *(*d_real)(struct dentry *, const struct inode *,
+                                unsigned int);
 };
 
   d_revalidate: called when the VFS needs to revalidate a dentry. This
@@ -1020,6 +1014,14 @@ struct dentry_operations {
        at the end of the buffer, and returns a pointer to the first char.
        dynamic_dname() helper function is provided to take care of this.
 
+       Example :
+
+       static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen)
+       {
+               return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]",
+                               dentry->d_inode->i_ino);
+       }
+
   d_automount: called when an automount dentry is to be traversed (optional).
        This should create a new VFS mount record and return the record to the
        caller.  The caller is supplied with a path parameter giving the
@@ -1058,13 +1060,23 @@ struct dentry_operations {
        This function is only used if DCACHE_MANAGE_TRANSIT is set on the
        dentry being transited from.
 
-Example :
+  d_real: overlay/union type filesystems implement this method to return one of
+       the underlying dentries hidden by the overlay.  It is used in three
+       different modes:
 
-static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen)
-{
-       return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]",
-                               dentry->d_inode->i_ino);
-}
+       Called from open it may need to copy-up the file depending on the
+       supplied open flags.  This mode is selected with a non-zero flags
+       argument.  In this mode the d_real method can return an error.
+
+       Called from file_dentry() it returns the real dentry matching the inode
+       argument.  The real dentry may be from a lower layer already copied up,
+       but still referenced from the file.  This mode is selected with a
+       non-NULL inode argument.  This will always succeed.
+
+       With NULL inode and zero flags the topmost real underlying dentry is
+       returned.  This will always succeed.
+
+       This method is never called with both non-NULL inode and non-zero flags.
 
 Each dentry has a pointer to its parent dentry, as well as a hash list
 of child dentries. Child dentries are basically like files in a