filesystems/nfs/exporting.rst

7 --------
9 All filesystem operations require a dentry (or two) as a starting
10 point.  Local applications have a reference-counted hold on suitable
12 applications that access a filesystem via a remote filesystem protocol
13 such as NFS may not be able to hold such a reference, and so need a
14 different way to refer to a particular dentry.  As the alternative
16 server-reboot (among other things, though these tend to be the most
23 This byte string will be called a "filehandle fragment" as it
26 A filesystem which supports the mapping between filehandle fragments
32 -------------
34 The dcache normally contains a proper prefix of any given filesystem
38 maintained easily (by each object maintaining a reference count on
41 However when objects are included into the dcache by interpreting a
42 filehandle fragment, there is no automatic creation of a path prefix
48 2. The dcache must be prepared for a newly found (via ->lookup) directory
49    to already have a (non-connected) dentry, and must be able to move
51    ->lookup).   This is particularly needed for directories as
52    it is a dcache invariant that directories only have one dentry.
56 a. A dentry flag DCACHE_DISCONNECTED which is set on
58    This is set when anonymous dentries are created, and cleared when a
59    dentry is noticed to be a child of a dentry which is in the proper
60    prefix.  If the refcount on a dentry with this flag set
62    kept in the dcache.  If a dentry that is not already in the dcache
64    will be a allocated for each access, and discarded at the end of
67    Note that such a dentry can acquire children, name, ancestors, etc.
68    without losing DCACHE_DISCONNECTED - that flag is only cleared when
75 b. A primitive for creation of secondary roots - d_obtain_root(inode).
77    per-superblock list (->s_roots), so they can be located at umount
83     d_obtain_alias(inode) will return a dentry for the given inode.
84       If the inode already has a dentry, one of those is returned.
86       If it doesn't, a new anonymous (IS_ROOT and
89       In the case of a directory, care is taken that only one dentry
92     d_splice_alias(inode, dentry) will introduce a new dentry into the tree;
93       either the passed-in dentry or a preexisting alias for the given inode
95       It returns NULL when the passed-in dentry is used, following the calling
96       convention of ->lookup.
99 -----------------
101 For a filesystem to be exportable it must:
105       when ->lookup finds an inode for a given parent and name.
113       Typically the ->lookup routine will simply end with a::
120 A file system implementation declares that instances of the filesystem
122 super_block.  This field must point to a "struct export_operations"
126     Takes a dentry and creates a filehandle fragment which may later be used
127     to find or create a dentry for the same object.
130     Given a filehandle fragment, this should find the implied object and
131     create a dentry for it (possibly with d_obtain_alias).
134     Given a filehandle fragment, this should find the parent of the
135     implied object and create a dentry for it (possibly with
139     When given a dentry for a directory, this should return  a dentry for
142     so any filehandle lookup that requires finding a parent will fail.
143     ->lookup("..") is *not* used as a default as it can leave ".." entries
147     When given a parent dentry and a child dentry, this should find a name
150     supplied, a default implementation is provided which uses vfs_readdir
156     export_operations struct also includes a flags field that allows the
160 A filehandle fragment consists of an array of 1 or more 4byte words,
161 together with a one byte "type".
165 nuls.  Rather, the encode_fh routine should choose a "type" which
170 -----------------------
172 contains a "flags" field that allows the filesystem to communicate to nfsd
176   EXPORT_OP_NOWCC - disable NFSv3 WCC attributes on this filesystem
187     this on filesystems that have an expensive ->getattr inode operation,
191   EXPORT_OP_NOSUBTREECHK - disallow subtree checking on this fs
195     ensure that the filehandle live on the filesystem. When only part of a
203   EXPORT_OP_CLOSE_BEFORE_UNLINK - always close cached files before unlinking
204     On some exportable filesystems (such as NFS) unlinking a file that
205     is still open can cause a fair bit of extra work. For instance,
206     the NFS client will do a "sillyrename" to ensure that the file
208     file is held by nfsd so we usually end up doing a sillyrename, and
213     calling into the vfs to do an unlink or a rename that would replace
216   EXPORT_OP_REMOTE_FS - Backing storage for this filesystem is remote
217     PF_LOCAL_THROTTLE exists for loopback NFSD, where a thread needs to
219     to another bdi (the client bdi). Such threads get a private balance
226   EXPORT_OP_NOATOMIC_ATTR - Filesystem does not update attributes atomically
229     NFSv4's change_info4. This boolean indicates to a client whether the
234   EXPORT_OP_FLUSH_ON_CLOSE - Filesystem flushes file data on close(2)
242   EXPORT_OP_ASYNC_LOCK - Indicates a capable filesystem to do async lock
244     it's own ->lock() functionality as core posix_lock_file() implementation
246     indicate an async lock request from a ->lock() file_operations struct, see