Commit | Line | Data |
---|---|---|
099c5c7a TH |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
90ac11a8 TH |
3 | ========================================= |
4 | Overview of the Linux Virtual File System | |
5 | ========================================= | |
1da177e4 | 6 | |
e66b0457 | 7 | Original author: Richard Gooch <rgooch@atnf.csiro.au> |
1da177e4 | 8 | |
e66b0457 TH |
9 | - Copyright (C) 1999 Richard Gooch |
10 | - Copyright (C) 2005 Pekka Enberg | |
1da177e4 | 11 | |
1da177e4 | 12 | |
cc7d1f8f PE |
13 | Introduction |
14 | ============ | |
1da177e4 | 15 | |
90caa781 TH |
16 | The Virtual File System (also known as the Virtual Filesystem Switch) is |
17 | the software layer in the kernel that provides the filesystem interface | |
18 | to userspace programs. It also provides an abstraction within the | |
19 | kernel which allows different filesystem implementations to coexist. | |
1da177e4 | 20 | |
90caa781 TH |
21 | VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on |
22 | are called from a process context. Filesystem locking is described in | |
ec23eb54 | 23 | the document Documentation/filesystems/locking.rst. |
1da177e4 | 24 | |
1da177e4 | 25 | |
cc7d1f8f PE |
26 | Directory Entry Cache (dcache) |
27 | ------------------------------ | |
1da177e4 | 28 | |
cc7d1f8f | 29 | The VFS implements the open(2), stat(2), chmod(2), and similar system |
4ee33ea4 | 30 | calls. The pathname argument that is passed to them is used by the VFS |
cc7d1f8f | 31 | to search through the directory entry cache (also known as the dentry |
4ee33ea4 TH |
32 | cache or dcache). This provides a very fast look-up mechanism to |
33 | translate a pathname (filename) into a specific dentry. Dentries live | |
cc7d1f8f PE |
34 | in RAM and are never saved to disc: they exist only for performance. |
35 | ||
4ee33ea4 | 36 | The dentry cache is meant to be a view into your entire filespace. As |
90caa781 TH |
37 | most computers cannot fit all dentries in the RAM at the same time, some |
38 | bits of the cache are missing. In order to resolve your pathname into a | |
39 | dentry, the VFS may have to resort to creating dentries along the way, | |
40 | and then loading the inode. This is done by looking up the inode. | |
cc7d1f8f PE |
41 | |
42 | ||
43 | The Inode Object | |
44 | ---------------- | |
45 | ||
4ee33ea4 | 46 | An individual dentry usually has a pointer to an inode. Inodes are |
cc7d1f8f | 47 | filesystem objects such as regular files, directories, FIFOs and other |
90caa781 TH |
48 | beasts. They live either on the disc (for block device filesystems) or |
49 | in the memory (for pseudo filesystems). Inodes that live on the disc | |
50 | are copied into the memory when required and changes to the inode are | |
51 | written back to disc. A single inode can be pointed to by multiple | |
cc7d1f8f PE |
52 | dentries (hard links, for example, do this). |
53 | ||
54 | To look up an inode requires that the VFS calls the lookup() method of | |
4ee33ea4 | 55 | the parent directory inode. This method is installed by the specific |
90caa781 TH |
56 | filesystem implementation that the inode lives in. Once the VFS has the |
57 | required dentry (and hence the inode), we can do all those boring things | |
58 | like open(2) the file, or stat(2) it to peek at the inode data. The | |
59 | stat(2) operation is fairly simple: once the VFS has the dentry, it | |
60 | peeks at the inode data and passes some of it back to userspace. | |
cc7d1f8f PE |
61 | |
62 | ||
63 | The File Object | |
64 | --------------- | |
1da177e4 LT |
65 | |
66 | Opening a file requires another operation: allocation of a file | |
90caa781 TH |
67 | structure (this is the kernel-side implementation of file descriptors). |
68 | The freshly allocated file structure is initialized with a pointer to | |
69 | the dentry and a set of file operation member functions. These are | |
70 | taken from the inode data. The open() file method is then called so the | |
71 | specific filesystem implementation can do its work. You can see that | |
72 | this is another switch performed by the VFS. The file structure is | |
73 | placed into the file descriptor table for the process. | |
1da177e4 LT |
74 | |
75 | Reading, writing and closing files (and other assorted VFS operations) | |
76 | is done by using the userspace file descriptor to grab the appropriate | |
cc7d1f8f | 77 | file structure, and then calling the required file structure method to |
4ee33ea4 | 78 | do whatever is required. For as long as the file is open, it keeps the |
cc7d1f8f | 79 | dentry in use, which in turn means that the VFS inode is still in use. |
1da177e4 | 80 | |
5ea626aa PE |
81 | |
82 | Registering and Mounting a Filesystem | |
cc7d1f8f | 83 | ===================================== |
1da177e4 | 84 | |
cc7d1f8f PE |
85 | To register and unregister a filesystem, use the following API |
86 | functions: | |
1da177e4 | 87 | |
af96c1e3 | 88 | .. code-block:: c |
1da177e4 | 89 | |
af96c1e3 TH |
90 | #include <linux/fs.h> |
91 | ||
92 | extern int register_filesystem(struct file_system_type *); | |
93 | extern int unregister_filesystem(struct file_system_type *); | |
1da177e4 | 94 | |
4ee33ea4 | 95 | The passed struct file_system_type describes your filesystem. When a |
90caa781 TH |
96 | request is made to mount a filesystem onto a directory in your |
97 | namespace, the VFS will call the appropriate mount() method for the | |
98 | specific filesystem. New vfsmount referring to the tree returned by | |
99 | ->mount() will be attached to the mountpoint, so that when pathname | |
100 | resolution reaches the mountpoint it will jump into the root of that | |
101 | vfsmount. | |
1da177e4 | 102 | |
cc7d1f8f PE |
103 | You can see all filesystems that are registered to the kernel in the |
104 | file /proc/filesystems. | |
1da177e4 LT |
105 | |
106 | ||
5ea626aa | 107 | struct file_system_type |
cc7d1f8f | 108 | ----------------------- |
1da177e4 | 109 | |
85bf9a0e | 110 | This describes the filesystem. The following |
1da177e4 LT |
111 | members are defined: |
112 | ||
af96c1e3 TH |
113 | .. code-block:: c |
114 | ||
6a2195a1 | 115 | struct file_system_type { |
af96c1e3 TH |
116 | const char *name; |
117 | int fs_flags; | |
85bf9a0e AM |
118 | int (*init_fs_context)(struct fs_context *); |
119 | const struct fs_parameter_spec *parameters; | |
af96c1e3 | 120 | struct dentry *(*mount) (struct file_system_type *, int, |
85bf9a0e | 121 | const char *, void *); |
af96c1e3 TH |
122 | void (*kill_sb) (struct super_block *); |
123 | struct module *owner; | |
124 | struct file_system_type * next; | |
85bf9a0e AM |
125 | struct hlist_head fs_supers; |
126 | ||
af96c1e3 TH |
127 | struct lock_class_key s_lock_key; |
128 | struct lock_class_key s_umount_key; | |
85bf9a0e AM |
129 | struct lock_class_key s_vfs_rename_key; |
130 | struct lock_class_key s_writers_key[SB_FREEZE_LEVELS]; | |
131 | ||
132 | struct lock_class_key i_lock_key; | |
133 | struct lock_class_key i_mutex_key; | |
134 | struct lock_class_key invalidate_lock_key; | |
135 | struct lock_class_key i_mutex_dir_key; | |
af96c1e3 TH |
136 | }; |
137 | ||
ee5dc049 TH |
138 | ``name`` |
139 | the name of the filesystem type, such as "ext2", "iso9660", | |
1da177e4 LT |
140 | "msdos" and so on |
141 | ||
ee5dc049 TH |
142 | ``fs_flags`` |
143 | various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.) | |
1da177e4 | 144 | |
85bf9a0e AM |
145 | ``init_fs_context`` |
146 | Initializes 'struct fs_context' ->ops and ->fs_private fields with | |
147 | filesystem-specific data. | |
148 | ||
149 | ``parameters`` | |
150 | Pointer to the array of filesystem parameters descriptors | |
151 | 'struct fs_parameter_spec'. | |
152 | More info in Documentation/filesystems/mount_api.rst. | |
153 | ||
ee5dc049 TH |
154 | ``mount`` |
155 | the method to call when a new instance of this filesystem should | |
156 | be mounted | |
1da177e4 | 157 | |
ee5dc049 TH |
158 | ``kill_sb`` |
159 | the method to call when an instance of this filesystem should be | |
160 | shut down | |
5ea626aa | 161 | |
1da177e4 | 162 | |
ee5dc049 TH |
163 | ``owner`` |
164 | for internal VFS use: you should initialize this to THIS_MODULE | |
165 | in most cases. | |
166 | ||
167 | ``next`` | |
168 | for internal VFS use: you should initialize this to NULL | |
5ea626aa | 169 | |
85bf9a0e AM |
170 | ``fs_supers`` |
171 | for internal VFS use: hlist of filesystem instances (superblocks) | |
172 | ||
173 | s_lock_key, s_umount_key, s_vfs_rename_key, s_writers_key, | |
174 | i_lock_key, i_mutex_key, invalidate_lock_key, i_mutex_dir_key: lockdep-specific | |
0746aec3 | 175 | |
1a102ff9 | 176 | The mount() method has the following arguments: |
1da177e4 | 177 | |
ee5dc049 TH |
178 | ``struct file_system_type *fs_type`` |
179 | describes the filesystem, partly initialized by the specific | |
180 | filesystem code | |
5ea626aa | 181 | |
ee5dc049 TH |
182 | ``int flags`` |
183 | mount flags | |
5ea626aa | 184 | |
ee5dc049 TH |
185 | ``const char *dev_name`` |
186 | the device name we are mounting. | |
1da177e4 | 187 | |
ee5dc049 TH |
188 | ``void *data`` |
189 | arbitrary mount options, usually comes as an ASCII string (see | |
190 | "Mount Options" section) | |
1da177e4 | 191 | |
1a102ff9 AV |
192 | The mount() method must return the root dentry of the tree requested by |
193 | caller. An active reference to its superblock must be grabbed and the | |
194 | superblock must be locked. On failure it should return ERR_PTR(error). | |
1da177e4 | 195 | |
90caa781 TH |
196 | The arguments match those of mount(2) and their interpretation depends |
197 | on filesystem type. E.g. for block filesystems, dev_name is interpreted | |
198 | as block device name, that device is opened and if it contains a | |
199 | suitable filesystem image the method creates and initializes struct | |
200 | super_block accordingly, returning its root dentry to caller. | |
1a102ff9 AV |
201 | |
202 | ->mount() may choose to return a subtree of existing filesystem - it | |
203 | doesn't have to create a new one. The main result from the caller's | |
90caa781 TH |
204 | point of view is a reference to dentry at the root of (sub)tree to be |
205 | attached; creation of new superblock is a common side effect. | |
1da177e4 | 206 | |
90caa781 TH |
207 | The most interesting member of the superblock structure that the mount() |
208 | method fills in is the "s_op" field. This is a pointer to a "struct | |
209 | super_operations" which describes the next level of the filesystem | |
210 | implementation. | |
1da177e4 | 211 | |
1a102ff9 | 212 | Usually, a filesystem uses one of the generic mount() implementations |
4ee33ea4 | 213 | and provides a fill_super() callback instead. The generic variants are: |
5ea626aa | 214 | |
ee5dc049 TH |
215 | ``mount_bdev`` |
216 | mount a filesystem residing on a block device | |
1da177e4 | 217 | |
ee5dc049 TH |
218 | ``mount_nodev`` |
219 | mount a filesystem that is not backed by a device | |
5ea626aa | 220 | |
ee5dc049 TH |
221 | ``mount_single`` |
222 | mount a filesystem which shares the instance between all mounts | |
5ea626aa | 223 | |
1a102ff9 | 224 | A fill_super() callback implementation has the following arguments: |
5ea626aa | 225 | |
ee5dc049 TH |
226 | ``struct super_block *sb`` |
227 | the superblock structure. The callback must initialize this | |
228 | properly. | |
5ea626aa | 229 | |
ee5dc049 TH |
230 | ``void *data`` |
231 | arbitrary mount options, usually comes as an ASCII string (see | |
232 | "Mount Options" section) | |
5ea626aa | 233 | |
ee5dc049 TH |
234 | ``int silent`` |
235 | whether or not to be silent on error | |
5ea626aa PE |
236 | |
237 | ||
cc7d1f8f PE |
238 | The Superblock Object |
239 | ===================== | |
240 | ||
241 | A superblock object represents a mounted filesystem. | |
242 | ||
243 | ||
5ea626aa | 244 | struct super_operations |
cc7d1f8f | 245 | ----------------------- |
1da177e4 LT |
246 | |
247 | This describes how the VFS can manipulate the superblock of your | |
592d8072 | 248 | filesystem. The following members are defined: |
1da177e4 | 249 | |
af96c1e3 TH |
250 | .. code-block:: c |
251 | ||
252 | struct super_operations { | |
253 | struct inode *(*alloc_inode)(struct super_block *sb); | |
254 | void (*destroy_inode)(struct inode *); | |
592d8072 | 255 | void (*free_inode)(struct inode *); |
af96c1e3 TH |
256 | |
257 | void (*dirty_inode) (struct inode *, int flags); | |
592d8072 AM |
258 | int (*write_inode) (struct inode *, struct writeback_control *wbc); |
259 | int (*drop_inode) (struct inode *); | |
260 | void (*evict_inode) (struct inode *); | |
af96c1e3 TH |
261 | void (*put_super) (struct super_block *); |
262 | int (*sync_fs)(struct super_block *sb, int wait); | |
880b9577 DW |
263 | int (*freeze_super) (struct super_block *sb, |
264 | enum freeze_holder who); | |
af96c1e3 | 265 | int (*freeze_fs) (struct super_block *); |
880b9577 DW |
266 | int (*thaw_super) (struct super_block *sb, |
267 | enum freeze_wholder who); | |
af96c1e3 TH |
268 | int (*unfreeze_fs) (struct super_block *); |
269 | int (*statfs) (struct dentry *, struct kstatfs *); | |
270 | int (*remount_fs) (struct super_block *, int *, char *); | |
af96c1e3 TH |
271 | void (*umount_begin) (struct super_block *); |
272 | ||
273 | int (*show_options)(struct seq_file *, struct dentry *); | |
592d8072 AM |
274 | int (*show_devname)(struct seq_file *, struct dentry *); |
275 | int (*show_path)(struct seq_file *, struct dentry *); | |
276 | int (*show_stats)(struct seq_file *, struct dentry *); | |
af96c1e3 TH |
277 | |
278 | ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); | |
279 | ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); | |
592d8072 AM |
280 | struct dquot **(*get_dquots)(struct inode *); |
281 | ||
282 | long (*nr_cached_objects)(struct super_block *, | |
283 | struct shrink_control *); | |
284 | long (*free_cached_objects)(struct super_block *, | |
285 | struct shrink_control *); | |
af96c1e3 | 286 | }; |
1da177e4 LT |
287 | |
288 | All methods are called without any locks being held, unless otherwise | |
4ee33ea4 | 289 | noted. This means that most methods can block safely. All methods are |
1da177e4 LT |
290 | only called from a process context (i.e. not from an interrupt handler |
291 | or bottom half). | |
292 | ||
ee5dc049 TH |
293 | ``alloc_inode`` |
294 | this method is called by alloc_inode() to allocate memory for | |
295 | struct inode and initialize it. If this function is not | |
50c1f43a TH |
296 | defined, a simple 'struct inode' is allocated. Normally |
297 | alloc_inode will be used to allocate a larger structure which | |
298 | contains a 'struct inode' embedded within it. | |
5ea626aa | 299 | |
ee5dc049 TH |
300 | ``destroy_inode`` |
301 | this method is called by destroy_inode() to release resources | |
302 | allocated for struct inode. It is only required if | |
50c1f43a | 303 | ->alloc_inode was defined and simply undoes anything done by |
341546f5 | 304 | ->alloc_inode. |
5ea626aa | 305 | |
592d8072 AM |
306 | ``free_inode`` |
307 | this method is called from RCU callback. If you use call_rcu() | |
308 | in ->destroy_inode to free 'struct inode' memory, then it's | |
309 | better to release memory in this method. | |
310 | ||
ee5dc049 | 311 | ``dirty_inode`` |
a38ed483 EB |
312 | this method is called by the VFS when an inode is marked dirty. |
313 | This is specifically for the inode itself being marked dirty, | |
314 | not its data. If the update needs to be persisted by fdatasync(), | |
315 | then I_DIRTY_DATASYNC will be set in the flags argument. | |
cbfecb92 LC |
316 | I_DIRTY_TIME will be set in the flags in case lazytime is enabled |
317 | and struct inode has times updated since the last ->dirty_inode | |
318 | call. | |
1da177e4 | 319 | |
ee5dc049 TH |
320 | ``write_inode`` |
321 | this method is called when the VFS needs to write an inode to | |
322 | disc. The second parameter indicates whether the write should | |
323 | be synchronous or not, not all filesystems check this flag. | |
1da177e4 | 324 | |
ee5dc049 TH |
325 | ``drop_inode`` |
326 | called when the last access to the inode is dropped, with the | |
327 | inode->i_lock spinlock held. | |
1da177e4 | 328 | |
5ea626aa | 329 | This method should be either NULL (normal UNIX filesystem |
ee5dc049 TH |
330 | semantics) or "generic_delete_inode" (for filesystems that do |
331 | not want to cache inodes - causing "delete_inode" to always be | |
1da177e4 LT |
332 | called regardless of the value of i_nlink) |
333 | ||
ee5dc049 TH |
334 | The "generic_delete_inode()" behavior is equivalent to the old |
335 | practice of using "force_delete" in the put_inode() case, but | |
336 | does not have the races that the "force_delete()" approach had. | |
1da177e4 | 337 | |
592d8072 AM |
338 | ``evict_inode`` |
339 | called when the VFS wants to evict an inode. Caller does | |
340 | *not* evict the pagecache or inode-associated metadata buffers; | |
341 | the method has to use truncate_inode_pages_final() to get rid | |
342 | of those. Caller makes sure async writeback cannot be running for | |
343 | the inode while (or after) ->evict_inode() is called. Optional. | |
1da177e4 | 344 | |
ee5dc049 TH |
345 | ``put_super`` |
346 | called when the VFS wishes to free the superblock | |
4ee33ea4 | 347 | (i.e. unmount). This is called with the superblock lock held |
1da177e4 | 348 | |
ee5dc049 TH |
349 | ``sync_fs`` |
350 | called when VFS is writing out all dirty data associated with a | |
351 | superblock. The second parameter indicates whether the method | |
4ee33ea4 | 352 | should wait until the write out has been completed. Optional. |
5ea626aa | 353 | |
592d8072 AM |
354 | ``freeze_super`` |
355 | Called instead of ->freeze_fs callback if provided. | |
356 | Main difference is that ->freeze_super is called without taking | |
357 | down_write(&sb->s_umount). If filesystem implements it and wants | |
358 | ->freeze_fs to be called too, then it has to call ->freeze_fs | |
359 | explicitly from this callback. Optional. | |
360 | ||
ee5dc049 TH |
361 | ``freeze_fs`` |
362 | called when VFS is locking a filesystem and forcing it into a | |
363 | consistent state. This method is currently used by the Logical | |
592d8072 AM |
364 | Volume Manager (LVM) and ioctl(FIFREEZE). Optional. |
365 | ||
366 | ``thaw_super`` | |
367 | called when VFS is unlocking a filesystem and making it writable | |
368 | again after ->freeze_super. Optional. | |
5ea626aa | 369 | |
ee5dc049 TH |
370 | ``unfreeze_fs`` |
371 | called when VFS is unlocking a filesystem and making it writable | |
592d8072 | 372 | again after ->freeze_fs. Optional. |
5ea626aa | 373 | |
ee5dc049 TH |
374 | ``statfs`` |
375 | called when the VFS needs to get filesystem statistics. | |
1da177e4 | 376 | |
ee5dc049 TH |
377 | ``remount_fs`` |
378 | called when the filesystem is remounted. This is called with | |
379 | the kernel lock held | |
1da177e4 | 380 | |
ee5dc049 TH |
381 | ``umount_begin`` |
382 | called when the VFS is unmounting a filesystem. | |
5ea626aa | 383 | |
ee5dc049 | 384 | ``show_options`` |
592d8072 AM |
385 | called by the VFS to show mount options for /proc/<pid>/mounts |
386 | and /proc/<pid>/mountinfo. | |
ee5dc049 | 387 | (see "Mount Options" section) |
5ea626aa | 388 | |
592d8072 AM |
389 | ``show_devname`` |
390 | Optional. Called by the VFS to show device name for | |
391 | /proc/<pid>/{mounts,mountinfo,mountstats}. If not provided then | |
392 | '(struct mount).mnt_devname' will be used. | |
393 | ||
394 | ``show_path`` | |
395 | Optional. Called by the VFS (for /proc/<pid>/mountinfo) to show | |
396 | the mount root dentry path relative to the filesystem root. | |
397 | ||
398 | ``show_stats`` | |
399 | Optional. Called by the VFS (for /proc/<pid>/mountstats) to show | |
400 | filesystem-specific mount statistics. | |
401 | ||
ee5dc049 TH |
402 | ``quota_read`` |
403 | called by the VFS to read from filesystem quota file. | |
5ea626aa | 404 | |
ee5dc049 TH |
405 | ``quota_write`` |
406 | called by the VFS to write to filesystem quota file. | |
5ea626aa | 407 | |
592d8072 AM |
408 | ``get_dquots`` |
409 | called by quota to get 'struct dquot' array for a particular inode. | |
410 | Optional. | |
411 | ||
ee5dc049 TH |
412 | ``nr_cached_objects`` |
413 | called by the sb cache shrinking function for the filesystem to | |
414 | return the number of freeable cached objects it contains. | |
0e1fdafd DC |
415 | Optional. |
416 | ||
ee5dc049 TH |
417 | ``free_cache_objects`` |
418 | called by the sb cache shrinking function for the filesystem to | |
419 | scan the number of objects indicated to try to free them. | |
420 | Optional, but any filesystem implementing this method needs to | |
421 | also implement ->nr_cached_objects for it to be called | |
422 | correctly. | |
0e1fdafd DC |
423 | |
424 | We can't do anything with any errors that the filesystem might | |
ee5dc049 TH |
425 | encountered, hence the void return type. This will never be |
426 | called if the VM is trying to reclaim under GFP_NOFS conditions, | |
427 | hence this method does not need to handle that situation itself. | |
0e1fdafd | 428 | |
ee5dc049 TH |
429 | Implementations must include conditional reschedule calls inside |
430 | any scanning loop that is done. This allows the VFS to | |
431 | determine appropriate scan batch sizes without having to worry | |
432 | about whether implementations will cause holdoff problems due to | |
433 | large scan batch sizes. | |
8ab47664 | 434 | |
90caa781 TH |
435 | Whoever sets up the inode is responsible for filling in the "i_op" |
436 | field. This is a pointer to a "struct inode_operations" which describes | |
437 | the methods that can be performed on individual inodes. | |
1da177e4 | 438 | |
e04c83cd | 439 | |
4746be1d | 440 | struct xattr_handler |
6c6ef9f2 AG |
441 | --------------------- |
442 | ||
443 | On filesystems that support extended attributes (xattrs), the s_xattr | |
90caa781 TH |
444 | superblock field points to a NULL-terminated array of xattr handlers. |
445 | Extended attributes are name:value pairs. | |
6c6ef9f2 | 446 | |
ee5dc049 TH |
447 | ``name`` |
448 | Indicates that the handler matches attributes with the specified | |
449 | name (such as "system.posix_acl_access"); the prefix field must | |
450 | be NULL. | |
6c6ef9f2 | 451 | |
ee5dc049 TH |
452 | ``prefix`` |
453 | Indicates that the handler matches all attributes with the | |
454 | specified name prefix (such as "user."); the name field must be | |
455 | NULL. | |
6c6ef9f2 | 456 | |
ee5dc049 TH |
457 | ``list`` |
458 | Determine if attributes matching this xattr handler should be | |
459 | listed for a particular dentry. Used by some listxattr | |
460 | implementations like generic_listxattr. | |
6c6ef9f2 | 461 | |
ee5dc049 TH |
462 | ``get`` |
463 | Called by the VFS to get the value of a particular extended | |
464 | attribute. This method is called by the getxattr(2) system | |
465 | call. | |
6c6ef9f2 | 466 | |
ee5dc049 TH |
467 | ``set`` |
468 | Called by the VFS to set the value of a particular extended | |
469 | attribute. When the new value is NULL, called to remove a | |
8286de7c | 470 | particular extended attribute. This method is called by the |
ee5dc049 | 471 | setxattr(2) and removexattr(2) system calls. |
6c6ef9f2 | 472 | |
90caa781 TH |
473 | When none of the xattr handlers of a filesystem match the specified |
474 | attribute name or when a filesystem doesn't support extended attributes, | |
af96c1e3 | 475 | the various ``*xattr(2)`` system calls return -EOPNOTSUPP. |
6c6ef9f2 | 476 | |
1da177e4 | 477 | |
cc7d1f8f PE |
478 | The Inode Object |
479 | ================ | |
480 | ||
481 | An inode object represents an object within the filesystem. | |
482 | ||
483 | ||
5ea626aa | 484 | struct inode_operations |
cc7d1f8f | 485 | ----------------------- |
1da177e4 | 486 | |
90caa781 TH |
487 | This describes how the VFS can manipulate an inode in your filesystem. |
488 | As of kernel 2.6.22, the following members are defined: | |
1da177e4 | 489 | |
af96c1e3 TH |
490 | .. code-block:: c |
491 | ||
492 | struct inode_operations { | |
6c960e68 | 493 | int (*create) (struct mnt_idmap *, struct inode *,struct dentry *, umode_t, bool); |
af96c1e3 TH |
494 | struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int); |
495 | int (*link) (struct dentry *,struct inode *,struct dentry *); | |
496 | int (*unlink) (struct inode *,struct dentry *); | |
7a77db95 | 497 | int (*symlink) (struct mnt_idmap *, struct inode *,struct dentry *,const char *); |
c54bd91e | 498 | int (*mkdir) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t); |
af96c1e3 | 499 | int (*rmdir) (struct inode *,struct dentry *); |
5ebb29be | 500 | int (*mknod) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t,dev_t); |
e18275ae | 501 | int (*rename) (struct mnt_idmap *, struct inode *, struct dentry *, |
af96c1e3 TH |
502 | struct inode *, struct dentry *, unsigned int); |
503 | int (*readlink) (struct dentry *, char __user *,int); | |
504 | const char *(*get_link) (struct dentry *, struct inode *, | |
505 | struct delayed_call *); | |
4609e1f1 | 506 | int (*permission) (struct mnt_idmap *, struct inode *, int); |
cac2f8b8 | 507 | struct posix_acl * (*get_inode_acl)(struct inode *, int, bool); |
c1632a0f | 508 | int (*setattr) (struct mnt_idmap *, struct dentry *, struct iattr *); |
b74d24f7 | 509 | int (*getattr) (struct mnt_idmap *, const struct path *, struct kstat *, u32, unsigned int); |
af96c1e3 TH |
510 | ssize_t (*listxattr) (struct dentry *, char *, size_t); |
511 | void (*update_time)(struct inode *, struct timespec *, int); | |
512 | int (*atomic_open)(struct inode *, struct dentry *, struct file *, | |
513 | unsigned open_flag, umode_t create_mode); | |
011e2b71 | 514 | int (*tmpfile) (struct mnt_idmap *, struct inode *, struct file *, umode_t); |
77435322 | 515 | struct posix_acl * (*get_acl)(struct mnt_idmap *, struct dentry *, int); |
13e83a49 | 516 | int (*set_acl)(struct mnt_idmap *, struct dentry *, struct posix_acl *, int); |
8782a9ae | 517 | int (*fileattr_set)(struct mnt_idmap *idmap, |
4c5b4799 MS |
518 | struct dentry *dentry, struct fileattr *fa); |
519 | int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa); | |
6faddda6 | 520 | struct offset_ctx *(*get_offset_ctx)(struct inode *inode); |
af96c1e3 | 521 | }; |
1da177e4 LT |
522 | |
523 | Again, all methods are called without any locks being held, unless | |
524 | otherwise noted. | |
525 | ||
ee5dc049 TH |
526 | ``create`` |
527 | called by the open(2) and creat(2) system calls. Only required | |
528 | if you want to support regular files. The dentry you get should | |
529 | not have an inode (i.e. it should be a negative dentry). Here | |
530 | you will probably call d_instantiate() with the dentry and the | |
531 | newly created inode | |
1da177e4 | 532 | |
ee5dc049 TH |
533 | ``lookup`` |
534 | called when the VFS needs to look up an inode in a parent | |
4ee33ea4 | 535 | directory. The name to look for is found in the dentry. This |
1da177e4 | 536 | method must call d_add() to insert the found inode into the |
4ee33ea4 TH |
537 | dentry. The "i_count" field in the inode structure should be |
538 | incremented. If the named inode does not exist a NULL inode | |
1da177e4 | 539 | should be inserted into the dentry (this is called a negative |
ee5dc049 TH |
540 | dentry). Returning an error code from this routine must only be |
541 | done on a real error, otherwise creating inodes with system | |
1da177e4 LT |
542 | calls like create(2), mknod(2), mkdir(2) and so on will fail. |
543 | If you wish to overload the dentry methods then you should | |
ee5dc049 TH |
544 | initialise the "d_dop" field in the dentry; this is a pointer to |
545 | a struct "dentry_operations". This method is called with the | |
546 | directory inode semaphore held | |
1da177e4 | 547 | |
ee5dc049 TH |
548 | ``link`` |
549 | called by the link(2) system call. Only required if you want to | |
550 | support hard links. You will probably need to call | |
1da177e4 LT |
551 | d_instantiate() just as you would in the create() method |
552 | ||
ee5dc049 TH |
553 | ``unlink`` |
554 | called by the unlink(2) system call. Only required if you want | |
555 | to support deleting inodes | |
1da177e4 | 556 | |
ee5dc049 TH |
557 | ``symlink`` |
558 | called by the symlink(2) system call. Only required if you want | |
559 | to support symlinks. You will probably need to call | |
1da177e4 LT |
560 | d_instantiate() just as you would in the create() method |
561 | ||
ee5dc049 TH |
562 | ``mkdir`` |
563 | called by the mkdir(2) system call. Only required if you want | |
4ee33ea4 | 564 | to support creating subdirectories. You will probably need to |
1da177e4 LT |
565 | call d_instantiate() just as you would in the create() method |
566 | ||
ee5dc049 TH |
567 | ``rmdir`` |
568 | called by the rmdir(2) system call. Only required if you want | |
1da177e4 LT |
569 | to support deleting subdirectories |
570 | ||
ee5dc049 TH |
571 | ``mknod`` |
572 | called by the mknod(2) system call to create a device (char, | |
573 | block) inode or a named pipe (FIFO) or socket. Only required if | |
574 | you want to support creating these types of inodes. You will | |
575 | probably need to call d_instantiate() just as you would in the | |
576 | create() method | |
1da177e4 | 577 | |
ee5dc049 TH |
578 | ``rename`` |
579 | called by the rename(2) system call to rename the object to have | |
580 | the parent and name given by the second inode and dentry. | |
cc7d1f8f | 581 | |
18fc84da | 582 | The filesystem must return -EINVAL for any unsupported or |
ee5dc049 TH |
583 | unknown flags. Currently the following flags are implemented: |
584 | (1) RENAME_NOREPLACE: this flag indicates that if the target of | |
585 | the rename exists the rename should fail with -EEXIST instead of | |
586 | replacing the target. The VFS already checks for existence, so | |
587 | for local filesystems the RENAME_NOREPLACE implementation is | |
588 | equivalent to plain rename. | |
520c8b16 | 589 | (2) RENAME_EXCHANGE: exchange source and target. Both must |
ee5dc049 TH |
590 | exist; this is checked by the VFS. Unlike plain rename, source |
591 | and target may be of different type. | |
592 | ||
593 | ``get_link`` | |
594 | called by the VFS to follow a symbolic link to the inode it | |
595 | points to. Only required if you want to support symbolic links. | |
596 | This method returns the symlink body to traverse (and possibly | |
597 | resets the current position with nd_jump_link()). If the body | |
598 | won't go away until the inode is gone, nothing else is needed; | |
599 | if it needs to be otherwise pinned, arrange for its release by | |
600 | having get_link(..., ..., done) do set_delayed_call(done, | |
601 | destructor, argument). In that case destructor(argument) will | |
602 | be called once VFS is done with the body you've returned. May | |
603 | be called in RCU mode; that is indicated by NULL dentry | |
fceef393 AV |
604 | argument. If request can't be handled without leaving RCU mode, |
605 | have it return ERR_PTR(-ECHILD). | |
cc7d1f8f | 606 | |
dcb2cb1f EB |
607 | If the filesystem stores the symlink target in ->i_link, the |
608 | VFS may use it directly without calling ->get_link(); however, | |
609 | ->get_link() must still be provided. ->i_link must not be | |
610 | freed until after an RCU grace period. Writing to ->i_link | |
611 | post-iget() time requires a 'release' memory barrier. | |
612 | ||
ee5dc049 TH |
613 | ``readlink`` |
614 | this is now just an override for use by readlink(2) for the | |
76fca90e MS |
615 | cases when ->get_link uses nd_jump_link() or object is not in |
616 | fact a symlink. Normally filesystems should only implement | |
617 | ->get_link for symlinks and readlink(2) will automatically use | |
618 | that. | |
619 | ||
ee5dc049 TH |
620 | ``permission`` |
621 | called by the VFS to check for access rights on a POSIX-like | |
50c1f43a | 622 | filesystem. |
5ea626aa | 623 | |
ee5dc049 TH |
624 | May be called in rcu-walk mode (mask & MAY_NOT_BLOCK). If in |
625 | rcu-walk mode, the filesystem must check the permission without | |
626 | blocking or storing to the inode. | |
b74c79e9 | 627 | |
ee5dc049 TH |
628 | If a situation is encountered that rcu-walk cannot handle, |
629 | return | |
b74c79e9 NP |
630 | -ECHILD and it will be called again in ref-walk mode. |
631 | ||
ee5dc049 TH |
632 | ``setattr`` |
633 | called by the VFS to set attributes for a file. This method is | |
634 | called by chmod(2) and related system calls. | |
635 | ||
636 | ``getattr`` | |
637 | called by the VFS to get attributes of a file. This method is | |
638 | called by stat(2) and related system calls. | |
639 | ||
640 | ``listxattr`` | |
641 | called by the VFS to list all extended attributes for a given | |
642 | file. This method is called by the listxattr(2) system call. | |
643 | ||
644 | ``update_time`` | |
645 | called by the VFS to update a specific time or the i_version of | |
646 | an inode. If this is not defined the VFS will update the inode | |
647 | itself and call mark_inode_dirty_sync. | |
648 | ||
649 | ``atomic_open`` | |
650 | called on the last component of an open. Using this optional | |
651 | method the filesystem can look up, possibly create and open the | |
652 | file in one atomic operation. If it wants to leave actual | |
653 | opening to the caller (e.g. if the file turned out to be a | |
654 | symlink, device, or just something filesystem won't do atomic | |
655 | open for), it may signal this by returning finish_no_open(file, | |
656 | dentry). This method is only called if the last component is | |
657 | negative or needs lookup. Cached positive dentries are still | |
658 | handled by f_op->open(). If the file was created, FMODE_CREATED | |
659 | flag should be set in file->f_mode. In case of O_EXCL the | |
660 | method must only succeed if the file didn't exist and hence | |
661 | FMODE_CREATED shall always be set on success. | |
662 | ||
663 | ``tmpfile`` | |
664 | called in the end of O_TMPFILE open(). Optional, equivalent to | |
665 | atomically creating, opening and unlinking a file in given | |
863f144f MS |
666 | directory. On success needs to return with the file already |
667 | open; this can be done by calling finish_open_simple() right at | |
668 | the end. | |
48bde8d3 | 669 | |
4c5b4799 MS |
670 | ``fileattr_get`` |
671 | called on ioctl(FS_IOC_GETFLAGS) and ioctl(FS_IOC_FSGETXATTR) to | |
672 | retrieve miscellaneous file flags and attributes. Also called | |
673 | before the relevant SET operation to check what is being changed | |
674 | (in this case with i_rwsem locked exclusive). If unset, then | |
675 | fall back to f_op->ioctl(). | |
676 | ||
677 | ``fileattr_set`` | |
678 | called on ioctl(FS_IOC_SETFLAGS) and ioctl(FS_IOC_FSSETXATTR) to | |
679 | change miscellaneous file flags and attributes. Callers hold | |
680 | i_rwsem exclusive. If unset, then fall back to f_op->ioctl(). | |
6faddda6 CL |
681 | ``get_offset_ctx`` |
682 | called to get the offset context for a directory inode. A | |
683 | filesystem must define this operation to use | |
684 | simple_offset_dir_operations. | |
e04c83cd | 685 | |
cc7d1f8f PE |
686 | The Address Space Object |
687 | ======================== | |
688 | ||
341546f5 | 689 | The address space object is used to group and manage pages in the page |
90caa781 TH |
690 | cache. It can be used to keep track of the pages in a file (or anything |
691 | else) and also track the mapping of sections of the file into process | |
692 | address spaces. | |
341546f5 N |
693 | |
694 | There are a number of distinct yet related services that an | |
90caa781 TH |
695 | address-space can provide. These include communicating memory pressure, |
696 | page lookup by address, and keeping track of pages tagged as Dirty or | |
697 | Writeback. | |
341546f5 | 698 | |
a9e102b6 | 699 | The first can be used independently to the others. The VM can try to |
90caa781 TH |
700 | either write dirty pages in order to clean them, or release clean pages |
701 | in order to reuse them. To do this it can call the ->writepage method | |
fa29000b MWO |
702 | on dirty pages, and ->release_folio on clean folios with the private |
703 | flag set. Clean pages without PagePrivate and with no external references | |
704 | will be released without notice being given to the address_space. | |
341546f5 | 705 | |
a9e102b6 | 706 | To achieve this functionality, pages need to be placed on an LRU with |
90caa781 TH |
707 | lru_cache_add and mark_page_active needs to be called whenever the page |
708 | is used. | |
341546f5 | 709 | |
4ee33ea4 | 710 | Pages are normally kept in a radix tree index by ->index. This tree |
90caa781 TH |
711 | maintains information about the PG_Dirty and PG_Writeback status of each |
712 | page, so that pages with either of these flags can be found quickly. | |
341546f5 N |
713 | |
714 | The Dirty tag is primarily used by mpage_writepages - the default | |
715 | ->writepages method. It uses the tag to find dirty pages to call | |
716 | ->writepage on. If mpage_writepages is not used (i.e. the address | |
90caa781 TH |
717 | provides its own ->writepages) , the PAGECACHE_TAG_DIRTY tag is almost |
718 | unused. write_inode_now and sync_inode do use it (through | |
341546f5 N |
719 | __sync_single_inode) to check if ->writepages has been successful in |
720 | writing out the whole address_space. | |
721 | ||
90caa781 TH |
722 | The Writeback tag is used by filemap*wait* and sync_page* functions, via |
723 | filemap_fdatawait_range, to wait for all writeback to complete. | |
341546f5 N |
724 | |
725 | An address_space handler may attach extra information to a page, | |
726 | typically using the 'private' field in the 'struct page'. If such | |
727 | information is attached, the PG_Private flag should be set. This will | |
a9e102b6 | 728 | cause various VM routines to make extra calls into the address_space |
341546f5 N |
729 | handler to deal with that data. |
730 | ||
731 | An address space acts as an intermediate between storage and | |
732 | application. Data is read into the address space a whole page at a | |
90caa781 TH |
733 | time, and provided to the application either by copying of the page, or |
734 | by memory-mapping the page. Data is written into the address space by | |
735 | the application, and then written-back to storage typically in whole | |
736 | pages, however the address_space has finer control of write sizes. | |
341546f5 | 737 | |
08830c8b | 738 | The read process essentially only requires 'read_folio'. The write |
4e02ed4b | 739 | process is more complicated and uses write_begin/write_end or |
6f31a5a2 | 740 | dirty_folio to write data into the address_space, and writepage and |
90caa781 | 741 | writepages to writeback data to storage. |
341546f5 N |
742 | |
743 | Adding and removing pages to/from an address_space is protected by the | |
744 | inode's i_mutex. | |
745 | ||
746 | When data is written to a page, the PG_Dirty flag should be set. It | |
747 | typically remains set until writepage asks for it to be written. This | |
90caa781 TH |
748 | should clear PG_Dirty and set PG_Writeback. It can be actually written |
749 | at any point after PG_Dirty is clear. Once it is known to be safe, | |
750 | PG_Writeback is cleared. | |
341546f5 | 751 | |
acbf3c34 | 752 | Writeback makes use of a writeback_control structure to direct the |
8286de7c | 753 | operations. This gives the writepage and writepages operations some |
acbf3c34 JL |
754 | information about the nature of and reason for the writeback request, |
755 | and the constraints under which it is being done. It is also used to | |
756 | return information back to the caller about the result of a writepage or | |
757 | writepages request. | |
758 | ||
e04c83cd | 759 | |
acbf3c34 JL |
760 | Handling errors during writeback |
761 | -------------------------------- | |
e04c83cd | 762 | |
acbf3c34 JL |
763 | Most applications that do buffered I/O will periodically call a file |
764 | synchronization call (fsync, fdatasync, msync or sync_file_range) to | |
765 | ensure that data written has made it to the backing store. When there | |
766 | is an error during writeback, they expect that error to be reported when | |
767 | a file sync request is made. After an error has been reported on one | |
768 | request, subsequent requests on the same file descriptor should return | |
769 | 0, unless further writeback errors have occurred since the previous file | |
d56b699d | 770 | synchronization. |
acbf3c34 JL |
771 | |
772 | Ideally, the kernel would report errors only on file descriptions on | |
773 | which writes were done that subsequently failed to be written back. The | |
774 | generic pagecache infrastructure does not track the file descriptions | |
775 | that have dirtied each individual page however, so determining which | |
776 | file descriptors should get back an error is not possible. | |
777 | ||
778 | Instead, the generic writeback error tracking infrastructure in the | |
779 | kernel settles for reporting errors to fsync on all file descriptions | |
780 | that were open at the time that the error occurred. In a situation with | |
90caa781 TH |
781 | multiple writers, all of them will get back an error on a subsequent |
782 | fsync, even if all of the writes done through that particular file | |
783 | descriptor succeeded (or even if there were no writes on that file | |
784 | descriptor at all). | |
acbf3c34 JL |
785 | |
786 | Filesystems that wish to use this infrastructure should call | |
787 | mapping_set_error to record the error in the address_space when it | |
788 | occurs. Then, after writing back data from the pagecache in their | |
789 | file->fsync operation, they should call file_check_and_advance_wb_err to | |
790 | ensure that the struct file's error cursor has advanced to the correct | |
791 | point in the stream of errors emitted by the backing device(s). | |
5ea626aa | 792 | |
e04c83cd | 793 | |
5ea626aa | 794 | struct address_space_operations |
cc7d1f8f | 795 | ------------------------------- |
5ea626aa | 796 | |
90caa781 TH |
797 | This describes how the VFS can manipulate mapping of a file to page |
798 | cache in your filesystem. The following members are defined: | |
5ea626aa | 799 | |
af96c1e3 TH |
800 | .. code-block:: c |
801 | ||
802 | struct address_space_operations { | |
803 | int (*writepage)(struct page *page, struct writeback_control *wbc); | |
08830c8b | 804 | int (*read_folio)(struct file *, struct folio *); |
af96c1e3 | 805 | int (*writepages)(struct address_space *, struct writeback_control *); |
6f31a5a2 | 806 | bool (*dirty_folio)(struct address_space *, struct folio *); |
8151b4c8 | 807 | void (*readahead)(struct readahead_control *); |
af96c1e3 | 808 | int (*write_begin)(struct file *, struct address_space *mapping, |
9d6b0cd7 | 809 | loff_t pos, unsigned len, |
afddba49 | 810 | struct page **pagep, void **fsdata); |
af96c1e3 TH |
811 | int (*write_end)(struct file *, struct address_space *mapping, |
812 | loff_t pos, unsigned len, unsigned copied, | |
813 | struct page *page, void *fsdata); | |
814 | sector_t (*bmap)(struct address_space *, sector_t); | |
128d1f82 | 815 | void (*invalidate_folio) (struct folio *, size_t start, size_t len); |
fa29000b | 816 | bool (*release_folio)(struct folio *, gfp_t); |
d2329aa0 | 817 | void (*free_folio)(struct folio *); |
af96c1e3 | 818 | ssize_t (*direct_IO)(struct kiocb *, struct iov_iter *iter); |
5490da4f MWO |
819 | int (*migrate_folio)(struct mapping *, struct folio *dst, |
820 | struct folio *src, enum migrate_mode); | |
affa80e8 | 821 | int (*launder_folio) (struct folio *); |
af96c1e3 | 822 | |
2e7e80f7 MWO |
823 | bool (*is_partially_uptodate) (struct folio *, size_t from, |
824 | size_t count); | |
520f301c | 825 | void (*is_dirty_writeback)(struct folio *, bool *, bool *); |
af7628d6 | 826 | int (*error_remove_folio)(struct mapping *mapping, struct folio *); |
cba738f6 | 827 | int (*swap_activate)(struct swap_info_struct *sis, struct file *f, sector_t *span) |
af96c1e3 | 828 | int (*swap_deactivate)(struct file *); |
cba738f6 | 829 | int (*swap_rw)(struct kiocb *iocb, struct iov_iter *iter); |
af96c1e3 TH |
830 | }; |
831 | ||
ee5dc049 TH |
832 | ``writepage`` |
833 | called by the VM to write a dirty page to backing store. This | |
834 | may happen for data integrity reasons (i.e. 'sync'), or to free | |
835 | up memory (flush). The difference can be seen in | |
836 | wbc->sync_mode. The PG_Dirty flag has been cleared and | |
837 | PageLocked is true. writepage should start writeout, should set | |
838 | PG_Writeback, and should make sure the page is unlocked, either | |
839 | synchronously or asynchronously when the write operation | |
840 | completes. | |
841 | ||
842 | If wbc->sync_mode is WB_SYNC_NONE, ->writepage doesn't have to | |
843 | try too hard if there are problems, and may choose to write out | |
844 | other pages from the mapping if that is easier (e.g. due to | |
845 | internal dependencies). If it chooses not to start writeout, it | |
846 | should return AOP_WRITEPAGE_ACTIVATE so that the VM will not | |
847 | keep calling ->writepage on that page. | |
848 | ||
849 | See the file "Locking" for more details. | |
850 | ||
08830c8b | 851 | ``read_folio`` |
90c02eb9 MWO |
852 | Called by the page cache to read a folio from the backing store. |
853 | The 'file' argument supplies authentication information to network | |
854 | filesystems, and is generally not used by block based filesystems. | |
855 | It may be NULL if the caller does not have an open file (eg if | |
856 | the kernel is performing a read for itself rather than on behalf | |
857 | of a userspace process with an open file). | |
858 | ||
859 | If the mapping does not support large folios, the folio will | |
860 | contain a single page. The folio will be locked when read_folio | |
861 | is called. If the read completes successfully, the folio should | |
862 | be marked uptodate. The filesystem should unlock the folio | |
863 | once the read has completed, whether it was successful or not. | |
864 | The filesystem does not need to modify the refcount on the folio; | |
865 | the page cache holds a reference count and that will not be | |
866 | released until the folio is unlocked. | |
867 | ||
868 | Filesystems may implement ->read_folio() synchronously. | |
869 | In normal operation, folios are read through the ->readahead() | |
870 | method. Only if this fails, or if the caller needs to wait for | |
871 | the read to complete will the page cache call ->read_folio(). | |
872 | Filesystems should not attempt to perform their own readahead | |
873 | in the ->read_folio() operation. | |
874 | ||
875 | If the filesystem cannot perform the read at this time, it can | |
876 | unlock the folio, do whatever action it needs to ensure that the | |
877 | read will succeed in the future and return AOP_TRUNCATED_PAGE. | |
878 | In this case, the caller should look up the folio, lock it, | |
879 | and call ->read_folio again. | |
880 | ||
881 | Callers may invoke the ->read_folio() method directly, but using | |
882 | read_mapping_folio() will take care of locking, waiting for the | |
883 | read to complete and handle cases such as AOP_TRUNCATED_PAGE. | |
ee5dc049 TH |
884 | |
885 | ``writepages`` | |
886 | called by the VM to write out pages associated with the | |
e9b2f15b | 887 | address_space object. If wbc->sync_mode is WB_SYNC_ALL, then |
50c1f43a | 888 | the writeback_control will specify a range of pages that must be |
e9b2f15b | 889 | written out. If it is WB_SYNC_NONE, then a nr_to_write is |
ee5dc049 TH |
890 | given and that many pages should be written if possible. If no |
891 | ->writepages is given, then mpage_writepages is used instead. | |
892 | This will choose pages from the address space that are tagged as | |
893 | DIRTY and will pass them to ->writepage. | |
894 | ||
6f31a5a2 MWO |
895 | ``dirty_folio`` |
896 | called by the VM to mark a folio as dirty. This is particularly | |
897 | needed if an address space attaches private data to a folio, and | |
898 | that data needs to be updated when a folio is dirtied. This is | |
ee5dc049 | 899 | called, for example, when a memory mapped page gets modified. |
6f31a5a2 MWO |
900 | If defined, it should set the folio dirty flag, and the |
901 | PAGECACHE_TAG_DIRTY search mark in i_pages. | |
5ea626aa | 902 | |
8151b4c8 MWO |
903 | ``readahead`` |
904 | Called by the VM to read pages associated with the address_space | |
905 | object. The pages are consecutive in the page cache and are | |
906 | locked. The implementation should decrement the page refcount | |
907 | after starting I/O on each page. Usually the page will be | |
84dacdbd N |
908 | unlocked by the I/O completion handler. The set of pages are |
909 | divided into some sync pages followed by some async pages, | |
910 | rac->ra->async_size gives the number of async pages. The | |
911 | filesystem should attempt to read all sync pages but may decide | |
912 | to stop once it reaches the async pages. If it does decide to | |
913 | stop attempting I/O, it can simply return. The caller will | |
914 | remove the remaining pages from the address space, unlock them | |
915 | and decrement the page refcount. Set PageUptodate if the I/O | |
916 | completes successfully. Setting PageError on any page will be | |
917 | ignored; simply unlock the page if an I/O error occurs. | |
8151b4c8 | 918 | |
ee5dc049 TH |
919 | ``write_begin`` |
920 | Called by the generic buffered write code to ask the filesystem | |
921 | to prepare to write len bytes at the given offset in the file. | |
922 | The address_space should check that the write will be able to | |
923 | complete, by allocating space if necessary and doing any other | |
924 | internal housekeeping. If the write will update parts of any | |
925 | basic-blocks on storage, then those blocks should be pre-read | |
926 | (if they haven't been read already) so that the updated blocks | |
927 | can be written out properly. | |
afddba49 | 928 | |
ee5dc049 TH |
929 | The filesystem must return the locked pagecache page for the |
930 | specified offset, in ``*pagep``, for the caller to write into. | |
afddba49 | 931 | |
ee5dc049 TH |
932 | It must be able to cope with short writes (where the length |
933 | passed to write_begin is greater than the number of bytes copied | |
934 | into the page). | |
4e02ed4b | 935 | |
1b44ae63 TH |
936 | A void * may be returned in fsdata, which then gets passed into |
937 | write_end. | |
afddba49 | 938 | |
ee5dc049 TH |
939 | Returns 0 on success; < 0 on failure (which is the error code), |
940 | in which case write_end is not called. | |
941 | ||
942 | ``write_end`` | |
943 | After a successful write_begin, and data copy, write_end must be | |
944 | called. len is the original len passed to write_begin, and | |
945 | copied is the amount that was able to be copied. | |
946 | ||
947 | The filesystem must take care of unlocking the page and | |
948 | releasing it refcount, and updating i_size. | |
949 | ||
950 | Returns < 0 on failure, otherwise the number of bytes (<= | |
951 | 'copied') that were able to be copied into pagecache. | |
952 | ||
953 | ``bmap`` | |
954 | called by the VFS to map a logical block offset within object to | |
955 | physical block number. This method is used by the FIBMAP ioctl | |
956 | and for working with swap-files. To be able to swap to a file, | |
957 | the file must have a stable mapping to a block device. The swap | |
958 | system does not go through the filesystem but instead uses bmap | |
959 | to find out where the blocks in the file are and uses those | |
960 | addresses directly. | |
961 | ||
128d1f82 MWO |
962 | ``invalidate_folio`` |
963 | If a folio has private data, then invalidate_folio will be | |
964 | called when part or all of the folio is to be removed from the | |
ee5dc049 TH |
965 | address space. This generally corresponds to either a |
966 | truncation, punch hole or a complete invalidation of the address | |
d47992f8 | 967 | space (in the latter case 'offset' will always be 0 and 'length' |
fa29000b | 968 | will be folio_size()). Any private data associated with the folio |
ee5dc049 | 969 | should be updated to reflect this truncation. If offset is 0 |
128d1f82 | 970 | and length is folio_size(), then the private data should be |
fa29000b MWO |
971 | released, because the folio must be able to be completely |
972 | discarded. This may be done by calling the ->release_folio | |
ee5dc049 TH |
973 | function, but in this case the release MUST succeed. |
974 | ||
fa29000b MWO |
975 | ``release_folio`` |
976 | release_folio is called on folios with private data to tell the | |
977 | filesystem that the folio is about to be freed. ->release_folio | |
978 | should remove any private data from the folio and clear the | |
979 | private flag. If release_folio() fails, it should return false. | |
980 | release_folio() is used in two distinct though related cases. | |
981 | The first is when the VM wants to free a clean folio with no | |
982 | active users. If ->release_folio succeeds, the folio will be | |
983 | removed from the address_space and be freed. | |
341546f5 | 984 | |
bc5b1d55 | 985 | The second case is when a request has been made to invalidate |
fa29000b MWO |
986 | some or all folios in an address_space. This can happen |
987 | through the fadvise(POSIX_FADV_DONTNEED) system call or by the | |
988 | filesystem explicitly requesting it as nfs and 9p do (when they | |
ee5dc049 TH |
989 | believe the cache may be out of date with storage) by calling |
990 | invalidate_inode_pages2(). If the filesystem makes such a call, | |
fa29000b MWO |
991 | and needs to be certain that all folios are invalidated, then |
992 | its release_folio will need to ensure this. Possibly it can | |
993 | clear the uptodate flag if it cannot free private data yet. | |
ee5dc049 | 994 | |
d2329aa0 MWO |
995 | ``free_folio`` |
996 | free_folio is called once the folio is no longer visible in the | |
ee5dc049 TH |
997 | page cache in order to allow the cleanup of any private data. |
998 | Since it may be called by the memory reclaimer, it should not | |
999 | assume that the original address_space mapping still exists, and | |
1000 | it should not block. | |
1001 | ||
1002 | ``direct_IO`` | |
1003 | called by the generic read/write routines to perform direct_IO - | |
1004 | that is IO requests which bypass the page cache and transfer | |
1005 | data directly between the storage and the application's address | |
1006 | space. | |
1007 | ||
5490da4f | 1008 | ``migrate_folio`` |
ee5dc049 | 1009 | This is used to compact the physical memory usage. If the VM |
5490da4f MWO |
1010 | wants to relocate a folio (maybe from a memory device that is |
1011 | signalling imminent failure) it will pass a new folio and an old | |
1012 | folio to this function. migrate_folio should transfer any private | |
1013 | data across and update any references that it has to the folio. | |
ee5dc049 | 1014 | |
affa80e8 MWO |
1015 | ``launder_folio`` |
1016 | Called before freeing a folio - it writes back the dirty folio. | |
1017 | To prevent redirtying the folio, it is kept locked during the | |
ee5dc049 TH |
1018 | whole operation. |
1019 | ||
1020 | ``is_partially_uptodate`` | |
1021 | Called by the VM when reading a file through the pagecache when | |
2e7e80f7 MWO |
1022 | the underlying blocksize is smaller than the size of the folio. |
1023 | If the required block is up to date then the read can complete | |
1024 | without needing I/O to bring the whole page up to date. | |
ee5dc049 TH |
1025 | |
1026 | ``is_dirty_writeback`` | |
520f301c | 1027 | Called by the VM when attempting to reclaim a folio. The VM uses |
ee5dc049 TH |
1028 | dirty and writeback information to determine if it needs to |
1029 | stall to allow flushers a chance to complete some IO. | |
520f301c MWO |
1030 | Ordinarily it can use folio_test_dirty and folio_test_writeback but |
1031 | some filesystems have more complex state (unstable folios in NFS | |
ee5dc049 TH |
1032 | prevent reclaim) or do not set those flags due to locking |
1033 | problems. This callback allows a filesystem to indicate to the | |
520f301c | 1034 | VM if a folio should be treated as dirty or writeback for the |
ee5dc049 TH |
1035 | purposes of stalling. |
1036 | ||
af7628d6 MWO |
1037 | ``error_remove_folio`` |
1038 | normally set to generic_error_remove_folio if truncation is ok | |
ee5dc049 | 1039 | for this address space. Used for memory failure handling. |
25718736 AK |
1040 | Setting this implies you deal with pages going away under you, |
1041 | unless you have them locked or reference counts increased. | |
1042 | ||
ee5dc049 | 1043 | ``swap_activate`` |
cba738f6 N |
1044 | |
1045 | Called to prepare the given file for swap. It should perform | |
1046 | any validation and preparation necessary to ensure that writes | |
1047 | can be performed with minimal memory allocation. It should call | |
1048 | add_swap_extent(), or the helper iomap_swapfile_activate(), and | |
1049 | return the number of extents added. If IO should be submitted | |
1050 | through ->swap_rw(), it should set SWP_FS_OPS, otherwise IO will | |
1051 | be submitted directly to the block device ``sis->bdev``. | |
62c230bc | 1052 | |
ee5dc049 TH |
1053 | ``swap_deactivate`` |
1054 | Called during swapoff on files where swap_activate was | |
1055 | successful. | |
62c230bc | 1056 | |
cba738f6 N |
1057 | ``swap_rw`` |
1058 | Called to read or write swap pages when SWP_FS_OPS is set. | |
25718736 | 1059 | |
cc7d1f8f PE |
1060 | The File Object |
1061 | =============== | |
1062 | ||
4ee33ea4 | 1063 | A file object represents a file opened by a process. This is also known |
acbf3c34 | 1064 | as an "open file description" in POSIX parlance. |
cc7d1f8f PE |
1065 | |
1066 | ||
5ea626aa | 1067 | struct file_operations |
cc7d1f8f | 1068 | ---------------------- |
1da177e4 | 1069 | |
4ee33ea4 | 1070 | This describes how the VFS can manipulate an open file. As of kernel |
17ef445f | 1071 | 4.18, the following members are defined: |
1da177e4 | 1072 | |
af96c1e3 TH |
1073 | .. code-block:: c |
1074 | ||
1075 | struct file_operations { | |
1076 | struct module *owner; | |
1077 | loff_t (*llseek) (struct file *, loff_t, int); | |
1078 | ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); | |
1079 | ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); | |
1080 | ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); | |
1081 | ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); | |
1082 | int (*iopoll)(struct kiocb *kiocb, bool spin); | |
af96c1e3 TH |
1083 | int (*iterate_shared) (struct file *, struct dir_context *); |
1084 | __poll_t (*poll) (struct file *, struct poll_table_struct *); | |
1085 | long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); | |
1086 | long (*compat_ioctl) (struct file *, unsigned int, unsigned long); | |
1087 | int (*mmap) (struct file *, struct vm_area_struct *); | |
1088 | int (*open) (struct inode *, struct file *); | |
1089 | int (*flush) (struct file *, fl_owner_t id); | |
1090 | int (*release) (struct inode *, struct file *); | |
1091 | int (*fsync) (struct file *, loff_t, loff_t, int datasync); | |
1092 | int (*fasync) (int, struct file *, int); | |
1093 | int (*lock) (struct file *, int, struct file_lock *); | |
af96c1e3 TH |
1094 | unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned long, unsigned long, unsigned long); |
1095 | int (*check_flags)(int); | |
1096 | int (*flock) (struct file *, int, struct file_lock *); | |
1097 | ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *, size_t, unsigned int); | |
1098 | ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *, size_t, unsigned int); | |
1099 | int (*setlease)(struct file *, long, struct file_lock **, void **); | |
1100 | long (*fallocate)(struct file *file, int mode, loff_t offset, | |
1101 | loff_t len); | |
1102 | void (*show_fdinfo)(struct seq_file *m, struct file *f); | |
1103 | #ifndef CONFIG_MMU | |
1104 | unsigned (*mmap_capabilities)(struct file *); | |
1105 | #endif | |
1106 | ssize_t (*copy_file_range)(struct file *, loff_t, struct file *, loff_t, size_t, unsigned int); | |
1107 | loff_t (*remap_file_range)(struct file *file_in, loff_t pos_in, | |
1108 | struct file *file_out, loff_t pos_out, | |
1109 | loff_t len, unsigned int remap_flags); | |
1110 | int (*fadvise)(struct file *, loff_t, loff_t, int); | |
1111 | }; | |
1da177e4 LT |
1112 | |
1113 | Again, all methods are called without any locks being held, unless | |
1114 | otherwise noted. | |
1115 | ||
ee5dc049 TH |
1116 | ``llseek`` |
1117 | called when the VFS needs to move the file position index | |
1da177e4 | 1118 | |
ee5dc049 TH |
1119 | ``read`` |
1120 | called by read(2) and related system calls | |
1da177e4 | 1121 | |
ee5dc049 TH |
1122 | ``read_iter`` |
1123 | possibly asynchronous read with iov_iter as destination | |
5ea626aa | 1124 | |
ee5dc049 TH |
1125 | ``write`` |
1126 | called by write(2) and related system calls | |
1da177e4 | 1127 | |
ee5dc049 TH |
1128 | ``write_iter`` |
1129 | possibly asynchronous write with iov_iter as source | |
5ea626aa | 1130 | |
ee5dc049 TH |
1131 | ``iopoll`` |
1132 | called when aio wants to poll for completions on HIPRI iocbs | |
fb7e1600 | 1133 | |
ee5dc049 | 1134 | ``iterate_shared`` |
99b319d3 | 1135 | called when the VFS needs to read the directory contents |
17ef445f | 1136 | |
ee5dc049 TH |
1137 | ``poll`` |
1138 | called by the VFS when a process wants to check if there is | |
1da177e4 | 1139 | activity on this file and (optionally) go to sleep until there |
4ee33ea4 | 1140 | is activity. Called by the select(2) and poll(2) system calls |
1da177e4 | 1141 | |
ee5dc049 TH |
1142 | ``unlocked_ioctl`` |
1143 | called by the ioctl(2) system call. | |
5ea626aa | 1144 | |
ee5dc049 TH |
1145 | ``compat_ioctl`` |
1146 | called by the ioctl(2) system call when 32 bit system calls are | |
1147 | used on 64 bit kernels. | |
5ea626aa | 1148 | |
ee5dc049 TH |
1149 | ``mmap`` |
1150 | called by the mmap(2) system call | |
1da177e4 | 1151 | |
ee5dc049 TH |
1152 | ``open`` |
1153 | called by the VFS when an inode should be opened. When the VFS | |
4ee33ea4 TH |
1154 | opens a file, it creates a new "struct file". It then calls the |
1155 | open method for the newly allocated file structure. You might | |
ee5dc049 TH |
1156 | think that the open method really belongs in "struct |
1157 | inode_operations", and you may be right. I think it's done the | |
1158 | way it is because it makes filesystems simpler to implement. | |
1159 | The open() method is a good place to initialize the | |
5ea626aa PE |
1160 | "private_data" member in the file structure if you want to point |
1161 | to a device structure | |
1162 | ||
ee5dc049 TH |
1163 | ``flush`` |
1164 | called by the close(2) system call to flush a file | |
1da177e4 | 1165 | |
ee5dc049 TH |
1166 | ``release`` |
1167 | called when the last reference to an open file is closed | |
1da177e4 | 1168 | |
ee5dc049 TH |
1169 | ``fsync`` |
1170 | called by the fsync(2) system call. Also see the section above | |
1171 | entitled "Handling errors during writeback". | |
1da177e4 | 1172 | |
ee5dc049 TH |
1173 | ``fasync`` |
1174 | called by the fcntl(2) system call when asynchronous | |
1da177e4 LT |
1175 | (non-blocking) mode is enabled for a file |
1176 | ||
ee5dc049 TH |
1177 | ``lock`` |
1178 | called by the fcntl(2) system call for F_GETLK, F_SETLK, and | |
1179 | F_SETLKW commands | |
5ea626aa | 1180 | |
ee5dc049 TH |
1181 | ``get_unmapped_area`` |
1182 | called by the mmap(2) system call | |
5ea626aa | 1183 | |
ee5dc049 TH |
1184 | ``check_flags`` |
1185 | called by the fcntl(2) system call for F_SETFL command | |
5ea626aa | 1186 | |
ee5dc049 TH |
1187 | ``flock`` |
1188 | called by the flock(2) system call | |
5ea626aa | 1189 | |
ee5dc049 TH |
1190 | ``splice_write`` |
1191 | called by the VFS to splice data from a pipe to a file. This | |
1192 | method is used by the splice(2) system call | |
d1195c51 | 1193 | |
ee5dc049 TH |
1194 | ``splice_read`` |
1195 | called by the VFS to splice data from file to a pipe. This | |
1196 | method is used by the splice(2) system call | |
d1195c51 | 1197 | |
ee5dc049 TH |
1198 | ``setlease`` |
1199 | called by the VFS to set or release a file lock lease. setlease | |
1200 | implementations should call generic_setlease to record or remove | |
1201 | the lease in the inode after setting it. | |
17cf28af | 1202 | |
ee5dc049 TH |
1203 | ``fallocate`` |
1204 | called by the VFS to preallocate blocks or punch a hole. | |
17cf28af | 1205 | |
ee5dc049 TH |
1206 | ``copy_file_range`` |
1207 | called by the copy_file_range(2) system call. | |
17ef445f | 1208 | |
ee5dc049 TH |
1209 | ``remap_file_range`` |
1210 | called by the ioctl(2) system call for FICLONERANGE and FICLONE | |
1211 | and FIDEDUPERANGE commands to remap file ranges. An | |
1212 | implementation should remap len bytes at pos_in of the source | |
1213 | file into the dest file at pos_out. Implementations must handle | |
1214 | callers passing in len == 0; this means "remap to the end of the | |
1215 | source file". The return value should the number of bytes | |
1216 | remapped, or the usual negative error code if errors occurred | |
1217 | before any bytes were remapped. The remap_flags parameter | |
1218 | accepts REMAP_FILE_* flags. If REMAP_FILE_DEDUP is set then the | |
1219 | implementation must only remap if the requested file ranges have | |
cb56ecae | 1220 | identical contents. If REMAP_FILE_CAN_SHORTEN is set, the caller is |
ee5dc049 TH |
1221 | ok with the implementation shortening the request length to |
1222 | satisfy alignment or EOF requirements (or any other reason). | |
17ef445f | 1223 | |
ee5dc049 TH |
1224 | ``fadvise`` |
1225 | possibly called by the fadvise64() system call. | |
45cd0faa | 1226 | |
1da177e4 | 1227 | Note that the file operations are implemented by the specific |
4ee33ea4 | 1228 | filesystem in which the inode resides. When opening a device node |
1da177e4 LT |
1229 | (character or block special) most filesystems will call special |
1230 | support routines in the VFS which will locate the required device | |
4ee33ea4 | 1231 | driver information. These support routines replace the filesystem file |
1da177e4 | 1232 | operations with those for the device driver, and then proceed to call |
4ee33ea4 | 1233 | the new open() method for the file. This is how opening a device file |
1da177e4 | 1234 | in the filesystem eventually ends up calling the device driver open() |
5ea626aa | 1235 | method. |
1da177e4 LT |
1236 | |
1237 | ||
5ea626aa PE |
1238 | Directory Entry Cache (dcache) |
1239 | ============================== | |
1240 | ||
1da177e4 LT |
1241 | |
1242 | struct dentry_operations | |
5ea626aa | 1243 | ------------------------ |
1da177e4 LT |
1244 | |
1245 | This describes how a filesystem can overload the standard dentry | |
4ee33ea4 TH |
1246 | operations. Dentries and the dcache are the domain of the VFS and the |
1247 | individual filesystem implementations. Device drivers have no business | |
1248 | here. These methods may be set to NULL, as they are either optional or | |
1249 | the VFS uses a default. As of kernel 2.6.22, the following members are | |
1da177e4 LT |
1250 | defined: |
1251 | ||
af96c1e3 TH |
1252 | .. code-block:: c |
1253 | ||
1254 | struct dentry_operations { | |
1255 | int (*d_revalidate)(struct dentry *, unsigned int); | |
1256 | int (*d_weak_revalidate)(struct dentry *, unsigned int); | |
1257 | int (*d_hash)(const struct dentry *, struct qstr *); | |
1258 | int (*d_compare)(const struct dentry *, | |
1259 | unsigned int, const char *, const struct qstr *); | |
1260 | int (*d_delete)(const struct dentry *); | |
1261 | int (*d_init)(struct dentry *); | |
1262 | void (*d_release)(struct dentry *); | |
1263 | void (*d_iput)(struct dentry *, struct inode *); | |
1264 | char *(*d_dname)(struct dentry *, char *, int); | |
1265 | struct vfsmount *(*d_automount)(struct path *); | |
1266 | int (*d_manage)(const struct path *, bool); | |
11b3f8ae | 1267 | struct dentry *(*d_real)(struct dentry *, enum d_real_type type); |
af96c1e3 TH |
1268 | }; |
1269 | ||
ee5dc049 TH |
1270 | ``d_revalidate`` |
1271 | called when the VFS needs to revalidate a dentry. This is | |
1272 | called whenever a name look-up finds a dentry in the dcache. | |
1273 | Most local filesystems leave this as NULL, because all their | |
1274 | dentries in the dcache are valid. Network filesystems are | |
1275 | different since things can change on the server without the | |
1276 | client necessarily being aware of it. | |
1277 | ||
1278 | This function should return a positive value if the dentry is | |
1279 | still valid, and zero or a negative error code if it isn't. | |
1280 | ||
1281 | d_revalidate may be called in rcu-walk mode (flags & | |
1282 | LOOKUP_RCU). If in rcu-walk mode, the filesystem must | |
1283 | revalidate the dentry without blocking or storing to the dentry, | |
1284 | d_parent and d_inode should not be used without care (because | |
1285 | they can change and, in d_inode case, even become NULL under | |
1286 | us). | |
1287 | ||
1288 | If a situation is encountered that rcu-walk cannot handle, | |
1289 | return | |
34286d66 NP |
1290 | -ECHILD and it will be called again in ref-walk mode. |
1291 | ||
74596085 | 1292 | ``d_weak_revalidate`` |
ee5dc049 TH |
1293 | called when the VFS needs to revalidate a "jumped" dentry. This |
1294 | is called when a path-walk ends at dentry that was not acquired | |
1295 | by doing a lookup in the parent directory. This includes "/", | |
1296 | "." and "..", as well as procfs-style symlinks and mountpoint | |
1297 | traversal. | |
ecf3d1f1 | 1298 | |
ee5dc049 TH |
1299 | In this case, we are less concerned with whether the dentry is |
1300 | still fully correct, but rather that the inode is still valid. | |
1301 | As with d_revalidate, most local filesystems will set this to | |
1302 | NULL since their dcache entries are always valid. | |
ecf3d1f1 | 1303 | |
ee5dc049 TH |
1304 | This function has the same return code semantics as |
1305 | d_revalidate. | |
ecf3d1f1 JL |
1306 | |
1307 | d_weak_revalidate is only called after leaving rcu-walk mode. | |
1308 | ||
ee5dc049 TH |
1309 | ``d_hash`` |
1310 | called when the VFS adds a dentry to the hash table. The first | |
621e155a | 1311 | dentry passed to d_hash is the parent directory that the name is |
da53be12 | 1312 | to be hashed into. |
b1e6a015 NP |
1313 | |
1314 | Same locking and synchronisation rules as d_compare regarding | |
1315 | what is safe to dereference etc. | |
1da177e4 | 1316 | |
ee5dc049 TH |
1317 | ``d_compare`` |
1318 | called to compare a dentry name with a given name. The first | |
621e155a | 1319 | dentry is the parent of the dentry to be compared, the second is |
ee5dc049 TH |
1320 | the child dentry. len and name string are properties of the |
1321 | dentry to be compared. qstr is the name to compare it with. | |
621e155a NP |
1322 | |
1323 | Must be constant and idempotent, and should not take locks if | |
ee5dc049 TH |
1324 | possible, and should not or store into the dentry. Should not |
1325 | dereference pointers outside the dentry without lots of care | |
1326 | (eg. d_parent, d_inode, d_name should not be used). | |
1327 | ||
1328 | However, our vfsmount is pinned, and RCU held, so the dentries | |
1329 | and inodes won't disappear, neither will our sb or filesystem | |
1330 | module. ->d_sb may be used. | |
1331 | ||
1332 | It is a tricky calling convention because it needs to be called | |
1333 | under "rcu-walk", ie. without any locks or references on things. | |
1334 | ||
1335 | ``d_delete`` | |
1336 | called when the last reference to a dentry is dropped and the | |
1337 | dcache is deciding whether or not to cache it. Return 1 to | |
1338 | delete immediately, or 0 to cache the dentry. Default is NULL | |
1339 | which means to always cache a reachable dentry. d_delete must | |
1340 | be constant and idempotent. | |
1341 | ||
1342 | ``d_init`` | |
1343 | called when a dentry is allocated | |
1344 | ||
1345 | ``d_release`` | |
1346 | called when a dentry is really deallocated | |
1347 | ||
1348 | ``d_iput`` | |
1349 | called when a dentry loses its inode (just prior to its being | |
1350 | deallocated). The default when this is NULL is that the VFS | |
1351 | calls iput(). If you define this method, you must call iput() | |
1352 | yourself | |
1353 | ||
1354 | ``d_dname`` | |
1355 | called when the pathname of a dentry should be generated. | |
1356 | Useful for some pseudo filesystems (sockfs, pipefs, ...) to | |
1357 | delay pathname generation. (Instead of doing it when dentry is | |
1358 | created, it's done only when the path is needed.). Real | |
1359 | filesystems probably dont want to use it, because their dentries | |
1360 | are present in global dcache hash, so their hash should be an | |
1361 | invariant. As no lock is held, d_dname() should not try to | |
1362 | modify the dentry itself, unless appropriate SMP safety is used. | |
1363 | CAUTION : d_path() logic is quite tricky. The correct way to | |
1364 | return for example "Hello" is to put it at the end of the | |
1365 | buffer, and returns a pointer to the first char. | |
1366 | dynamic_dname() helper function is provided to take care of | |
1367 | this. | |
c23fbb6b | 1368 | |
0cac643c MS |
1369 | Example : |
1370 | ||
af96c1e3 TH |
1371 | .. code-block:: c |
1372 | ||
0cac643c MS |
1373 | static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen) |
1374 | { | |
1375 | return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]", | |
1376 | dentry->d_inode->i_ino); | |
1377 | } | |
1378 | ||
ee5dc049 TH |
1379 | ``d_automount`` |
1380 | called when an automount dentry is to be traversed (optional). | |
1381 | This should create a new VFS mount record and return the record | |
1382 | to the caller. The caller is supplied with a path parameter | |
1383 | giving the automount directory to describe the automount target | |
1384 | and the parent VFS mount record to provide inheritable mount | |
1385 | parameters. NULL should be returned if someone else managed to | |
1386 | make the automount first. If the vfsmount creation failed, then | |
1387 | an error code should be returned. If -EISDIR is returned, then | |
1388 | the directory will be treated as an ordinary directory and | |
1389 | returned to pathwalk to continue walking. | |
1390 | ||
1391 | If a vfsmount is returned, the caller will attempt to mount it | |
1392 | on the mountpoint and will remove the vfsmount from its | |
1393 | expiration list in the case of failure. The vfsmount should be | |
1394 | returned with 2 refs on it to prevent automatic expiration - the | |
1395 | caller will clean up the additional ref. | |
1396 | ||
1397 | This function is only used if DCACHE_NEED_AUTOMOUNT is set on | |
1398 | the dentry. This is set by __d_instantiate() if S_AUTOMOUNT is | |
1399 | set on the inode being added. | |
1400 | ||
1401 | ``d_manage`` | |
1402 | called to allow the filesystem to manage the transition from a | |
1403 | dentry (optional). This allows autofs, for example, to hold up | |
1404 | clients waiting to explore behind a 'mountpoint' while letting | |
1405 | the daemon go past and construct the subtree there. 0 should be | |
1406 | returned to let the calling process continue. -EISDIR can be | |
1407 | returned to tell pathwalk to use this directory as an ordinary | |
1408 | directory and to ignore anything mounted on it and not to check | |
1409 | the automount flag. Any other error code will abort pathwalk | |
1410 | completely. | |
cc53ce53 | 1411 | |
ab90911f | 1412 | If the 'rcu_walk' parameter is true, then the caller is doing a |
ee5dc049 TH |
1413 | pathwalk in RCU-walk mode. Sleeping is not permitted in this |
1414 | mode, and the caller can be asked to leave it and call again by | |
1415 | returning -ECHILD. -EISDIR may also be returned to tell | |
1416 | pathwalk to ignore d_automount or any mounts. | |
ab90911f | 1417 | |
ee5dc049 TH |
1418 | This function is only used if DCACHE_MANAGE_TRANSIT is set on |
1419 | the dentry being transited from. | |
cc53ce53 | 1420 | |
ee5dc049 | 1421 | ``d_real`` |
11b3f8ae AG |
1422 | overlay/union type filesystems implement this method to return one |
1423 | of the underlying dentries of a regular file hidden by the overlay. | |
c23fbb6b | 1424 | |
11b3f8ae AG |
1425 | The 'type' argument takes the values D_REAL_DATA or D_REAL_METADATA |
1426 | for returning the real underlying dentry that refers to the inode | |
1427 | hosting the file's data or metadata respectively. | |
e698b8a4 | 1428 | |
11b3f8ae | 1429 | For non-regular files, the 'dentry' argument is returned. |
c23fbb6b | 1430 | |
1da177e4 | 1431 | Each dentry has a pointer to its parent dentry, as well as a hash list |
4ee33ea4 | 1432 | of child dentries. Child dentries are basically like files in a |
1da177e4 LT |
1433 | directory. |
1434 | ||
5ea626aa | 1435 | |
cc7d1f8f | 1436 | Directory Entry Cache API |
1da177e4 LT |
1437 | -------------------------- |
1438 | ||
1439 | There are a number of functions defined which permit a filesystem to | |
1440 | manipulate dentries: | |
1441 | ||
ee5dc049 TH |
1442 | ``dget`` |
1443 | open a new handle for an existing dentry (this just increments | |
1da177e4 LT |
1444 | the usage count) |
1445 | ||
ee5dc049 TH |
1446 | ``dput`` |
1447 | close a handle for a dentry (decrements the usage count). If | |
fe15ce44 NP |
1448 | the usage count drops to 0, and the dentry is still in its |
1449 | parent's hash, the "d_delete" method is called to check whether | |
ee5dc049 TH |
1450 | it should be cached. If it should not be cached, or if the |
1451 | dentry is not hashed, it is deleted. Otherwise cached dentries | |
1452 | are put into an LRU list to be reclaimed on memory shortage. | |
1453 | ||
1454 | ``d_drop`` | |
1455 | this unhashes a dentry from its parents hash list. A subsequent | |
1456 | call to dput() will deallocate the dentry if its usage count | |
1457 | drops to 0 | |
1458 | ||
1459 | ``d_delete`` | |
1460 | delete a dentry. If there are no other open references to the | |
1461 | dentry then the dentry is turned into a negative dentry (the | |
1462 | d_iput() method is called). If there are other references, then | |
1463 | d_drop() is called instead | |
1464 | ||
1465 | ``d_add`` | |
1466 | add a dentry to its parents hash list and then calls | |
1da177e4 LT |
1467 | d_instantiate() |
1468 | ||
ee5dc049 TH |
1469 | ``d_instantiate`` |
1470 | add a dentry to the alias hash list for the inode and updates | |
1471 | the "d_inode" member. The "i_count" member in the inode | |
1472 | structure should be set/incremented. If the inode pointer is | |
1473 | NULL, the dentry is called a "negative dentry". This function | |
1474 | is commonly called when an inode is created for an existing | |
1475 | negative dentry | |
1476 | ||
1477 | ``d_lookup`` | |
1478 | look up a dentry given its parent and path name component It | |
1479 | looks up the child of that given name from the dcache hash | |
1480 | table. If it is found, the reference count is incremented and | |
1481 | the dentry is returned. The caller must use dput() to free the | |
1482 | dentry when it finishes using it. | |
1da177e4 | 1483 | |
e04c83cd | 1484 | |
f84e3f52 MS |
1485 | Mount Options |
1486 | ============= | |
1487 | ||
e04c83cd | 1488 | |
f84e3f52 MS |
1489 | Parsing options |
1490 | --------------- | |
1491 | ||
1492 | On mount and remount the filesystem is passed a string containing a | |
1493 | comma separated list of mount options. The options can have either of | |
1494 | these forms: | |
1495 | ||
1496 | option | |
1497 | option=value | |
1498 | ||
1499 | The <linux/parser.h> header defines an API that helps parse these | |
1500 | options. There are plenty of examples on how to use it in existing | |
1501 | filesystems. | |
1502 | ||
e04c83cd | 1503 | |
f84e3f52 MS |
1504 | Showing options |
1505 | --------------- | |
1506 | ||
90caa781 TH |
1507 | If a filesystem accepts mount options, it must define show_options() to |
1508 | show all the currently active options. The rules are: | |
f84e3f52 MS |
1509 | |
1510 | - options MUST be shown which are not default or their values differ | |
1511 | from the default | |
1512 | ||
1513 | - options MAY be shown which are enabled by default or have their | |
1514 | default value | |
1515 | ||
90caa781 TH |
1516 | Options used only internally between a mount helper and the kernel (such |
1517 | as file descriptors), or which only have an effect during the mounting | |
1518 | (such as ones controlling the creation of a journal) are exempt from the | |
1519 | above rules. | |
f84e3f52 | 1520 | |
90caa781 TH |
1521 | The underlying reason for the above rules is to make sure, that a mount |
1522 | can be accurately replicated (e.g. umounting and mounting again) based | |
1523 | on the information found in /proc/mounts. | |
f84e3f52 | 1524 | |
e04c83cd | 1525 | |
cc7d1f8f PE |
1526 | Resources |
1527 | ========= | |
1528 | ||
1529 | (Note some of these resources are not up-to-date with the latest kernel | |
1530 | version.) | |
1531 | ||
1532 | Creating Linux virtual filesystems. 2002 | |
c69f22f2 | 1533 | <https://lwn.net/Articles/13325/> |
cc7d1f8f PE |
1534 | |
1535 | The Linux Virtual File-system Layer by Neil Brown. 1999 | |
1536 | <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html> | |
1537 | ||
1538 | A tour of the Linux VFS by Michael K. Johnson. 1996 | |
c69f22f2 | 1539 | <https://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html> |
cc7d1f8f PE |
1540 | |
1541 | A small trail through the Linux kernel by Andries Brouwer. 2001 | |
c69f22f2 | 1542 | <https://www.win.tue.nl/~aeb/linux/vfs/trail.html> |