include/linux/exportfs.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 #ifndef LINUX_EXPORTFS_H
0003 #define LINUX_EXPORTFS_H 1
0004
0005 #include <linux/types.h>
0006
0007 struct dentry;
0008 struct iattr;
0009 struct inode;
0010 struct iomap;
0011 struct super_block;
0012 struct vfsmount;
0013
0014 /* limit the handle size to NFSv4 handle size now */
0015 #define MAX_HANDLE_SZ 128
0016
0017 /*
0018  * The fileid_type identifies how the file within the filesystem is encoded.
0019  * In theory this is freely set and parsed by the filesystem, but we try to
0020  * stick to conventions so we can share some generic code and don't confuse
0021  * sniffers like ethereal/wireshark.
0022  *
0023  * The filesystem must not use the value '0' or '0xff'.
0024  */
0025 enum fid_type {
0026     /*
0027      * The root, or export point, of the filesystem.
0028      * (Never actually passed down to the filesystem.
0029      */
0030     FILEID_ROOT = 0,
0031
0032     /*
0033      * 32bit inode number, 32 bit generation number.
0034      */
0035     FILEID_INO32_GEN = 1,
0036
0037     /*
0038      * 32bit inode number, 32 bit generation number,
0039      * 32 bit parent directory inode number.
0040      */
0041     FILEID_INO32_GEN_PARENT = 2,
0042
0043     /*
0044      * 64 bit object ID, 64 bit root object ID,
0045      * 32 bit generation number.
0046      */
0047     FILEID_BTRFS_WITHOUT_PARENT = 0x4d,
0048
0049     /*
0050      * 64 bit object ID, 64 bit root object ID,
0051      * 32 bit generation number,
0052      * 64 bit parent object ID, 32 bit parent generation.
0053      */
0054     FILEID_BTRFS_WITH_PARENT = 0x4e,
0055
0056     /*
0057      * 64 bit object ID, 64 bit root object ID,
0058      * 32 bit generation number,
0059      * 64 bit parent object ID, 32 bit parent generation,
0060      * 64 bit parent root object ID.
0061      */
0062     FILEID_BTRFS_WITH_PARENT_ROOT = 0x4f,
0063
0064     /*
0065      * 32 bit block number, 16 bit partition reference,
0066      * 16 bit unused, 32 bit generation number.
0067      */
0068     FILEID_UDF_WITHOUT_PARENT = 0x51,
0069
0070     /*
0071      * 32 bit block number, 16 bit partition reference,
0072      * 16 bit unused, 32 bit generation number,
0073      * 32 bit parent block number, 32 bit parent generation number
0074      */
0075     FILEID_UDF_WITH_PARENT = 0x52,
0076
0077     /*
0078      * 64 bit checkpoint number, 64 bit inode number,
0079      * 32 bit generation number.
0080      */
0081     FILEID_NILFS_WITHOUT_PARENT = 0x61,
0082
0083     /*
0084      * 64 bit checkpoint number, 64 bit inode number,
0085      * 32 bit generation number, 32 bit parent generation.
0086      * 64 bit parent inode number.
0087      */
0088     FILEID_NILFS_WITH_PARENT = 0x62,
0089
0090     /*
0091      * 32 bit generation number, 40 bit i_pos.
0092      */
0093     FILEID_FAT_WITHOUT_PARENT = 0x71,
0094
0095     /*
0096      * 32 bit generation number, 40 bit i_pos,
0097      * 32 bit parent generation number, 40 bit parent i_pos
0098      */
0099     FILEID_FAT_WITH_PARENT = 0x72,
0100
0101     /*
0102      * 128 bit child FID (struct lu_fid)
0103      * 128 bit parent FID (struct lu_fid)
0104      */
0105     FILEID_LUSTRE = 0x97,
0106
0107     /*
0108      * 64 bit unique kernfs id
0109      */
0110     FILEID_KERNFS = 0xfe,
0111
0112     /*
0113      * Filesystems must not use 0xff file ID.
0114      */
0115     FILEID_INVALID = 0xff,
0116 };
0117
0118 struct fid {
0119     union {
0120         struct {
0121             u32 ino;
0122             u32 gen;
0123             u32 parent_ino;
0124             u32 parent_gen;
0125         } i32;
0126         struct {
0127             u32 block;
0128             u16 partref;
0129             u16 parent_partref;
0130             u32 generation;
0131             u32 parent_block;
0132             u32 parent_generation;
0133         } udf;
0134         __u32 raw[0];
0135     };
0136 };
0137
0138 /**
0139  * struct export_operations - for nfsd to communicate with file systems
0140  * @encode_fh:      encode a file handle fragment from a dentry
0141  * @fh_to_dentry:   find the implied object and get a dentry for it
0142  * @fh_to_parent:   find the implied object's parent and get a dentry for it
0143  * @get_name:       find the name for a given inode in a given directory
0144  * @get_parent:     find the parent of a given directory
0145  * @commit_metadata: commit metadata changes to stable storage
0146  *
0147  * See Documentation/filesystems/nfs/exporting.rst for details on how to use
0148  * this interface correctly.
0149  *
0150  * encode_fh:
0151  *    @encode_fh should store in the file handle fragment @fh (using at most
0152  *    @max_len bytes) information that can be used by @decode_fh to recover the
0153  *    file referred to by the &struct dentry @de.  If the @connectable flag is
0154  *    set, the encode_fh() should store sufficient information so that a good
0155  *    attempt can be made to find not only the file but also it's place in the
0156  *    filesystem.   This typically means storing a reference to de->d_parent in
0157  *    the filehandle fragment.  encode_fh() should return the fileid_type on
0158  *    success and on error returns 255 (if the space needed to encode fh is
0159  *    greater than @max_len*4 bytes). On error @max_len contains the minimum
0160  *    size(in 4 byte unit) needed to encode the file handle.
0161  *
0162  * fh_to_dentry:
0163  *    @fh_to_dentry is given a &struct super_block (@sb) and a file handle
0164  *    fragment (@fh, @fh_len). It should return a &struct dentry which refers
0165  *    to the same file that the file handle fragment refers to.  If it cannot,
0166  *    it should return a %NULL pointer if the file cannot be found, or an
0167  *    %ERR_PTR error code of %ENOMEM if a memory allocation failure occurred.
0168  *    Any other error code is treated like %NULL, and will cause an %ESTALE error
0169  *    for callers of exportfs_decode_fh().
0170  *    Any suitable dentry can be returned including, if necessary, a new dentry
0171  *    created with d_alloc_root.  The caller can then find any other extant
0172  *    dentries by following the d_alias links.
0173  *
0174  * fh_to_parent:
0175  *    Same as @fh_to_dentry, except that it returns a pointer to the parent
0176  *    dentry if it was encoded into the filehandle fragment by @encode_fh.
0177  *
0178  * get_name:
0179  *    @get_name should find a name for the given @child in the given @parent
0180  *    directory.  The name should be stored in the @name (with the
0181  *    understanding that it is already pointing to a %NAME_MAX+1 sized
0182  *    buffer.   get_name() should return %0 on success, a negative error code
0183  *    or error.  @get_name will be called without @parent->i_mutex held.
0184  *
0185  * get_parent:
0186  *    @get_parent should find the parent directory for the given @child which
0187  *    is also a directory.  In the event that it cannot be found, or storage
0188  *    space cannot be allocated, a %ERR_PTR should be returned.
0189  *
0190  * commit_metadata:
0191  *    @commit_metadata should commit metadata changes to stable storage.
0192  *
0193  * Locking rules:
0194  *    get_parent is called with child->d_inode->i_mutex down
0195  *    get_name is not (which is possibly inconsistent)
0196  */
0197
0198 struct export_operations {
0199     int (*encode_fh)(struct inode *inode, __u32 *fh, int *max_len,
0200             struct inode *parent);
0201     struct dentry * (*fh_to_dentry)(struct super_block *sb, struct fid *fid,
0202             int fh_len, int fh_type);
0203     struct dentry * (*fh_to_parent)(struct super_block *sb, struct fid *fid,
0204             int fh_len, int fh_type);
0205     int (*get_name)(struct dentry *parent, char *name,
0206             struct dentry *child);
0207     struct dentry * (*get_parent)(struct dentry *child);
0208     int (*commit_metadata)(struct inode *inode);
0209
0210     int (*get_uuid)(struct super_block *sb, u8 *buf, u32 *len, u64 *offset);
0211     int (*map_blocks)(struct inode *inode, loff_t offset,
0212               u64 len, struct iomap *iomap,
0213               bool write, u32 *device_generation);
0214     int (*commit_blocks)(struct inode *inode, struct iomap *iomaps,
0215                  int nr_iomaps, struct iattr *iattr);
0216     u64 (*fetch_iversion)(struct inode *);
0217 #define EXPORT_OP_NOWCC         (0x1) /* don't collect v3 wcc data */
0218 #define EXPORT_OP_NOSUBTREECHK      (0x2) /* no subtree checking */
0219 #define EXPORT_OP_CLOSE_BEFORE_UNLINK   (0x4) /* close files before unlink */
0220 #define EXPORT_OP_REMOTE_FS     (0x8) /* Filesystem is remote */
0221 #define EXPORT_OP_NOATOMIC_ATTR     (0x10) /* Filesystem cannot supply
0222                           atomic attribute updates
0223                         */
0224     unsigned long   flags;
0225 };
0226
0227 extern int exportfs_encode_inode_fh(struct inode *inode, struct fid *fid,
0228                     int *max_len, struct inode *parent);
0229 extern int exportfs_encode_fh(struct dentry *dentry, struct fid *fid,
0230     int *max_len, int connectable);
0231 extern struct dentry *exportfs_decode_fh_raw(struct vfsmount *mnt,
0232                          struct fid *fid, int fh_len,
0233                          int fileid_type,
0234                          int (*acceptable)(void *, struct dentry *),
0235                          void *context);
0236 extern struct dentry *exportfs_decode_fh(struct vfsmount *mnt, struct fid *fid,
0237     int fh_len, int fileid_type, int (*acceptable)(void *, struct dentry *),
0238     void *context);
0239
0240 /*
0241  * Generic helpers for filesystems.
0242  */
0243 extern struct dentry *generic_fh_to_dentry(struct super_block *sb,
0244     struct fid *fid, int fh_len, int fh_type,
0245     struct inode *(*get_inode) (struct super_block *sb, u64 ino, u32 gen));
0246 extern struct dentry *generic_fh_to_parent(struct super_block *sb,
0247     struct fid *fid, int fh_len, int fh_type,
0248     struct inode *(*get_inode) (struct super_block *sb, u64 ino, u32 gen));
0249
0250 #endif /* LINUX_EXPORTFS_H */