1 /* SPDX-License-Identifier: GPL-2.0-only */
3 * kernfs.h - pseudo filesystem decoupled from vfs locking
6 #ifndef __LINUX_KERNFS_H
7 #define __LINUX_KERNFS_H
10 #include <linux/list.h>
11 #include <linux/mutex.h>
12 #include <linux/idr.h>
13 #include <linux/lockdep.h>
14 #include <linux/rbtree.h>
15 #include <linux/atomic.h>
16 #include <linux/bug.h>
17 #include <linux/types.h>
18 #include <linux/uidgid.h>
19 #include <linux/wait.h>
20 #include <linux/rwsem.h>
26 struct vm_area_struct;
27 struct vm_operations_struct;
29 struct file_system_type;
30 struct poll_table_struct;
33 struct kernfs_fs_context;
34 struct kernfs_open_node;
37 enum kernfs_node_type {
43 #define KERNFS_TYPE_MASK 0x000f
44 #define KERNFS_FLAG_MASK ~KERNFS_TYPE_MASK
45 #define KERNFS_MAX_USER_XATTRS 128
46 #define KERNFS_USER_XATTR_SIZE_LIMIT (128 << 10)
48 enum kernfs_node_flag {
49 KERNFS_ACTIVATED = 0x0010,
51 KERNFS_HAS_SEQ_SHOW = 0x0040,
52 KERNFS_HAS_MMAP = 0x0080,
53 KERNFS_LOCKDEP = 0x0100,
54 KERNFS_SUICIDAL = 0x0400,
55 KERNFS_SUICIDED = 0x0800,
56 KERNFS_EMPTY_DIR = 0x1000,
57 KERNFS_HAS_RELEASE = 0x2000,
60 /* @flags for kernfs_create_root() */
61 enum kernfs_root_flag {
63 * kernfs_nodes are created in the deactivated state and invisible.
64 * They require explicit kernfs_activate() to become visible. This
65 * can be used to make related nodes become visible atomically
66 * after all nodes are created successfully.
68 KERNFS_ROOT_CREATE_DEACTIVATED = 0x0001,
71 * For regular files, if the opener has CAP_DAC_OVERRIDE, open(2)
72 * succeeds regardless of the RW permissions. sysfs had an extra
73 * layer of enforcement where open(2) fails with -EACCES regardless
74 * of CAP_DAC_OVERRIDE if the permission doesn't have the
75 * respective read or write access at all (none of S_IRUGO or
76 * S_IWUGO) or the respective operation isn't implemented. The
77 * following flag enables that behavior.
79 KERNFS_ROOT_EXTRA_OPEN_PERM_CHECK = 0x0002,
82 * The filesystem supports exportfs operation, so userspace can use
83 * fhandle to access nodes of the fs.
85 KERNFS_ROOT_SUPPORT_EXPORTOP = 0x0004,
88 * Support user xattrs to be written to nodes rooted at this root.
90 KERNFS_ROOT_SUPPORT_USER_XATTR = 0x0008,
93 /* type-specific structures for kernfs_node union members */
94 struct kernfs_elem_dir {
95 unsigned long subdirs;
96 /* children rbtree starts here and goes through kn->rb */
97 struct rb_root children;
100 * The kernfs hierarchy this directory belongs to. This fits
101 * better directly in kernfs_node but is here to save space.
103 struct kernfs_root *root;
105 * Monotonic revision counter, used to identify if a directory
106 * node has changed during negative dentry revalidation.
111 struct kernfs_elem_symlink {
112 struct kernfs_node *target_kn;
115 struct kernfs_elem_attr {
116 const struct kernfs_ops *ops;
117 struct kernfs_open_node *open;
119 struct kernfs_node *notify_next; /* for kernfs_notify() */
123 * kernfs_node - the building block of kernfs hierarchy. Each and every
124 * kernfs node is represented by single kernfs_node. Most fields are
125 * private to kernfs and shouldn't be accessed directly by kernfs users.
127 * As long as count reference is held, the kernfs_node itself is
128 * accessible. Dereferencing elem or any other outer entity requires
134 #ifdef CONFIG_DEBUG_LOCK_ALLOC
135 struct lockdep_map dep_map;
138 * Use kernfs_get_parent() and kernfs_name/path() instead of
139 * accessing the following two fields directly. If the node is
140 * never moved to a different parent, it is safe to access the
143 struct kernfs_node *parent;
148 const void *ns; /* namespace tag */
149 unsigned int hash; /* ns + name hash */
151 struct kernfs_elem_dir dir;
152 struct kernfs_elem_symlink symlink;
153 struct kernfs_elem_attr attr;
159 * 64bit unique ID. On 64bit ino setups, id is the ino. On 32bit,
160 * the low 32bits are ino and upper generation.
164 unsigned short flags;
166 struct kernfs_iattrs *iattr;
170 * kernfs_syscall_ops may be specified on kernfs_create_root() to support
171 * syscalls. These optional callbacks are invoked on the matching syscalls
172 * and can perform any kernfs operations which don't necessarily have to be
173 * the exact operation requested. An active reference is held for each
174 * kernfs_node parameter.
176 struct kernfs_syscall_ops {
177 int (*show_options)(struct seq_file *sf, struct kernfs_root *root);
179 int (*mkdir)(struct kernfs_node *parent, const char *name,
181 int (*rmdir)(struct kernfs_node *kn);
182 int (*rename)(struct kernfs_node *kn, struct kernfs_node *new_parent,
183 const char *new_name);
184 int (*show_path)(struct seq_file *sf, struct kernfs_node *kn,
185 struct kernfs_root *root);
188 struct kernfs_node *kernfs_root_to_node(struct kernfs_root *root);
190 struct kernfs_open_file {
191 /* published fields */
192 struct kernfs_node *kn;
194 struct seq_file *seq_file;
197 /* private fields, do not use outside kernfs proper */
199 struct mutex prealloc_mutex;
201 struct list_head list;
204 size_t atomic_write_len;
207 const struct vm_operations_struct *vm_ops;
212 * Optional open/release methods. Both are called with
213 * @of->seq_file populated.
215 int (*open)(struct kernfs_open_file *of);
216 void (*release)(struct kernfs_open_file *of);
219 * Read is handled by either seq_file or raw_read().
221 * If seq_show() is present, seq_file path is active. Other seq
222 * operations are optional and if not implemented, the behavior is
223 * equivalent to single_open(). @sf->private points to the
224 * associated kernfs_open_file.
226 * read() is bounced through kernel buffer and a read larger than
227 * PAGE_SIZE results in partial operation of PAGE_SIZE.
229 int (*seq_show)(struct seq_file *sf, void *v);
231 void *(*seq_start)(struct seq_file *sf, loff_t *ppos);
232 void *(*seq_next)(struct seq_file *sf, void *v, loff_t *ppos);
233 void (*seq_stop)(struct seq_file *sf, void *v);
235 ssize_t (*read)(struct kernfs_open_file *of, char *buf, size_t bytes,
239 * write() is bounced through kernel buffer. If atomic_write_len
240 * is not set, a write larger than PAGE_SIZE results in partial
241 * operations of PAGE_SIZE chunks. If atomic_write_len is set,
242 * writes upto the specified size are executed atomically but
243 * larger ones are rejected with -E2BIG.
245 size_t atomic_write_len;
247 * "prealloc" causes a buffer to be allocated at open for
248 * all read/write requests. As ->seq_show uses seq_read()
249 * which does its own allocation, it is incompatible with
250 * ->prealloc. Provide ->read and ->write with ->prealloc.
253 ssize_t (*write)(struct kernfs_open_file *of, char *buf, size_t bytes,
256 __poll_t (*poll)(struct kernfs_open_file *of,
257 struct poll_table_struct *pt);
259 int (*mmap)(struct kernfs_open_file *of, struct vm_area_struct *vma);
263 * The kernfs superblock creation/mount parameter context.
265 struct kernfs_fs_context {
266 struct kernfs_root *root; /* Root of the hierarchy being mounted */
267 void *ns_tag; /* Namespace tag of the mount (or NULL) */
268 unsigned long magic; /* File system specific magic number */
270 /* The following are set/used by kernfs_mount() */
271 bool new_sb_created; /* Set to T if we allocated a new sb */
276 static inline enum kernfs_node_type kernfs_type(struct kernfs_node *kn)
278 return kn->flags & KERNFS_TYPE_MASK;
281 static inline ino_t kernfs_id_ino(u64 id)
283 /* id is ino if ino_t is 64bit; otherwise, low 32bits */
284 if (sizeof(ino_t) >= sizeof(u64))
290 static inline u32 kernfs_id_gen(u64 id)
292 /* gen is fixed at 1 if ino_t is 64bit; otherwise, high 32bits */
293 if (sizeof(ino_t) >= sizeof(u64))
299 static inline ino_t kernfs_ino(struct kernfs_node *kn)
301 return kernfs_id_ino(kn->id);
304 static inline ino_t kernfs_gen(struct kernfs_node *kn)
306 return kernfs_id_gen(kn->id);
310 * kernfs_enable_ns - enable namespace under a directory
311 * @kn: directory of interest, should be empty
313 * This is to be called right after @kn is created to enable namespace
314 * under it. All children of @kn must have non-NULL namespace tags and
315 * only the ones which match the super_block's tag will be visible.
317 static inline void kernfs_enable_ns(struct kernfs_node *kn)
319 WARN_ON_ONCE(kernfs_type(kn) != KERNFS_DIR);
320 WARN_ON_ONCE(!RB_EMPTY_ROOT(&kn->dir.children));
321 kn->flags |= KERNFS_NS;
325 * kernfs_ns_enabled - test whether namespace is enabled
326 * @kn: the node to test
328 * Test whether namespace filtering is enabled for the children of @ns.
330 static inline bool kernfs_ns_enabled(struct kernfs_node *kn)
332 return kn->flags & KERNFS_NS;
335 int kernfs_name(struct kernfs_node *kn, char *buf, size_t buflen);
336 int kernfs_path_from_node(struct kernfs_node *root_kn, struct kernfs_node *kn,
337 char *buf, size_t buflen);
338 void pr_cont_kernfs_name(struct kernfs_node *kn);
339 void pr_cont_kernfs_path(struct kernfs_node *kn);
340 struct kernfs_node *kernfs_get_parent(struct kernfs_node *kn);
341 struct kernfs_node *kernfs_find_and_get_ns(struct kernfs_node *parent,
342 const char *name, const void *ns);
343 struct kernfs_node *kernfs_walk_and_get_ns(struct kernfs_node *parent,
344 const char *path, const void *ns);
345 void kernfs_get(struct kernfs_node *kn);
346 void kernfs_put(struct kernfs_node *kn);
348 struct kernfs_node *kernfs_node_from_dentry(struct dentry *dentry);
349 struct kernfs_root *kernfs_root_from_sb(struct super_block *sb);
350 struct inode *kernfs_get_inode(struct super_block *sb, struct kernfs_node *kn);
352 struct dentry *kernfs_node_dentry(struct kernfs_node *kn,
353 struct super_block *sb);
354 struct kernfs_root *kernfs_create_root(struct kernfs_syscall_ops *scops,
355 unsigned int flags, void *priv);
356 void kernfs_destroy_root(struct kernfs_root *root);
358 struct kernfs_node *kernfs_create_dir_ns(struct kernfs_node *parent,
359 const char *name, umode_t mode,
360 kuid_t uid, kgid_t gid,
361 void *priv, const void *ns);
362 struct kernfs_node *kernfs_create_empty_dir(struct kernfs_node *parent,
364 struct kernfs_node *__kernfs_create_file(struct kernfs_node *parent,
365 const char *name, umode_t mode,
366 kuid_t uid, kgid_t gid,
368 const struct kernfs_ops *ops,
369 void *priv, const void *ns,
370 struct lock_class_key *key);
371 struct kernfs_node *kernfs_create_link(struct kernfs_node *parent,
373 struct kernfs_node *target);
374 void kernfs_activate(struct kernfs_node *kn);
375 void kernfs_remove(struct kernfs_node *kn);
376 void kernfs_break_active_protection(struct kernfs_node *kn);
377 void kernfs_unbreak_active_protection(struct kernfs_node *kn);
378 bool kernfs_remove_self(struct kernfs_node *kn);
379 int kernfs_remove_by_name_ns(struct kernfs_node *parent, const char *name,
381 int kernfs_rename_ns(struct kernfs_node *kn, struct kernfs_node *new_parent,
382 const char *new_name, const void *new_ns);
383 int kernfs_setattr(struct kernfs_node *kn, const struct iattr *iattr);
384 __poll_t kernfs_generic_poll(struct kernfs_open_file *of,
385 struct poll_table_struct *pt);
386 void kernfs_notify(struct kernfs_node *kn);
388 int kernfs_xattr_get(struct kernfs_node *kn, const char *name,
389 void *value, size_t size);
390 int kernfs_xattr_set(struct kernfs_node *kn, const char *name,
391 const void *value, size_t size, int flags);
393 const void *kernfs_super_ns(struct super_block *sb);
394 int kernfs_get_tree(struct fs_context *fc);
395 void kernfs_free_fs_context(struct fs_context *fc);
396 void kernfs_kill_sb(struct super_block *sb);
398 void kernfs_init(void);
400 struct kernfs_node *kernfs_find_and_get_node_by_id(struct kernfs_root *root,
402 #else /* CONFIG_KERNFS */
404 static inline enum kernfs_node_type kernfs_type(struct kernfs_node *kn)
405 { return 0; } /* whatever */
407 static inline void kernfs_enable_ns(struct kernfs_node *kn) { }
409 static inline bool kernfs_ns_enabled(struct kernfs_node *kn)
412 static inline int kernfs_name(struct kernfs_node *kn, char *buf, size_t buflen)
415 static inline int kernfs_path_from_node(struct kernfs_node *root_kn,
416 struct kernfs_node *kn,
417 char *buf, size_t buflen)
420 static inline void pr_cont_kernfs_name(struct kernfs_node *kn) { }
421 static inline void pr_cont_kernfs_path(struct kernfs_node *kn) { }
423 static inline struct kernfs_node *kernfs_get_parent(struct kernfs_node *kn)
426 static inline struct kernfs_node *
427 kernfs_find_and_get_ns(struct kernfs_node *parent, const char *name,
430 static inline struct kernfs_node *
431 kernfs_walk_and_get_ns(struct kernfs_node *parent, const char *path,
435 static inline void kernfs_get(struct kernfs_node *kn) { }
436 static inline void kernfs_put(struct kernfs_node *kn) { }
438 static inline struct kernfs_node *kernfs_node_from_dentry(struct dentry *dentry)
441 static inline struct kernfs_root *kernfs_root_from_sb(struct super_block *sb)
444 static inline struct inode *
445 kernfs_get_inode(struct super_block *sb, struct kernfs_node *kn)
448 static inline struct kernfs_root *
449 kernfs_create_root(struct kernfs_syscall_ops *scops, unsigned int flags,
451 { return ERR_PTR(-ENOSYS); }
453 static inline void kernfs_destroy_root(struct kernfs_root *root) { }
455 static inline struct kernfs_node *
456 kernfs_create_dir_ns(struct kernfs_node *parent, const char *name,
457 umode_t mode, kuid_t uid, kgid_t gid,
458 void *priv, const void *ns)
459 { return ERR_PTR(-ENOSYS); }
461 static inline struct kernfs_node *
462 __kernfs_create_file(struct kernfs_node *parent, const char *name,
463 umode_t mode, kuid_t uid, kgid_t gid,
464 loff_t size, const struct kernfs_ops *ops,
465 void *priv, const void *ns, struct lock_class_key *key)
466 { return ERR_PTR(-ENOSYS); }
468 static inline struct kernfs_node *
469 kernfs_create_link(struct kernfs_node *parent, const char *name,
470 struct kernfs_node *target)
471 { return ERR_PTR(-ENOSYS); }
473 static inline void kernfs_activate(struct kernfs_node *kn) { }
475 static inline void kernfs_remove(struct kernfs_node *kn) { }
477 static inline bool kernfs_remove_self(struct kernfs_node *kn)
480 static inline int kernfs_remove_by_name_ns(struct kernfs_node *kn,
481 const char *name, const void *ns)
484 static inline int kernfs_rename_ns(struct kernfs_node *kn,
485 struct kernfs_node *new_parent,
486 const char *new_name, const void *new_ns)
489 static inline int kernfs_setattr(struct kernfs_node *kn,
490 const struct iattr *iattr)
493 static inline void kernfs_notify(struct kernfs_node *kn) { }
495 static inline int kernfs_xattr_get(struct kernfs_node *kn, const char *name,
496 void *value, size_t size)
499 static inline int kernfs_xattr_set(struct kernfs_node *kn, const char *name,
500 const void *value, size_t size, int flags)
503 static inline const void *kernfs_super_ns(struct super_block *sb)
506 static inline int kernfs_get_tree(struct fs_context *fc)
509 static inline void kernfs_free_fs_context(struct fs_context *fc) { }
511 static inline void kernfs_kill_sb(struct super_block *sb) { }
513 static inline void kernfs_init(void) { }
515 #endif /* CONFIG_KERNFS */
518 * kernfs_path - build full path of a given node
519 * @kn: kernfs_node of interest
520 * @buf: buffer to copy @kn's name into
521 * @buflen: size of @buf
523 * If @kn is NULL result will be "(null)".
525 * Returns the length of the full path. If the full length is equal to or
526 * greater than @buflen, @buf contains the truncated path with the trailing
527 * '\0'. On error, -errno is returned.
529 static inline int kernfs_path(struct kernfs_node *kn, char *buf, size_t buflen)
531 return kernfs_path_from_node(kn, NULL, buf, buflen);
534 static inline struct kernfs_node *
535 kernfs_find_and_get(struct kernfs_node *kn, const char *name)
537 return kernfs_find_and_get_ns(kn, name, NULL);
540 static inline struct kernfs_node *
541 kernfs_walk_and_get(struct kernfs_node *kn, const char *path)
543 return kernfs_walk_and_get_ns(kn, path, NULL);
546 static inline struct kernfs_node *
547 kernfs_create_dir(struct kernfs_node *parent, const char *name, umode_t mode,
550 return kernfs_create_dir_ns(parent, name, mode,
551 GLOBAL_ROOT_UID, GLOBAL_ROOT_GID,
555 static inline int kernfs_remove_by_name(struct kernfs_node *parent,
558 return kernfs_remove_by_name_ns(parent, name, NULL);
561 static inline int kernfs_rename(struct kernfs_node *kn,
562 struct kernfs_node *new_parent,
563 const char *new_name)
565 return kernfs_rename_ns(kn, new_parent, new_name, NULL);
568 #endif /* __LINUX_KERNFS_H */