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
9 #include <linux/kernel.h>
10 #include <linux/err.h>
11 #include <linux/list.h>
12 #include <linux/mutex.h>
13 #include <linux/idr.h>
14 #include <linux/lockdep.h>
15 #include <linux/rbtree.h>
16 #include <linux/atomic.h>
17 #include <linux/uidgid.h>
18 #include <linux/wait.h>
24 struct vm_area_struct;
26 struct file_system_type;
27 struct poll_table_struct;
30 struct kernfs_fs_context;
31 struct kernfs_open_node;
34 enum kernfs_node_type {
40 #define KERNFS_TYPE_MASK 0x000f
41 #define KERNFS_FLAG_MASK ~KERNFS_TYPE_MASK
43 enum kernfs_node_flag {
44 KERNFS_ACTIVATED = 0x0010,
46 KERNFS_HAS_SEQ_SHOW = 0x0040,
47 KERNFS_HAS_MMAP = 0x0080,
48 KERNFS_LOCKDEP = 0x0100,
49 KERNFS_SUICIDAL = 0x0400,
50 KERNFS_SUICIDED = 0x0800,
51 KERNFS_EMPTY_DIR = 0x1000,
52 KERNFS_HAS_RELEASE = 0x2000,
55 /* @flags for kernfs_create_root() */
56 enum kernfs_root_flag {
58 * kernfs_nodes are created in the deactivated state and invisible.
59 * They require explicit kernfs_activate() to become visible. This
60 * can be used to make related nodes become visible atomically
61 * after all nodes are created successfully.
63 KERNFS_ROOT_CREATE_DEACTIVATED = 0x0001,
66 * For regular files, if the opener has CAP_DAC_OVERRIDE, open(2)
67 * succeeds regardless of the RW permissions. sysfs had an extra
68 * layer of enforcement where open(2) fails with -EACCES regardless
69 * of CAP_DAC_OVERRIDE if the permission doesn't have the
70 * respective read or write access at all (none of S_IRUGO or
71 * S_IWUGO) or the respective operation isn't implemented. The
72 * following flag enables that behavior.
74 KERNFS_ROOT_EXTRA_OPEN_PERM_CHECK = 0x0002,
77 * The filesystem supports exportfs operation, so userspace can use
78 * fhandle to access nodes of the fs.
80 KERNFS_ROOT_SUPPORT_EXPORTOP = 0x0004,
83 /* type-specific structures for kernfs_node union members */
84 struct kernfs_elem_dir {
85 unsigned long subdirs;
86 /* children rbtree starts here and goes through kn->rb */
87 struct rb_root children;
90 * The kernfs hierarchy this directory belongs to. This fits
91 * better directly in kernfs_node but is here to save space.
93 struct kernfs_root *root;
96 struct kernfs_elem_symlink {
97 struct kernfs_node *target_kn;
100 struct kernfs_elem_attr {
101 const struct kernfs_ops *ops;
102 struct kernfs_open_node *open;
104 struct kernfs_node *notify_next; /* for kernfs_notify() */
108 * kernfs_node - the building block of kernfs hierarchy. Each and every
109 * kernfs node is represented by single kernfs_node. Most fields are
110 * private to kernfs and shouldn't be accessed directly by kernfs users.
112 * As long as s_count reference is held, the kernfs_node itself is
113 * accessible. Dereferencing elem or any other outer entity requires
119 #ifdef CONFIG_DEBUG_LOCK_ALLOC
120 struct lockdep_map dep_map;
123 * Use kernfs_get_parent() and kernfs_name/path() instead of
124 * accessing the following two fields directly. If the node is
125 * never moved to a different parent, it is safe to access the
128 struct kernfs_node *parent;
133 const void *ns; /* namespace tag */
134 unsigned int hash; /* ns + name hash */
136 struct kernfs_elem_dir dir;
137 struct kernfs_elem_symlink symlink;
138 struct kernfs_elem_attr attr;
144 * 64bit unique ID. On 64bit ino setups, id is the ino. On 32bit,
145 * the low 32bits are ino and upper generation.
149 unsigned short flags;
151 struct kernfs_iattrs *iattr;
155 * kernfs_syscall_ops may be specified on kernfs_create_root() to support
156 * syscalls. These optional callbacks are invoked on the matching syscalls
157 * and can perform any kernfs operations which don't necessarily have to be
158 * the exact operation requested. An active reference is held for each
159 * kernfs_node parameter.
161 struct kernfs_syscall_ops {
162 int (*show_options)(struct seq_file *sf, struct kernfs_root *root);
164 int (*mkdir)(struct kernfs_node *parent, const char *name,
166 int (*rmdir)(struct kernfs_node *kn);
167 int (*rename)(struct kernfs_node *kn, struct kernfs_node *new_parent,
168 const char *new_name);
169 int (*show_path)(struct seq_file *sf, struct kernfs_node *kn,
170 struct kernfs_root *root);
174 /* published fields */
175 struct kernfs_node *kn;
176 unsigned int flags; /* KERNFS_ROOT_* flags */
178 /* private fields, do not use outside kernfs proper */
182 struct kernfs_syscall_ops *syscall_ops;
184 /* list of kernfs_super_info of this root, protected by kernfs_mutex */
185 struct list_head supers;
187 wait_queue_head_t deactivate_waitq;
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);
261 #ifdef CONFIG_DEBUG_LOCK_ALLOC
262 struct lock_class_key lockdep_key;
267 * The kernfs superblock creation/mount parameter context.
269 struct kernfs_fs_context {
270 struct kernfs_root *root; /* Root of the hierarchy being mounted */
271 void *ns_tag; /* Namespace tag of the mount (or NULL) */
272 unsigned long magic; /* File system specific magic number */
274 /* The following are set/used by kernfs_mount() */
275 bool new_sb_created; /* Set to T if we allocated a new sb */
280 static inline enum kernfs_node_type kernfs_type(struct kernfs_node *kn)
282 return kn->flags & KERNFS_TYPE_MASK;
285 static inline ino_t kernfs_id_ino(u64 id)
287 /* id is ino if ino_t is 64bit; otherwise, low 32bits */
288 if (sizeof(ino_t) >= sizeof(u64))
294 static inline u32 kernfs_id_gen(u64 id)
296 /* gen is fixed at 1 if ino_t is 64bit; otherwise, high 32bits */
297 if (sizeof(ino_t) >= sizeof(u64))
303 static inline ino_t kernfs_ino(struct kernfs_node *kn)
305 return kernfs_id_ino(kn->id);
308 static inline ino_t kernfs_gen(struct kernfs_node *kn)
310 return kernfs_id_gen(kn->id);
314 * kernfs_enable_ns - enable namespace under a directory
315 * @kn: directory of interest, should be empty
317 * This is to be called right after @kn is created to enable namespace
318 * under it. All children of @kn must have non-NULL namespace tags and
319 * only the ones which match the super_block's tag will be visible.
321 static inline void kernfs_enable_ns(struct kernfs_node *kn)
323 WARN_ON_ONCE(kernfs_type(kn) != KERNFS_DIR);
324 WARN_ON_ONCE(!RB_EMPTY_ROOT(&kn->dir.children));
325 kn->flags |= KERNFS_NS;
329 * kernfs_ns_enabled - test whether namespace is enabled
330 * @kn: the node to test
332 * Test whether namespace filtering is enabled for the children of @ns.
334 static inline bool kernfs_ns_enabled(struct kernfs_node *kn)
336 return kn->flags & KERNFS_NS;
339 int kernfs_name(struct kernfs_node *kn, char *buf, size_t buflen);
340 int kernfs_path_from_node(struct kernfs_node *root_kn, struct kernfs_node *kn,
341 char *buf, size_t buflen);
342 void pr_cont_kernfs_name(struct kernfs_node *kn);
343 void pr_cont_kernfs_path(struct kernfs_node *kn);
344 struct kernfs_node *kernfs_get_parent(struct kernfs_node *kn);
345 struct kernfs_node *kernfs_find_and_get_ns(struct kernfs_node *parent,
346 const char *name, const void *ns);
347 struct kernfs_node *kernfs_walk_and_get_ns(struct kernfs_node *parent,
348 const char *path, const void *ns);
349 void kernfs_get(struct kernfs_node *kn);
350 void kernfs_put(struct kernfs_node *kn);
352 struct kernfs_node *kernfs_node_from_dentry(struct dentry *dentry);
353 struct kernfs_root *kernfs_root_from_sb(struct super_block *sb);
354 struct inode *kernfs_get_inode(struct super_block *sb, struct kernfs_node *kn);
356 struct dentry *kernfs_node_dentry(struct kernfs_node *kn,
357 struct super_block *sb);
358 struct kernfs_root *kernfs_create_root(struct kernfs_syscall_ops *scops,
359 unsigned int flags, void *priv);
360 void kernfs_destroy_root(struct kernfs_root *root);
362 struct kernfs_node *kernfs_create_dir_ns(struct kernfs_node *parent,
363 const char *name, umode_t mode,
364 kuid_t uid, kgid_t gid,
365 void *priv, const void *ns);
366 struct kernfs_node *kernfs_create_empty_dir(struct kernfs_node *parent,
368 struct kernfs_node *__kernfs_create_file(struct kernfs_node *parent,
369 const char *name, umode_t mode,
370 kuid_t uid, kgid_t gid,
372 const struct kernfs_ops *ops,
373 void *priv, const void *ns,
374 struct lock_class_key *key);
375 struct kernfs_node *kernfs_create_link(struct kernfs_node *parent,
377 struct kernfs_node *target);
378 void kernfs_activate(struct kernfs_node *kn);
379 void kernfs_remove(struct kernfs_node *kn);
380 void kernfs_break_active_protection(struct kernfs_node *kn);
381 void kernfs_unbreak_active_protection(struct kernfs_node *kn);
382 bool kernfs_remove_self(struct kernfs_node *kn);
383 int kernfs_remove_by_name_ns(struct kernfs_node *parent, const char *name,
385 int kernfs_rename_ns(struct kernfs_node *kn, struct kernfs_node *new_parent,
386 const char *new_name, const void *new_ns);
387 int kernfs_setattr(struct kernfs_node *kn, const struct iattr *iattr);
388 __poll_t kernfs_generic_poll(struct kernfs_open_file *of,
389 struct poll_table_struct *pt);
390 void kernfs_notify(struct kernfs_node *kn);
392 int kernfs_xattr_get(struct kernfs_node *kn, const char *name,
393 void *value, size_t size);
394 int kernfs_xattr_set(struct kernfs_node *kn, const char *name,
395 const void *value, size_t size, int flags);
397 const void *kernfs_super_ns(struct super_block *sb);
398 int kernfs_get_tree(struct fs_context *fc);
399 void kernfs_free_fs_context(struct fs_context *fc);
400 void kernfs_kill_sb(struct super_block *sb);
402 void kernfs_init(void);
404 struct kernfs_node *kernfs_find_and_get_node_by_id(struct kernfs_root *root,
406 #else /* CONFIG_KERNFS */
408 static inline enum kernfs_node_type kernfs_type(struct kernfs_node *kn)
409 { return 0; } /* whatever */
411 static inline void kernfs_enable_ns(struct kernfs_node *kn) { }
413 static inline bool kernfs_ns_enabled(struct kernfs_node *kn)
416 static inline int kernfs_name(struct kernfs_node *kn, char *buf, size_t buflen)
419 static inline int kernfs_path_from_node(struct kernfs_node *root_kn,
420 struct kernfs_node *kn,
421 char *buf, size_t buflen)
424 static inline void pr_cont_kernfs_name(struct kernfs_node *kn) { }
425 static inline void pr_cont_kernfs_path(struct kernfs_node *kn) { }
427 static inline struct kernfs_node *kernfs_get_parent(struct kernfs_node *kn)
430 static inline struct kernfs_node *
431 kernfs_find_and_get_ns(struct kernfs_node *parent, const char *name,
434 static inline struct kernfs_node *
435 kernfs_walk_and_get_ns(struct kernfs_node *parent, const char *path,
439 static inline void kernfs_get(struct kernfs_node *kn) { }
440 static inline void kernfs_put(struct kernfs_node *kn) { }
442 static inline struct kernfs_node *kernfs_node_from_dentry(struct dentry *dentry)
445 static inline struct kernfs_root *kernfs_root_from_sb(struct super_block *sb)
448 static inline struct inode *
449 kernfs_get_inode(struct super_block *sb, struct kernfs_node *kn)
452 static inline struct kernfs_root *
453 kernfs_create_root(struct kernfs_syscall_ops *scops, unsigned int flags,
455 { return ERR_PTR(-ENOSYS); }
457 static inline void kernfs_destroy_root(struct kernfs_root *root) { }
459 static inline struct kernfs_node *
460 kernfs_create_dir_ns(struct kernfs_node *parent, const char *name,
461 umode_t mode, kuid_t uid, kgid_t gid,
462 void *priv, const void *ns)
463 { return ERR_PTR(-ENOSYS); }
465 static inline struct kernfs_node *
466 __kernfs_create_file(struct kernfs_node *parent, const char *name,
467 umode_t mode, kuid_t uid, kgid_t gid,
468 loff_t size, const struct kernfs_ops *ops,
469 void *priv, const void *ns, struct lock_class_key *key)
470 { return ERR_PTR(-ENOSYS); }
472 static inline struct kernfs_node *
473 kernfs_create_link(struct kernfs_node *parent, const char *name,
474 struct kernfs_node *target)
475 { return ERR_PTR(-ENOSYS); }
477 static inline void kernfs_activate(struct kernfs_node *kn) { }
479 static inline void kernfs_remove(struct kernfs_node *kn) { }
481 static inline bool kernfs_remove_self(struct kernfs_node *kn)
484 static inline int kernfs_remove_by_name_ns(struct kernfs_node *kn,
485 const char *name, const void *ns)
488 static inline int kernfs_rename_ns(struct kernfs_node *kn,
489 struct kernfs_node *new_parent,
490 const char *new_name, const void *new_ns)
493 static inline int kernfs_setattr(struct kernfs_node *kn,
494 const struct iattr *iattr)
497 static inline void kernfs_notify(struct kernfs_node *kn) { }
499 static inline int kernfs_xattr_get(struct kernfs_node *kn, const char *name,
500 void *value, size_t size)
503 static inline int kernfs_xattr_set(struct kernfs_node *kn, const char *name,
504 const void *value, size_t size, int flags)
507 static inline const void *kernfs_super_ns(struct super_block *sb)
510 static inline int kernfs_get_tree(struct fs_context *fc)
513 static inline void kernfs_free_fs_context(struct fs_context *fc) { }
515 static inline void kernfs_kill_sb(struct super_block *sb) { }
517 static inline void kernfs_init(void) { }
519 #endif /* CONFIG_KERNFS */
522 * kernfs_path - build full path of a given node
523 * @kn: kernfs_node of interest
524 * @buf: buffer to copy @kn's name into
525 * @buflen: size of @buf
527 * If @kn is NULL result will be "(null)".
529 * Returns the length of the full path. If the full length is equal to or
530 * greater than @buflen, @buf contains the truncated path with the trailing
531 * '\0'. On error, -errno is returned.
533 static inline int kernfs_path(struct kernfs_node *kn, char *buf, size_t buflen)
535 return kernfs_path_from_node(kn, NULL, buf, buflen);
538 static inline struct kernfs_node *
539 kernfs_find_and_get(struct kernfs_node *kn, const char *name)
541 return kernfs_find_and_get_ns(kn, name, NULL);
544 static inline struct kernfs_node *
545 kernfs_walk_and_get(struct kernfs_node *kn, const char *path)
547 return kernfs_walk_and_get_ns(kn, path, NULL);
550 static inline struct kernfs_node *
551 kernfs_create_dir(struct kernfs_node *parent, const char *name, umode_t mode,
554 return kernfs_create_dir_ns(parent, name, mode,
555 GLOBAL_ROOT_UID, GLOBAL_ROOT_GID,
559 static inline struct kernfs_node *
560 kernfs_create_file_ns(struct kernfs_node *parent, const char *name,
561 umode_t mode, kuid_t uid, kgid_t gid,
562 loff_t size, const struct kernfs_ops *ops,
563 void *priv, const void *ns)
565 struct lock_class_key *key = NULL;
567 #ifdef CONFIG_DEBUG_LOCK_ALLOC
568 key = (struct lock_class_key *)&ops->lockdep_key;
570 return __kernfs_create_file(parent, name, mode, uid, gid,
571 size, ops, priv, ns, key);
574 static inline struct kernfs_node *
575 kernfs_create_file(struct kernfs_node *parent, const char *name, umode_t mode,
576 loff_t size, const struct kernfs_ops *ops, void *priv)
578 return kernfs_create_file_ns(parent, name, mode,
579 GLOBAL_ROOT_UID, GLOBAL_ROOT_GID,
580 size, ops, priv, NULL);
583 static inline int kernfs_remove_by_name(struct kernfs_node *parent,
586 return kernfs_remove_by_name_ns(parent, name, NULL);
589 static inline int kernfs_rename(struct kernfs_node *kn,
590 struct kernfs_node *new_parent,
591 const char *new_name)
593 return kernfs_rename_ns(kn, new_parent, new_name, NULL);
596 #endif /* __LINUX_KERNFS_H */