Commit | Line | Data |
---|---|---|
1da177e4 | 1 | |
5ea626aa | 2 | Overview of the Linux Virtual File System |
1da177e4 | 3 | |
5ea626aa | 4 | Original author: Richard Gooch <rgooch@atnf.csiro.au> |
1da177e4 | 5 | |
0746aec3 | 6 | Last updated on June 24, 2007. |
1da177e4 | 7 | |
5ea626aa PE |
8 | Copyright (C) 1999 Richard Gooch |
9 | Copyright (C) 2005 Pekka Enberg | |
1da177e4 | 10 | |
5ea626aa | 11 | This file is released under the GPLv2. |
1da177e4 | 12 | |
1da177e4 | 13 | |
cc7d1f8f PE |
14 | Introduction |
15 | ============ | |
1da177e4 | 16 | |
cc7d1f8f PE |
17 | The Virtual File System (also known as the Virtual Filesystem Switch) |
18 | is the software layer in the kernel that provides the filesystem | |
19 | interface to userspace programs. It also provides an abstraction | |
20 | within the kernel which allows different filesystem implementations to | |
21 | coexist. | |
1da177e4 | 22 | |
cc7d1f8f PE |
23 | VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so |
24 | on are called from a process context. Filesystem locking is described | |
25 | in the document Documentation/filesystems/Locking. | |
1da177e4 | 26 | |
1da177e4 | 27 | |
cc7d1f8f PE |
28 | Directory Entry Cache (dcache) |
29 | ------------------------------ | |
1da177e4 | 30 | |
cc7d1f8f PE |
31 | The VFS implements the open(2), stat(2), chmod(2), and similar system |
32 | calls. The pathname argument that is passed to them is used by the VFS | |
33 | to search through the directory entry cache (also known as the dentry | |
34 | cache or dcache). This provides a very fast look-up mechanism to | |
35 | translate a pathname (filename) into a specific dentry. Dentries live | |
36 | in RAM and are never saved to disc: they exist only for performance. | |
37 | ||
38 | The dentry cache is meant to be a view into your entire filespace. As | |
39 | most computers cannot fit all dentries in the RAM at the same time, | |
40 | some bits of the cache are missing. In order to resolve your pathname | |
41 | into a dentry, the VFS may have to resort to creating dentries along | |
42 | the way, and then loading the inode. This is done by looking up the | |
43 | inode. | |
44 | ||
45 | ||
46 | The Inode Object | |
47 | ---------------- | |
48 | ||
49 | An individual dentry usually has a pointer to an inode. Inodes are | |
50 | filesystem objects such as regular files, directories, FIFOs and other | |
51 | beasts. They live either on the disc (for block device filesystems) | |
52 | or in the memory (for pseudo filesystems). Inodes that live on the | |
53 | disc are copied into the memory when required and changes to the inode | |
54 | are written back to disc. A single inode can be pointed to by multiple | |
55 | dentries (hard links, for example, do this). | |
56 | ||
57 | To look up an inode requires that the VFS calls the lookup() method of | |
58 | the parent directory inode. This method is installed by the specific | |
59 | filesystem implementation that the inode lives in. Once the VFS has | |
60 | the required dentry (and hence the inode), we can do all those boring | |
61 | things like open(2) the file, or stat(2) it to peek at the inode | |
62 | data. The stat(2) operation is fairly simple: once the VFS has the | |
63 | dentry, it peeks at the inode data and passes some of it back to | |
64 | userspace. | |
65 | ||
66 | ||
67 | The File Object | |
68 | --------------- | |
1da177e4 LT |
69 | |
70 | Opening a file requires another operation: allocation of a file | |
71 | structure (this is the kernel-side implementation of file | |
5ea626aa | 72 | descriptors). The freshly allocated file structure is initialized with |
1da177e4 LT |
73 | a pointer to the dentry and a set of file operation member functions. |
74 | These are taken from the inode data. The open() file method is then | |
a33f3224 | 75 | called so the specific filesystem implementation can do its work. You |
cc7d1f8f PE |
76 | can see that this is another switch performed by the VFS. The file |
77 | structure is placed into the file descriptor table for the process. | |
1da177e4 LT |
78 | |
79 | Reading, writing and closing files (and other assorted VFS operations) | |
80 | is done by using the userspace file descriptor to grab the appropriate | |
cc7d1f8f PE |
81 | file structure, and then calling the required file structure method to |
82 | do whatever is required. For as long as the file is open, it keeps the | |
83 | dentry in use, which in turn means that the VFS inode is still in use. | |
1da177e4 | 84 | |
5ea626aa PE |
85 | |
86 | Registering and Mounting a Filesystem | |
cc7d1f8f | 87 | ===================================== |
1da177e4 | 88 | |
cc7d1f8f PE |
89 | To register and unregister a filesystem, use the following API |
90 | functions: | |
1da177e4 | 91 | |
cc7d1f8f | 92 | #include <linux/fs.h> |
1da177e4 | 93 | |
cc7d1f8f PE |
94 | extern int register_filesystem(struct file_system_type *); |
95 | extern int unregister_filesystem(struct file_system_type *); | |
1da177e4 | 96 | |
cc7d1f8f | 97 | The passed struct file_system_type describes your filesystem. When a |
1a102ff9 AV |
98 | request is made to mount a filesystem onto a directory in your namespace, |
99 | the VFS will call the appropriate mount() method for the specific | |
25985edc | 100 | filesystem. New vfsmount referring to the tree returned by ->mount() |
1a102ff9 AV |
101 | will be attached to the mountpoint, so that when pathname resolution |
102 | reaches the mountpoint it will jump into the root of that vfsmount. | |
1da177e4 | 103 | |
cc7d1f8f PE |
104 | You can see all filesystems that are registered to the kernel in the |
105 | file /proc/filesystems. | |
1da177e4 LT |
106 | |
107 | ||
5ea626aa | 108 | struct file_system_type |
cc7d1f8f | 109 | ----------------------- |
1da177e4 | 110 | |
1a102ff9 | 111 | This describes the filesystem. As of kernel 2.6.39, the following |
1da177e4 LT |
112 | members are defined: |
113 | ||
114 | struct file_system_type { | |
115 | const char *name; | |
116 | int fs_flags; | |
b1349f25 | 117 | struct dentry *(*mount) (struct file_system_type *, int, |
1a102ff9 | 118 | const char *, void *); |
5ea626aa PE |
119 | void (*kill_sb) (struct super_block *); |
120 | struct module *owner; | |
121 | struct file_system_type * next; | |
122 | struct list_head fs_supers; | |
0746aec3 BP |
123 | struct lock_class_key s_lock_key; |
124 | struct lock_class_key s_umount_key; | |
1da177e4 LT |
125 | }; |
126 | ||
127 | name: the name of the filesystem type, such as "ext2", "iso9660", | |
128 | "msdos" and so on | |
129 | ||
130 | fs_flags: various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.) | |
131 | ||
1a102ff9 | 132 | mount: the method to call when a new instance of this |
1da177e4 LT |
133 | filesystem should be mounted |
134 | ||
5ea626aa | 135 | kill_sb: the method to call when an instance of this filesystem |
1a102ff9 | 136 | should be shut down |
5ea626aa PE |
137 | |
138 | owner: for internal VFS use: you should initialize this to THIS_MODULE in | |
139 | most cases. | |
1da177e4 | 140 | |
5ea626aa PE |
141 | next: for internal VFS use: you should initialize this to NULL |
142 | ||
0746aec3 BP |
143 | s_lock_key, s_umount_key: lockdep-specific |
144 | ||
1a102ff9 | 145 | The mount() method has the following arguments: |
1da177e4 | 146 | |
d9195881 | 147 | struct file_system_type *fs_type: describes the filesystem, partly initialized |
0746aec3 | 148 | by the specific filesystem code |
5ea626aa PE |
149 | |
150 | int flags: mount flags | |
151 | ||
152 | const char *dev_name: the device name we are mounting. | |
1da177e4 LT |
153 | |
154 | void *data: arbitrary mount options, usually comes as an ASCII | |
f84e3f52 | 155 | string (see "Mount Options" section) |
1da177e4 | 156 | |
1a102ff9 AV |
157 | The mount() method must return the root dentry of the tree requested by |
158 | caller. An active reference to its superblock must be grabbed and the | |
159 | superblock must be locked. On failure it should return ERR_PTR(error). | |
1da177e4 | 160 | |
1a102ff9 AV |
161 | The arguments match those of mount(2) and their interpretation |
162 | depends on filesystem type. E.g. for block filesystems, dev_name is | |
163 | interpreted as block device name, that device is opened and if it | |
164 | contains a suitable filesystem image the method creates and initializes | |
165 | struct super_block accordingly, returning its root dentry to caller. | |
166 | ||
167 | ->mount() may choose to return a subtree of existing filesystem - it | |
168 | doesn't have to create a new one. The main result from the caller's | |
169 | point of view is a reference to dentry at the root of (sub)tree to | |
170 | be attached; creation of new superblock is a common side effect. | |
1da177e4 LT |
171 | |
172 | The most interesting member of the superblock structure that the | |
1a102ff9 | 173 | mount() method fills in is the "s_op" field. This is a pointer to |
1da177e4 LT |
174 | a "struct super_operations" which describes the next level of the |
175 | filesystem implementation. | |
176 | ||
1a102ff9 AV |
177 | Usually, a filesystem uses one of the generic mount() implementations |
178 | and provides a fill_super() callback instead. The generic variants are: | |
5ea626aa | 179 | |
1a102ff9 | 180 | mount_bdev: mount a filesystem residing on a block device |
1da177e4 | 181 | |
1a102ff9 | 182 | mount_nodev: mount a filesystem that is not backed by a device |
5ea626aa | 183 | |
1a102ff9 | 184 | mount_single: mount a filesystem which shares the instance between |
5ea626aa PE |
185 | all mounts |
186 | ||
1a102ff9 | 187 | A fill_super() callback implementation has the following arguments: |
5ea626aa | 188 | |
1a102ff9 | 189 | struct super_block *sb: the superblock structure. The callback |
5ea626aa PE |
190 | must initialize this properly. |
191 | ||
192 | void *data: arbitrary mount options, usually comes as an ASCII | |
f84e3f52 | 193 | string (see "Mount Options" section) |
5ea626aa PE |
194 | |
195 | int silent: whether or not to be silent on error | |
196 | ||
197 | ||
cc7d1f8f PE |
198 | The Superblock Object |
199 | ===================== | |
200 | ||
201 | A superblock object represents a mounted filesystem. | |
202 | ||
203 | ||
5ea626aa | 204 | struct super_operations |
cc7d1f8f | 205 | ----------------------- |
1da177e4 LT |
206 | |
207 | This describes how the VFS can manipulate the superblock of your | |
422b14c2 | 208 | filesystem. As of kernel 2.6.22, the following members are defined: |
1da177e4 LT |
209 | |
210 | struct super_operations { | |
5ea626aa PE |
211 | struct inode *(*alloc_inode)(struct super_block *sb); |
212 | void (*destroy_inode)(struct inode *); | |
213 | ||
aa385729 | 214 | void (*dirty_inode) (struct inode *, int flags); |
5ea626aa | 215 | int (*write_inode) (struct inode *, int); |
5ea626aa PE |
216 | void (*drop_inode) (struct inode *); |
217 | void (*delete_inode) (struct inode *); | |
218 | void (*put_super) (struct super_block *); | |
5ea626aa | 219 | int (*sync_fs)(struct super_block *sb, int wait); |
c4be0c1d TS |
220 | int (*freeze_fs) (struct super_block *); |
221 | int (*unfreeze_fs) (struct super_block *); | |
726c3342 | 222 | int (*statfs) (struct dentry *, struct kstatfs *); |
5ea626aa PE |
223 | int (*remount_fs) (struct super_block *, int *, char *); |
224 | void (*clear_inode) (struct inode *); | |
225 | void (*umount_begin) (struct super_block *); | |
226 | ||
34c80b1d | 227 | int (*show_options)(struct seq_file *, struct dentry *); |
5ea626aa PE |
228 | |
229 | ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); | |
230 | ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); | |
0e1fdafd DC |
231 | int (*nr_cached_objects)(struct super_block *); |
232 | void (*free_cached_objects)(struct super_block *, int); | |
1da177e4 LT |
233 | }; |
234 | ||
235 | All methods are called without any locks being held, unless otherwise | |
236 | noted. This means that most methods can block safely. All methods are | |
237 | only called from a process context (i.e. not from an interrupt handler | |
238 | or bottom half). | |
239 | ||
4e07ad64 | 240 | alloc_inode: this method is called by alloc_inode() to allocate memory |
341546f5 N |
241 | for struct inode and initialize it. If this function is not |
242 | defined, a simple 'struct inode' is allocated. Normally | |
243 | alloc_inode will be used to allocate a larger structure which | |
244 | contains a 'struct inode' embedded within it. | |
5ea626aa PE |
245 | |
246 | destroy_inode: this method is called by destroy_inode() to release | |
341546f5 N |
247 | resources allocated for struct inode. It is only required if |
248 | ->alloc_inode was defined and simply undoes anything done by | |
249 | ->alloc_inode. | |
5ea626aa | 250 | |
5ea626aa | 251 | dirty_inode: this method is called by the VFS to mark an inode dirty. |
1da177e4 LT |
252 | |
253 | write_inode: this method is called when the VFS needs to write an | |
254 | inode to disc. The second parameter indicates whether the write | |
255 | should be synchronous or not, not all filesystems check this flag. | |
256 | ||
1da177e4 | 257 | drop_inode: called when the last access to the inode is dropped, |
f283c86a | 258 | with the inode->i_lock spinlock held. |
1da177e4 | 259 | |
5ea626aa | 260 | This method should be either NULL (normal UNIX filesystem |
1da177e4 LT |
261 | semantics) or "generic_delete_inode" (for filesystems that do not |
262 | want to cache inodes - causing "delete_inode" to always be | |
263 | called regardless of the value of i_nlink) | |
264 | ||
5ea626aa | 265 | The "generic_delete_inode()" behavior is equivalent to the |
1da177e4 LT |
266 | old practice of using "force_delete" in the put_inode() case, |
267 | but does not have the races that the "force_delete()" approach | |
268 | had. | |
269 | ||
270 | delete_inode: called when the VFS wants to delete an inode | |
271 | ||
1da177e4 LT |
272 | put_super: called when the VFS wishes to free the superblock |
273 | (i.e. unmount). This is called with the superblock lock held | |
274 | ||
5ea626aa PE |
275 | sync_fs: called when VFS is writing out all dirty data associated with |
276 | a superblock. The second parameter indicates whether the method | |
277 | should wait until the write out has been completed. Optional. | |
278 | ||
c4be0c1d | 279 | freeze_fs: called when VFS is locking a filesystem and |
cc7d1f8f PE |
280 | forcing it into a consistent state. This method is currently |
281 | used by the Logical Volume Manager (LVM). | |
5ea626aa | 282 | |
c4be0c1d | 283 | unfreeze_fs: called when VFS is unlocking a filesystem and making it writable |
5ea626aa PE |
284 | again. |
285 | ||
66672fef | 286 | statfs: called when the VFS needs to get filesystem statistics. |
1da177e4 LT |
287 | |
288 | remount_fs: called when the filesystem is remounted. This is called | |
289 | with the kernel lock held | |
290 | ||
291 | clear_inode: called then the VFS clears the inode. Optional | |
292 | ||
5ea626aa PE |
293 | umount_begin: called when the VFS is unmounting a filesystem. |
294 | ||
f84e3f52 MS |
295 | show_options: called by the VFS to show mount options for |
296 | /proc/<pid>/mounts. (see "Mount Options" section) | |
5ea626aa PE |
297 | |
298 | quota_read: called by the VFS to read from filesystem quota file. | |
299 | ||
300 | quota_write: called by the VFS to write to filesystem quota file. | |
301 | ||
0e1fdafd DC |
302 | nr_cached_objects: called by the sb cache shrinking function for the |
303 | filesystem to return the number of freeable cached objects it contains. | |
304 | Optional. | |
305 | ||
306 | free_cache_objects: called by the sb cache shrinking function for the | |
307 | filesystem to scan the number of objects indicated to try to free them. | |
308 | Optional, but any filesystem implementing this method needs to also | |
309 | implement ->nr_cached_objects for it to be called correctly. | |
310 | ||
311 | We can't do anything with any errors that the filesystem might | |
312 | encountered, hence the void return type. This will never be called if | |
313 | the VM is trying to reclaim under GFP_NOFS conditions, hence this | |
314 | method does not need to handle that situation itself. | |
315 | ||
8ab47664 DC |
316 | Implementations must include conditional reschedule calls inside any |
317 | scanning loop that is done. This allows the VFS to determine | |
318 | appropriate scan batch sizes without having to worry about whether | |
319 | implementations will cause holdoff problems due to large scan batch | |
320 | sizes. | |
321 | ||
12debc42 DH |
322 | Whoever sets up the inode is responsible for filling in the "i_op" field. This |
323 | is a pointer to a "struct inode_operations" which describes the methods that | |
324 | can be performed on individual inodes. | |
1da177e4 LT |
325 | |
326 | ||
cc7d1f8f PE |
327 | The Inode Object |
328 | ================ | |
329 | ||
330 | An inode object represents an object within the filesystem. | |
331 | ||
332 | ||
5ea626aa | 333 | struct inode_operations |
cc7d1f8f | 334 | ----------------------- |
1da177e4 LT |
335 | |
336 | This describes how the VFS can manipulate an inode in your | |
422b14c2 | 337 | filesystem. As of kernel 2.6.22, the following members are defined: |
1da177e4 LT |
338 | |
339 | struct inode_operations { | |
ebfc3b49 | 340 | int (*create) (struct inode *,struct dentry *, umode_t, bool); |
00cd8dd3 | 341 | struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int); |
1da177e4 LT |
342 | int (*link) (struct dentry *,struct inode *,struct dentry *); |
343 | int (*unlink) (struct inode *,struct dentry *); | |
344 | int (*symlink) (struct inode *,struct dentry *,const char *); | |
18bb1db3 | 345 | int (*mkdir) (struct inode *,struct dentry *,umode_t); |
1da177e4 | 346 | int (*rmdir) (struct inode *,struct dentry *); |
1a67aafb | 347 | int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t); |
1da177e4 LT |
348 | int (*rename) (struct inode *, struct dentry *, |
349 | struct inode *, struct dentry *); | |
520c8b16 MS |
350 | int (*rename2) (struct inode *, struct dentry *, |
351 | struct inode *, struct dentry *, unsigned int); | |
5ea626aa | 352 | int (*readlink) (struct dentry *, char __user *,int); |
6e77137b | 353 | const char *(*follow_link) (struct dentry *, void **); |
5f2c4179 | 354 | void (*put_link) (struct inode *, void *); |
10556cb2 | 355 | int (*permission) (struct inode *, int); |
4e34e719 | 356 | int (*get_acl)(struct inode *, int); |
5ea626aa PE |
357 | int (*setattr) (struct dentry *, struct iattr *); |
358 | int (*getattr) (struct vfsmount *mnt, struct dentry *, struct kstat *); | |
359 | int (*setxattr) (struct dentry *, const char *,const void *,size_t,int); | |
360 | ssize_t (*getxattr) (struct dentry *, const char *, void *, size_t); | |
361 | ssize_t (*listxattr) (struct dentry *, char *, size_t); | |
362 | int (*removexattr) (struct dentry *, const char *); | |
c3b2da31 | 363 | void (*update_time)(struct inode *, struct timespec *, int); |
0854d450 MS |
364 | int (*atomic_open)(struct inode *, struct dentry *, struct file *, |
365 | unsigned open_flag, umode_t create_mode, int *opened); | |
48bde8d3 | 366 | int (*tmpfile) (struct inode *, struct dentry *, umode_t); |
4aa7c634 | 367 | int (*dentry_open)(struct dentry *, struct file *, const struct cred *); |
1da177e4 LT |
368 | }; |
369 | ||
370 | Again, all methods are called without any locks being held, unless | |
371 | otherwise noted. | |
372 | ||
1da177e4 LT |
373 | create: called by the open(2) and creat(2) system calls. Only |
374 | required if you want to support regular files. The dentry you | |
375 | get should not have an inode (i.e. it should be a negative | |
376 | dentry). Here you will probably call d_instantiate() with the | |
377 | dentry and the newly created inode | |
378 | ||
379 | lookup: called when the VFS needs to look up an inode in a parent | |
380 | directory. The name to look for is found in the dentry. This | |
381 | method must call d_add() to insert the found inode into the | |
382 | dentry. The "i_count" field in the inode structure should be | |
383 | incremented. If the named inode does not exist a NULL inode | |
384 | should be inserted into the dentry (this is called a negative | |
385 | dentry). Returning an error code from this routine must only | |
386 | be done on a real error, otherwise creating inodes with system | |
387 | calls like create(2), mknod(2), mkdir(2) and so on will fail. | |
388 | If you wish to overload the dentry methods then you should | |
389 | initialise the "d_dop" field in the dentry; this is a pointer | |
390 | to a struct "dentry_operations". | |
391 | This method is called with the directory inode semaphore held | |
392 | ||
393 | link: called by the link(2) system call. Only required if you want | |
394 | to support hard links. You will probably need to call | |
395 | d_instantiate() just as you would in the create() method | |
396 | ||
397 | unlink: called by the unlink(2) system call. Only required if you | |
398 | want to support deleting inodes | |
399 | ||
400 | symlink: called by the symlink(2) system call. Only required if you | |
401 | want to support symlinks. You will probably need to call | |
402 | d_instantiate() just as you would in the create() method | |
403 | ||
404 | mkdir: called by the mkdir(2) system call. Only required if you want | |
405 | to support creating subdirectories. You will probably need to | |
406 | call d_instantiate() just as you would in the create() method | |
407 | ||
408 | rmdir: called by the rmdir(2) system call. Only required if you want | |
409 | to support deleting subdirectories | |
410 | ||
411 | mknod: called by the mknod(2) system call to create a device (char, | |
412 | block) inode or a named pipe (FIFO) or socket. Only required | |
413 | if you want to support creating these types of inodes. You | |
414 | will probably need to call d_instantiate() just as you would | |
415 | in the create() method | |
416 | ||
cc7d1f8f PE |
417 | rename: called by the rename(2) system call to rename the object to |
418 | have the parent and name given by the second inode and dentry. | |
419 | ||
520c8b16 MS |
420 | rename2: this has an additional flags argument compared to rename. |
421 | If no flags are supported by the filesystem then this method | |
422 | need not be implemented. If some flags are supported then the | |
423 | filesystem must return -EINVAL for any unsupported or unknown | |
424 | flags. Currently the following flags are implemented: | |
425 | (1) RENAME_NOREPLACE: this flag indicates that if the target | |
426 | of the rename exists the rename should fail with -EEXIST | |
427 | instead of replacing the target. The VFS already checks for | |
428 | existence, so for local filesystems the RENAME_NOREPLACE | |
429 | implementation is equivalent to plain rename. | |
430 | (2) RENAME_EXCHANGE: exchange source and target. Both must | |
431 | exist; this is checked by the VFS. Unlike plain rename, | |
432 | source and target may be of different type. | |
433 | ||
1da177e4 LT |
434 | readlink: called by the readlink(2) system call. Only required if |
435 | you want to support reading symbolic links | |
436 | ||
437 | follow_link: called by the VFS to follow a symbolic link to the | |
5ea626aa | 438 | inode it points to. Only required if you want to support |
203bc643 AV |
439 | symbolic links. This method returns the symlink body |
440 | to traverse (and possibly resets the current position with | |
441 | nd_jump_link()). If the body won't go away until the inode | |
442 | is gone, nothing else is needed; if it needs to be otherwise | |
443 | pinned, the data needed to release whatever we'd grabbed | |
444 | is to be stored in void * variable passed by address to | |
445 | follow_link() instance. | |
5ea626aa PE |
446 | |
447 | put_link: called by the VFS to release resources allocated by | |
203bc643 AV |
448 | follow_link(). The cookie stored by follow_link() is passed |
449 | to this method as the last parameter; only called when | |
450 | cookie isn't NULL. | |
cc7d1f8f | 451 | |
5ea626aa PE |
452 | permission: called by the VFS to check for access rights on a POSIX-like |
453 | filesystem. | |
454 | ||
10556cb2 | 455 | May be called in rcu-walk mode (mask & MAY_NOT_BLOCK). If in rcu-walk |
a82416da | 456 | mode, the filesystem must check the permission without blocking or |
b74c79e9 NP |
457 | storing to the inode. |
458 | ||
459 | If a situation is encountered that rcu-walk cannot handle, return | |
460 | -ECHILD and it will be called again in ref-walk mode. | |
461 | ||
cc7d1f8f PE |
462 | setattr: called by the VFS to set attributes for a file. This method |
463 | is called by chmod(2) and related system calls. | |
5ea626aa | 464 | |
cc7d1f8f PE |
465 | getattr: called by the VFS to get attributes of a file. This method |
466 | is called by stat(2) and related system calls. | |
5ea626aa PE |
467 | |
468 | setxattr: called by the VFS to set an extended attribute for a file. | |
cc7d1f8f PE |
469 | Extended attribute is a name:value pair associated with an |
470 | inode. This method is called by setxattr(2) system call. | |
471 | ||
472 | getxattr: called by the VFS to retrieve the value of an extended | |
473 | attribute name. This method is called by getxattr(2) function | |
474 | call. | |
475 | ||
476 | listxattr: called by the VFS to list all extended attributes for a | |
477 | given file. This method is called by listxattr(2) system call. | |
5ea626aa | 478 | |
cc7d1f8f PE |
479 | removexattr: called by the VFS to remove an extended attribute from |
480 | a file. This method is called by removexattr(2) system call. | |
5ea626aa | 481 | |
c3b2da31 JB |
482 | update_time: called by the VFS to update a specific time or the i_version of |
483 | an inode. If this is not defined the VFS will update the inode itself | |
484 | and call mark_inode_dirty_sync. | |
5ea626aa | 485 | |
d18e9008 MS |
486 | atomic_open: called on the last component of an open. Using this optional |
487 | method the filesystem can look up, possibly create and open the file in | |
488 | one atomic operation. If it cannot perform this (e.g. the file type | |
d9585277 | 489 | turned out to be wrong) it may signal this by returning 1 instead of |
0854d450 MS |
490 | usual 0 or -ve . This method is only called if the last component is |
491 | negative or needs lookup. Cached positive dentries are still handled by | |
492 | f_op->open(). If the file was created, the FILE_CREATED flag should be | |
493 | set in "opened". In case of O_EXCL the method must only succeed if the | |
494 | file didn't exist and hence FILE_CREATED shall always be set on success. | |
d18e9008 | 495 | |
48bde8d3 AV |
496 | tmpfile: called in the end of O_TMPFILE open(). Optional, equivalent to |
497 | atomically creating, opening and unlinking a file in given directory. | |
498 | ||
cc7d1f8f PE |
499 | The Address Space Object |
500 | ======================== | |
501 | ||
341546f5 N |
502 | The address space object is used to group and manage pages in the page |
503 | cache. It can be used to keep track of the pages in a file (or | |
504 | anything else) and also track the mapping of sections of the file into | |
505 | process address spaces. | |
506 | ||
507 | There are a number of distinct yet related services that an | |
508 | address-space can provide. These include communicating memory | |
509 | pressure, page lookup by address, and keeping track of pages tagged as | |
510 | Dirty or Writeback. | |
511 | ||
a9e102b6 | 512 | The first can be used independently to the others. The VM can try to |
341546f5 N |
513 | either write dirty pages in order to clean them, or release clean |
514 | pages in order to reuse them. To do this it can call the ->writepage | |
515 | method on dirty pages, and ->releasepage on clean pages with | |
516 | PagePrivate set. Clean pages without PagePrivate and with no external | |
517 | references will be released without notice being given to the | |
518 | address_space. | |
519 | ||
a9e102b6 | 520 | To achieve this functionality, pages need to be placed on an LRU with |
341546f5 N |
521 | lru_cache_add and mark_page_active needs to be called whenever the |
522 | page is used. | |
523 | ||
524 | Pages are normally kept in a radix tree index by ->index. This tree | |
525 | maintains information about the PG_Dirty and PG_Writeback status of | |
526 | each page, so that pages with either of these flags can be found | |
527 | quickly. | |
528 | ||
529 | The Dirty tag is primarily used by mpage_writepages - the default | |
530 | ->writepages method. It uses the tag to find dirty pages to call | |
531 | ->writepage on. If mpage_writepages is not used (i.e. the address | |
a9e102b6 | 532 | provides its own ->writepages) , the PAGECACHE_TAG_DIRTY tag is |
341546f5 N |
533 | almost unused. write_inode_now and sync_inode do use it (through |
534 | __sync_single_inode) to check if ->writepages has been successful in | |
535 | writing out the whole address_space. | |
536 | ||
537 | The Writeback tag is used by filemap*wait* and sync_page* functions, | |
94004ed7 | 538 | via filemap_fdatawait_range, to wait for all writeback to |
341546f5 | 539 | complete. While waiting ->sync_page (if defined) will be called on |
a9e102b6 | 540 | each page that is found to require writeback. |
341546f5 N |
541 | |
542 | An address_space handler may attach extra information to a page, | |
543 | typically using the 'private' field in the 'struct page'. If such | |
544 | information is attached, the PG_Private flag should be set. This will | |
a9e102b6 | 545 | cause various VM routines to make extra calls into the address_space |
341546f5 N |
546 | handler to deal with that data. |
547 | ||
548 | An address space acts as an intermediate between storage and | |
549 | application. Data is read into the address space a whole page at a | |
550 | time, and provided to the application either by copying of the page, | |
551 | or by memory-mapping the page. | |
552 | Data is written into the address space by the application, and then | |
553 | written-back to storage typically in whole pages, however the | |
a9e102b6 | 554 | address_space has finer control of write sizes. |
341546f5 N |
555 | |
556 | The read process essentially only requires 'readpage'. The write | |
4e02ed4b | 557 | process is more complicated and uses write_begin/write_end or |
341546f5 N |
558 | set_page_dirty to write data into the address_space, and writepage, |
559 | sync_page, and writepages to writeback data to storage. | |
560 | ||
561 | Adding and removing pages to/from an address_space is protected by the | |
562 | inode's i_mutex. | |
563 | ||
564 | When data is written to a page, the PG_Dirty flag should be set. It | |
565 | typically remains set until writepage asks for it to be written. This | |
566 | should clear PG_Dirty and set PG_Writeback. It can be actually | |
567 | written at any point after PG_Dirty is clear. Once it is known to be | |
568 | safe, PG_Writeback is cleared. | |
569 | ||
570 | Writeback makes use of a writeback_control structure... | |
5ea626aa PE |
571 | |
572 | struct address_space_operations | |
cc7d1f8f | 573 | ------------------------------- |
5ea626aa PE |
574 | |
575 | This describes how the VFS can manipulate mapping of a file to page cache in | |
d47992f8 | 576 | your filesystem. The following members are defined: |
5ea626aa PE |
577 | |
578 | struct address_space_operations { | |
579 | int (*writepage)(struct page *page, struct writeback_control *wbc); | |
580 | int (*readpage)(struct file *, struct page *); | |
5ea626aa PE |
581 | int (*writepages)(struct address_space *, struct writeback_control *); |
582 | int (*set_page_dirty)(struct page *page); | |
583 | int (*readpages)(struct file *filp, struct address_space *mapping, | |
584 | struct list_head *pages, unsigned nr_pages); | |
afddba49 NP |
585 | int (*write_begin)(struct file *, struct address_space *mapping, |
586 | loff_t pos, unsigned len, unsigned flags, | |
587 | struct page **pagep, void **fsdata); | |
588 | int (*write_end)(struct file *, struct address_space *mapping, | |
589 | loff_t pos, unsigned len, unsigned copied, | |
590 | struct page *page, void *fsdata); | |
5ea626aa | 591 | sector_t (*bmap)(struct address_space *, sector_t); |
d47992f8 | 592 | void (*invalidatepage) (struct page *, unsigned int, unsigned int); |
5ea626aa | 593 | int (*releasepage) (struct page *, int); |
6072d13c | 594 | void (*freepage)(struct page *); |
22c6186e | 595 | ssize_t (*direct_IO)(struct kiocb *, struct iov_iter *iter, loff_t offset); |
341546f5 N |
596 | /* migrate the contents of a page to the specified target */ |
597 | int (*migratepage) (struct page *, struct page *); | |
422b14c2 | 598 | int (*launder_page) (struct page *); |
c186afb4 | 599 | int (*is_partially_uptodate) (struct page *, unsigned long, |
26c0c5bf | 600 | unsigned long); |
543cc115 | 601 | void (*is_dirty_writeback) (struct page *, bool *, bool *); |
25718736 | 602 | int (*error_remove_page) (struct mapping *mapping, struct page *page); |
62c230bc MG |
603 | int (*swap_activate)(struct file *); |
604 | int (*swap_deactivate)(struct file *); | |
5ea626aa PE |
605 | }; |
606 | ||
341546f5 | 607 | writepage: called by the VM to write a dirty page to backing store. |
a9e102b6 | 608 | This may happen for data integrity reasons (i.e. 'sync'), or |
341546f5 N |
609 | to free up memory (flush). The difference can be seen in |
610 | wbc->sync_mode. | |
611 | The PG_Dirty flag has been cleared and PageLocked is true. | |
612 | writepage should start writeout, should set PG_Writeback, | |
613 | and should make sure the page is unlocked, either synchronously | |
614 | or asynchronously when the write operation completes. | |
615 | ||
616 | If wbc->sync_mode is WB_SYNC_NONE, ->writepage doesn't have to | |
a9e102b6 N |
617 | try too hard if there are problems, and may choose to write out |
618 | other pages from the mapping if that is easier (e.g. due to | |
619 | internal dependencies). If it chooses not to start writeout, it | |
620 | should return AOP_WRITEPAGE_ACTIVATE so that the VM will not keep | |
341546f5 N |
621 | calling ->writepage on that page. |
622 | ||
623 | See the file "Locking" for more details. | |
5ea626aa PE |
624 | |
625 | readpage: called by the VM to read a page from backing store. | |
341546f5 N |
626 | The page will be Locked when readpage is called, and should be |
627 | unlocked and marked uptodate once the read completes. | |
628 | If ->readpage discovers that it needs to unlock the page for | |
629 | some reason, it can do so, and then return AOP_TRUNCATED_PAGE. | |
a9e102b6 | 630 | In this case, the page will be relocated, relocked and if |
341546f5 | 631 | that all succeeds, ->readpage will be called again. |
5ea626aa | 632 | |
5ea626aa | 633 | writepages: called by the VM to write out pages associated with the |
a9e102b6 N |
634 | address_space object. If wbc->sync_mode is WBC_SYNC_ALL, then |
635 | the writeback_control will specify a range of pages that must be | |
636 | written out. If it is WBC_SYNC_NONE, then a nr_to_write is given | |
341546f5 N |
637 | and that many pages should be written if possible. |
638 | If no ->writepages is given, then mpage_writepages is used | |
a9e102b6 | 639 | instead. This will choose pages from the address space that are |
341546f5 | 640 | tagged as DIRTY and will pass them to ->writepage. |
5ea626aa PE |
641 | |
642 | set_page_dirty: called by the VM to set a page dirty. | |
341546f5 N |
643 | This is particularly needed if an address space attaches |
644 | private data to a page, and that data needs to be updated when | |
645 | a page is dirtied. This is called, for example, when a memory | |
646 | mapped page gets modified. | |
647 | If defined, it should set the PageDirty flag, and the | |
648 | PAGECACHE_TAG_DIRTY tag in the radix tree. | |
5ea626aa PE |
649 | |
650 | readpages: called by the VM to read pages associated with the address_space | |
341546f5 N |
651 | object. This is essentially just a vector version of |
652 | readpage. Instead of just one page, several pages are | |
653 | requested. | |
a9e102b6 | 654 | readpages is only used for read-ahead, so read errors are |
341546f5 | 655 | ignored. If anything goes wrong, feel free to give up. |
1da177e4 | 656 | |
4e02ed4b | 657 | write_begin: |
afddba49 NP |
658 | Called by the generic buffered write code to ask the filesystem to |
659 | prepare to write len bytes at the given offset in the file. The | |
660 | address_space should check that the write will be able to complete, | |
661 | by allocating space if necessary and doing any other internal | |
662 | housekeeping. If the write will update parts of any basic-blocks on | |
663 | storage, then those blocks should be pre-read (if they haven't been | |
664 | read already) so that the updated blocks can be written out properly. | |
665 | ||
666 | The filesystem must return the locked pagecache page for the specified | |
667 | offset, in *pagep, for the caller to write into. | |
668 | ||
4e02ed4b NP |
669 | It must be able to cope with short writes (where the length passed to |
670 | write_begin is greater than the number of bytes copied into the page). | |
671 | ||
afddba49 NP |
672 | flags is a field for AOP_FLAG_xxx flags, described in |
673 | include/linux/fs.h. | |
674 | ||
675 | A void * may be returned in fsdata, which then gets passed into | |
676 | write_end. | |
677 | ||
678 | Returns 0 on success; < 0 on failure (which is the error code), in | |
679 | which case write_end is not called. | |
680 | ||
681 | write_end: After a successful write_begin, and data copy, write_end must | |
682 | be called. len is the original len passed to write_begin, and copied | |
683 | is the amount that was able to be copied (copied == len is always true | |
684 | if write_begin was called with the AOP_FLAG_UNINTERRUPTIBLE flag). | |
685 | ||
686 | The filesystem must take care of unlocking the page and releasing it | |
687 | refcount, and updating i_size. | |
688 | ||
689 | Returns < 0 on failure, otherwise the number of bytes (<= 'copied') | |
690 | that were able to be copied into pagecache. | |
691 | ||
5ea626aa | 692 | bmap: called by the VFS to map a logical block offset within object to |
a9e102b6 | 693 | physical block number. This method is used by the FIBMAP |
341546f5 | 694 | ioctl and for working with swap-files. To be able to swap to |
a9e102b6 | 695 | a file, the file must have a stable mapping to a block |
341546f5 N |
696 | device. The swap system does not go through the filesystem |
697 | but instead uses bmap to find out where the blocks in the file | |
698 | are and uses those addresses directly. | |
699 | ||
4aa7c634 MS |
700 | dentry_open: *WARNING: probably going away soon, do not use!* This is an |
701 | alternative to f_op->open(), the difference is that this method may open | |
702 | a file not necessarily originating from the same filesystem as the one | |
703 | i_op->open() was called on. It may be useful for stacking filesystems | |
704 | which want to allow native I/O directly on underlying files. | |
705 | ||
341546f5 N |
706 | |
707 | invalidatepage: If a page has PagePrivate set, then invalidatepage | |
708 | will be called when part or all of the page is to be removed | |
a9e102b6 | 709 | from the address space. This generally corresponds to either a |
d47992f8 LC |
710 | truncation, punch hole or a complete invalidation of the address |
711 | space (in the latter case 'offset' will always be 0 and 'length' | |
712 | will be PAGE_CACHE_SIZE). Any private data associated with the page | |
713 | should be updated to reflect this truncation. If offset is 0 and | |
714 | length is PAGE_CACHE_SIZE, then the private data should be released, | |
715 | because the page must be able to be completely discarded. This may | |
716 | be done by calling the ->releasepage function, but in this case the | |
717 | release MUST succeed. | |
341546f5 N |
718 | |
719 | releasepage: releasepage is called on PagePrivate pages to indicate | |
720 | that the page should be freed if possible. ->releasepage | |
721 | should remove any private data from the page and clear the | |
4fe65cab AM |
722 | PagePrivate flag. If releasepage() fails for some reason, it must |
723 | indicate failure with a 0 return value. | |
724 | releasepage() is used in two distinct though related cases. The | |
725 | first is when the VM finds a clean page with no active users and | |
341546f5 N |
726 | wants to make it a free page. If ->releasepage succeeds, the |
727 | page will be removed from the address_space and become free. | |
728 | ||
bc5b1d55 | 729 | The second case is when a request has been made to invalidate |
341546f5 N |
730 | some or all pages in an address_space. This can happen |
731 | through the fadvice(POSIX_FADV_DONTNEED) system call or by the | |
732 | filesystem explicitly requesting it as nfs and 9fs do (when | |
733 | they believe the cache may be out of date with storage) by | |
734 | calling invalidate_inode_pages2(). | |
735 | If the filesystem makes such a call, and needs to be certain | |
a9e102b6 | 736 | that all pages are invalidated, then its releasepage will |
341546f5 N |
737 | need to ensure this. Possibly it can clear the PageUptodate |
738 | bit if it cannot free private data yet. | |
739 | ||
6072d13c LT |
740 | freepage: freepage is called once the page is no longer visible in |
741 | the page cache in order to allow the cleanup of any private | |
742 | data. Since it may be called by the memory reclaimer, it | |
743 | should not assume that the original address_space mapping still | |
744 | exists, and it should not block. | |
745 | ||
341546f5 N |
746 | direct_IO: called by the generic read/write routines to perform |
747 | direct_IO - that is IO requests which bypass the page cache | |
a9e102b6 | 748 | and transfer data directly between the storage and the |
341546f5 | 749 | application's address space. |
5ea626aa | 750 | |
341546f5 N |
751 | migrate_page: This is used to compact the physical memory usage. |
752 | If the VM wants to relocate a page (maybe off a memory card | |
753 | that is signalling imminent failure) it will pass a new page | |
754 | and an old page to this function. migrate_page should | |
755 | transfer any private data across and update any references | |
756 | that it has to the page. | |
5ea626aa | 757 | |
422b14c2 BP |
758 | launder_page: Called before freeing a page - it writes back the dirty page. To |
759 | prevent redirtying the page, it is kept locked during the whole | |
760 | operation. | |
761 | ||
26c0c5bf MG |
762 | is_partially_uptodate: Called by the VM when reading a file through the |
763 | pagecache when the underlying blocksize != pagesize. If the required | |
764 | block is up to date then the read can complete without needing the IO | |
765 | to bring the whole page up to date. | |
766 | ||
543cc115 MG |
767 | is_dirty_writeback: Called by the VM when attempting to reclaim a page. |
768 | The VM uses dirty and writeback information to determine if it needs | |
769 | to stall to allow flushers a chance to complete some IO. Ordinarily | |
770 | it can use PageDirty and PageWriteback but some filesystems have | |
771 | more complex state (unstable pages in NFS prevent reclaim) or | |
c290ea01 | 772 | do not set those flags due to locking problems. This callback |
543cc115 MG |
773 | allows a filesystem to indicate to the VM if a page should be |
774 | treated as dirty or writeback for the purposes of stalling. | |
775 | ||
25718736 AK |
776 | error_remove_page: normally set to generic_error_remove_page if truncation |
777 | is ok for this address space. Used for memory failure handling. | |
778 | Setting this implies you deal with pages going away under you, | |
779 | unless you have them locked or reference counts increased. | |
780 | ||
62c230bc MG |
781 | swap_activate: Called when swapon is used on a file to allocate |
782 | space if necessary and pin the block lookup information in | |
783 | memory. A return value of zero indicates success, | |
784 | in which case this file can be used to back swapspace. The | |
785 | swapspace operations will be proxied to this address space's | |
786 | ->swap_{out,in} methods. | |
787 | ||
788 | swap_deactivate: Called during swapoff on files where swap_activate | |
789 | was successful. | |
790 | ||
25718736 | 791 | |
cc7d1f8f PE |
792 | The File Object |
793 | =============== | |
794 | ||
795 | A file object represents a file opened by a process. | |
796 | ||
797 | ||
5ea626aa | 798 | struct file_operations |
cc7d1f8f | 799 | ---------------------- |
1da177e4 LT |
800 | |
801 | This describes how the VFS can manipulate an open file. As of kernel | |
0d03943c | 802 | 4.1, the following members are defined: |
1da177e4 LT |
803 | |
804 | struct file_operations { | |
422b14c2 | 805 | struct module *owner; |
1da177e4 | 806 | loff_t (*llseek) (struct file *, loff_t, int); |
5ea626aa | 807 | ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); |
5ea626aa | 808 | ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); |
293bc982 AV |
809 | ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); |
810 | ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); | |
2233f31a | 811 | int (*iterate) (struct file *, struct dir_context *); |
1da177e4 | 812 | unsigned int (*poll) (struct file *, struct poll_table_struct *); |
5ea626aa PE |
813 | long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); |
814 | long (*compat_ioctl) (struct file *, unsigned int, unsigned long); | |
1da177e4 | 815 | int (*mmap) (struct file *, struct vm_area_struct *); |
0d03943c | 816 | int (*mremap)(struct file *, struct vm_area_struct *); |
1da177e4 | 817 | int (*open) (struct inode *, struct file *); |
0d03943c | 818 | int (*flush) (struct file *, fl_owner_t id); |
1da177e4 | 819 | int (*release) (struct inode *, struct file *); |
02c24a82 | 820 | int (*fsync) (struct file *, loff_t, loff_t, int datasync); |
5ea626aa PE |
821 | int (*aio_fsync) (struct kiocb *, int datasync); |
822 | int (*fasync) (int, struct file *, int); | |
1da177e4 | 823 | int (*lock) (struct file *, int, struct file_lock *); |
5ea626aa PE |
824 | ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int); |
825 | unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned long, unsigned long, unsigned long); | |
826 | int (*check_flags)(int); | |
5ea626aa | 827 | int (*flock) (struct file *, int, struct file_lock *); |
0d03943c TB |
828 | ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *, size_t, unsigned int); |
829 | ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *, size_t, unsigned int); | |
830 | int (*setlease)(struct file *, long, struct file_lock **, void **); | |
831 | long (*fallocate)(struct file *file, int mode, loff_t offset, | |
832 | loff_t len); | |
a3816ab0 | 833 | void (*show_fdinfo)(struct seq_file *m, struct file *f); |
0d03943c TB |
834 | #ifndef CONFIG_MMU |
835 | unsigned (*mmap_capabilities)(struct file *); | |
836 | #endif | |
1da177e4 LT |
837 | }; |
838 | ||
839 | Again, all methods are called without any locks being held, unless | |
840 | otherwise noted. | |
841 | ||
842 | llseek: called when the VFS needs to move the file position index | |
843 | ||
844 | read: called by read(2) and related system calls | |
845 | ||
293bc982 | 846 | read_iter: possibly asynchronous read with iov_iter as destination |
5ea626aa | 847 | |
1da177e4 LT |
848 | write: called by write(2) and related system calls |
849 | ||
293bc982 | 850 | write_iter: possibly asynchronous write with iov_iter as source |
5ea626aa | 851 | |
2233f31a | 852 | iterate: called when the VFS needs to read the directory contents |
1da177e4 LT |
853 | |
854 | poll: called by the VFS when a process wants to check if there is | |
855 | activity on this file and (optionally) go to sleep until there | |
856 | is activity. Called by the select(2) and poll(2) system calls | |
857 | ||
b19dd42f | 858 | unlocked_ioctl: called by the ioctl(2) system call. |
5ea626aa PE |
859 | |
860 | compat_ioctl: called by the ioctl(2) system call when 32 bit system calls | |
861 | are used on 64 bit kernels. | |
862 | ||
1da177e4 LT |
863 | mmap: called by the mmap(2) system call |
864 | ||
865 | open: called by the VFS when an inode should be opened. When the VFS | |
5ea626aa PE |
866 | opens a file, it creates a new "struct file". It then calls the |
867 | open method for the newly allocated file structure. You might | |
868 | think that the open method really belongs in | |
869 | "struct inode_operations", and you may be right. I think it's | |
870 | done the way it is because it makes filesystems simpler to | |
871 | implement. The open() method is a good place to initialize the | |
872 | "private_data" member in the file structure if you want to point | |
873 | to a device structure | |
874 | ||
875 | flush: called by the close(2) system call to flush a file | |
1da177e4 LT |
876 | |
877 | release: called when the last reference to an open file is closed | |
878 | ||
879 | fsync: called by the fsync(2) system call | |
880 | ||
881 | fasync: called by the fcntl(2) system call when asynchronous | |
882 | (non-blocking) mode is enabled for a file | |
883 | ||
5ea626aa PE |
884 | lock: called by the fcntl(2) system call for F_GETLK, F_SETLK, and F_SETLKW |
885 | commands | |
886 | ||
5ea626aa PE |
887 | get_unmapped_area: called by the mmap(2) system call |
888 | ||
889 | check_flags: called by the fcntl(2) system call for F_SETFL command | |
890 | ||
5ea626aa PE |
891 | flock: called by the flock(2) system call |
892 | ||
d1195c51 PE |
893 | splice_write: called by the VFS to splice data from a pipe to a file. This |
894 | method is used by the splice(2) system call | |
895 | ||
896 | splice_read: called by the VFS to splice data from file to a pipe. This | |
897 | method is used by the splice(2) system call | |
898 | ||
f82b4b67 JL |
899 | setlease: called by the VFS to set or release a file lock lease. setlease |
900 | implementations should call generic_setlease to record or remove | |
901 | the lease in the inode after setting it. | |
17cf28af HD |
902 | |
903 | fallocate: called by the VFS to preallocate blocks or punch a hole. | |
904 | ||
1da177e4 LT |
905 | Note that the file operations are implemented by the specific |
906 | filesystem in which the inode resides. When opening a device node | |
907 | (character or block special) most filesystems will call special | |
908 | support routines in the VFS which will locate the required device | |
909 | driver information. These support routines replace the filesystem file | |
910 | operations with those for the device driver, and then proceed to call | |
911 | the new open() method for the file. This is how opening a device file | |
912 | in the filesystem eventually ends up calling the device driver open() | |
5ea626aa | 913 | method. |
1da177e4 LT |
914 | |
915 | ||
5ea626aa PE |
916 | Directory Entry Cache (dcache) |
917 | ============================== | |
918 | ||
1da177e4 LT |
919 | |
920 | struct dentry_operations | |
5ea626aa | 921 | ------------------------ |
1da177e4 LT |
922 | |
923 | This describes how a filesystem can overload the standard dentry | |
924 | operations. Dentries and the dcache are the domain of the VFS and the | |
925 | individual filesystem implementations. Device drivers have no business | |
926 | here. These methods may be set to NULL, as they are either optional or | |
c23fbb6b | 927 | the VFS uses a default. As of kernel 2.6.22, the following members are |
1da177e4 LT |
928 | defined: |
929 | ||
930 | struct dentry_operations { | |
0b728e19 | 931 | int (*d_revalidate)(struct dentry *, unsigned int); |
ecf3d1f1 | 932 | int (*d_weak_revalidate)(struct dentry *, unsigned int); |
da53be12 LT |
933 | int (*d_hash)(const struct dentry *, struct qstr *); |
934 | int (*d_compare)(const struct dentry *, const struct dentry *, | |
621e155a | 935 | unsigned int, const char *, const struct qstr *); |
fe15ce44 | 936 | int (*d_delete)(const struct dentry *); |
1da177e4 LT |
937 | void (*d_release)(struct dentry *); |
938 | void (*d_iput)(struct dentry *, struct inode *); | |
c23fbb6b | 939 | char *(*d_dname)(struct dentry *, char *, int); |
9875cf80 | 940 | struct vfsmount *(*d_automount)(struct path *); |
1aed3e42 | 941 | int (*d_manage)(struct dentry *, bool); |
1da177e4 LT |
942 | }; |
943 | ||
944 | d_revalidate: called when the VFS needs to revalidate a dentry. This | |
945 | is called whenever a name look-up finds a dentry in the | |
ecf3d1f1 JL |
946 | dcache. Most local filesystems leave this as NULL, because all their |
947 | dentries in the dcache are valid. Network filesystems are different | |
948 | since things can change on the server without the client necessarily | |
949 | being aware of it. | |
950 | ||
951 | This function should return a positive value if the dentry is still | |
952 | valid, and zero or a negative error code if it isn't. | |
1da177e4 | 953 | |
0b728e19 | 954 | d_revalidate may be called in rcu-walk mode (flags & LOOKUP_RCU). |
34286d66 NP |
955 | If in rcu-walk mode, the filesystem must revalidate the dentry without |
956 | blocking or storing to the dentry, d_parent and d_inode should not be | |
0b728e19 AV |
957 | used without care (because they can change and, in d_inode case, even |
958 | become NULL under us). | |
34286d66 NP |
959 | |
960 | If a situation is encountered that rcu-walk cannot handle, return | |
961 | -ECHILD and it will be called again in ref-walk mode. | |
962 | ||
ecf3d1f1 JL |
963 | d_weak_revalidate: called when the VFS needs to revalidate a "jumped" dentry. |
964 | This is called when a path-walk ends at dentry that was not acquired by | |
965 | doing a lookup in the parent directory. This includes "/", "." and "..", | |
966 | as well as procfs-style symlinks and mountpoint traversal. | |
967 | ||
968 | In this case, we are less concerned with whether the dentry is still | |
969 | fully correct, but rather that the inode is still valid. As with | |
970 | d_revalidate, most local filesystems will set this to NULL since their | |
971 | dcache entries are always valid. | |
972 | ||
973 | This function has the same return code semantics as d_revalidate. | |
974 | ||
975 | d_weak_revalidate is only called after leaving rcu-walk mode. | |
976 | ||
621e155a NP |
977 | d_hash: called when the VFS adds a dentry to the hash table. The first |
978 | dentry passed to d_hash is the parent directory that the name is | |
da53be12 | 979 | to be hashed into. |
b1e6a015 NP |
980 | |
981 | Same locking and synchronisation rules as d_compare regarding | |
982 | what is safe to dereference etc. | |
1da177e4 | 983 | |
621e155a NP |
984 | d_compare: called to compare a dentry name with a given name. The first |
985 | dentry is the parent of the dentry to be compared, the second is | |
da53be12 LT |
986 | the child dentry. len and name string are properties of the dentry |
987 | to be compared. qstr is the name to compare it with. | |
621e155a NP |
988 | |
989 | Must be constant and idempotent, and should not take locks if | |
da53be12 LT |
990 | possible, and should not or store into the dentry. |
991 | Should not dereference pointers outside the dentry without | |
621e155a NP |
992 | lots of care (eg. d_parent, d_inode, d_name should not be used). |
993 | ||
994 | However, our vfsmount is pinned, and RCU held, so the dentries and | |
995 | inodes won't disappear, neither will our sb or filesystem module. | |
da53be12 | 996 | ->d_sb may be used. |
621e155a NP |
997 | |
998 | It is a tricky calling convention because it needs to be called under | |
999 | "rcu-walk", ie. without any locks or references on things. | |
1da177e4 | 1000 | |
fe15ce44 NP |
1001 | d_delete: called when the last reference to a dentry is dropped and the |
1002 | dcache is deciding whether or not to cache it. Return 1 to delete | |
1003 | immediately, or 0 to cache the dentry. Default is NULL which means to | |
1004 | always cache a reachable dentry. d_delete must be constant and | |
1005 | idempotent. | |
1da177e4 LT |
1006 | |
1007 | d_release: called when a dentry is really deallocated | |
1008 | ||
1009 | d_iput: called when a dentry loses its inode (just prior to its | |
1010 | being deallocated). The default when this is NULL is that the | |
1011 | VFS calls iput(). If you define this method, you must call | |
1012 | iput() yourself | |
1013 | ||
c23fbb6b | 1014 | d_dname: called when the pathname of a dentry should be generated. |
d9195881 | 1015 | Useful for some pseudo filesystems (sockfs, pipefs, ...) to delay |
c23fbb6b | 1016 | pathname generation. (Instead of doing it when dentry is created, |
d9195881 | 1017 | it's done only when the path is needed.). Real filesystems probably |
c23fbb6b ED |
1018 | dont want to use it, because their dentries are present in global |
1019 | dcache hash, so their hash should be an invariant. As no lock is | |
1020 | held, d_dname() should not try to modify the dentry itself, unless | |
1021 | appropriate SMP safety is used. CAUTION : d_path() logic is quite | |
1022 | tricky. The correct way to return for example "Hello" is to put it | |
1023 | at the end of the buffer, and returns a pointer to the first char. | |
1024 | dynamic_dname() helper function is provided to take care of this. | |
1025 | ||
9875cf80 | 1026 | d_automount: called when an automount dentry is to be traversed (optional). |
ea5b778a DH |
1027 | This should create a new VFS mount record and return the record to the |
1028 | caller. The caller is supplied with a path parameter giving the | |
1029 | automount directory to describe the automount target and the parent | |
1030 | VFS mount record to provide inheritable mount parameters. NULL should | |
1031 | be returned if someone else managed to make the automount first. If | |
1032 | the vfsmount creation failed, then an error code should be returned. | |
1033 | If -EISDIR is returned, then the directory will be treated as an | |
1034 | ordinary directory and returned to pathwalk to continue walking. | |
1035 | ||
1036 | If a vfsmount is returned, the caller will attempt to mount it on the | |
1037 | mountpoint and will remove the vfsmount from its expiration list in | |
1038 | the case of failure. The vfsmount should be returned with 2 refs on | |
1039 | it to prevent automatic expiration - the caller will clean up the | |
1040 | additional ref. | |
9875cf80 DH |
1041 | |
1042 | This function is only used if DCACHE_NEED_AUTOMOUNT is set on the | |
1043 | dentry. This is set by __d_instantiate() if S_AUTOMOUNT is set on the | |
1044 | inode being added. | |
1045 | ||
cc53ce53 DH |
1046 | d_manage: called to allow the filesystem to manage the transition from a |
1047 | dentry (optional). This allows autofs, for example, to hold up clients | |
1048 | waiting to explore behind a 'mountpoint' whilst letting the daemon go | |
1049 | past and construct the subtree there. 0 should be returned to let the | |
1050 | calling process continue. -EISDIR can be returned to tell pathwalk to | |
1051 | use this directory as an ordinary directory and to ignore anything | |
1052 | mounted on it and not to check the automount flag. Any other error | |
1053 | code will abort pathwalk completely. | |
1054 | ||
ab90911f DH |
1055 | If the 'rcu_walk' parameter is true, then the caller is doing a |
1056 | pathwalk in RCU-walk mode. Sleeping is not permitted in this mode, | |
40e47125 | 1057 | and the caller can be asked to leave it and call again by returning |
b8faf035 N |
1058 | -ECHILD. -EISDIR may also be returned to tell pathwalk to |
1059 | ignore d_automount or any mounts. | |
ab90911f | 1060 | |
cc53ce53 DH |
1061 | This function is only used if DCACHE_MANAGE_TRANSIT is set on the |
1062 | dentry being transited from. | |
1063 | ||
c23fbb6b ED |
1064 | Example : |
1065 | ||
1066 | static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen) | |
1067 | { | |
1068 | return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]", | |
1069 | dentry->d_inode->i_ino); | |
1070 | } | |
1071 | ||
1da177e4 LT |
1072 | Each dentry has a pointer to its parent dentry, as well as a hash list |
1073 | of child dentries. Child dentries are basically like files in a | |
1074 | directory. | |
1075 | ||
5ea626aa | 1076 | |
cc7d1f8f | 1077 | Directory Entry Cache API |
1da177e4 LT |
1078 | -------------------------- |
1079 | ||
1080 | There are a number of functions defined which permit a filesystem to | |
1081 | manipulate dentries: | |
1082 | ||
1083 | dget: open a new handle for an existing dentry (this just increments | |
1084 | the usage count) | |
1085 | ||
1086 | dput: close a handle for a dentry (decrements the usage count). If | |
fe15ce44 NP |
1087 | the usage count drops to 0, and the dentry is still in its |
1088 | parent's hash, the "d_delete" method is called to check whether | |
1089 | it should be cached. If it should not be cached, or if the dentry | |
1090 | is not hashed, it is deleted. Otherwise cached dentries are put | |
1091 | into an LRU list to be reclaimed on memory shortage. | |
1da177e4 LT |
1092 | |
1093 | d_drop: this unhashes a dentry from its parents hash list. A | |
5ea626aa | 1094 | subsequent call to dput() will deallocate the dentry if its |
1da177e4 LT |
1095 | usage count drops to 0 |
1096 | ||
1097 | d_delete: delete a dentry. If there are no other open references to | |
1098 | the dentry then the dentry is turned into a negative dentry | |
1099 | (the d_iput() method is called). If there are other | |
1100 | references, then d_drop() is called instead | |
1101 | ||
1102 | d_add: add a dentry to its parents hash list and then calls | |
1103 | d_instantiate() | |
1104 | ||
1105 | d_instantiate: add a dentry to the alias hash list for the inode and | |
1106 | updates the "d_inode" member. The "i_count" member in the | |
1107 | inode structure should be set/incremented. If the inode | |
1108 | pointer is NULL, the dentry is called a "negative | |
1109 | dentry". This function is commonly called when an inode is | |
1110 | created for an existing negative dentry | |
1111 | ||
1112 | d_lookup: look up a dentry given its parent and path name component | |
1113 | It looks up the child of that given name from the dcache | |
1114 | hash table. If it is found, the reference count is incremented | |
be42c4c4 | 1115 | and the dentry is returned. The caller must use dput() |
1da177e4 LT |
1116 | to free the dentry when it finishes using it. |
1117 | ||
f84e3f52 MS |
1118 | Mount Options |
1119 | ============= | |
1120 | ||
1121 | Parsing options | |
1122 | --------------- | |
1123 | ||
1124 | On mount and remount the filesystem is passed a string containing a | |
1125 | comma separated list of mount options. The options can have either of | |
1126 | these forms: | |
1127 | ||
1128 | option | |
1129 | option=value | |
1130 | ||
1131 | The <linux/parser.h> header defines an API that helps parse these | |
1132 | options. There are plenty of examples on how to use it in existing | |
1133 | filesystems. | |
1134 | ||
1135 | Showing options | |
1136 | --------------- | |
1137 | ||
1138 | If a filesystem accepts mount options, it must define show_options() | |
1139 | to show all the currently active options. The rules are: | |
1140 | ||
1141 | - options MUST be shown which are not default or their values differ | |
1142 | from the default | |
1143 | ||
1144 | - options MAY be shown which are enabled by default or have their | |
1145 | default value | |
1146 | ||
1147 | Options used only internally between a mount helper and the kernel | |
1148 | (such as file descriptors), or which only have an effect during the | |
1149 | mounting (such as ones controlling the creation of a journal) are exempt | |
1150 | from the above rules. | |
1151 | ||
1152 | The underlying reason for the above rules is to make sure, that a | |
1153 | mount can be accurately replicated (e.g. umounting and mounting again) | |
1154 | based on the information found in /proc/mounts. | |
1155 | ||
1156 | A simple method of saving options at mount/remount time and showing | |
1157 | them is provided with the save_mount_options() and | |
1158 | generic_show_options() helper functions. Please note, that using | |
1159 | these may have drawbacks. For more info see header comments for these | |
1160 | functions in fs/namespace.c. | |
cc7d1f8f PE |
1161 | |
1162 | Resources | |
1163 | ========= | |
1164 | ||
1165 | (Note some of these resources are not up-to-date with the latest kernel | |
1166 | version.) | |
1167 | ||
1168 | Creating Linux virtual filesystems. 2002 | |
1169 | <http://lwn.net/Articles/13325/> | |
1170 | ||
1171 | The Linux Virtual File-system Layer by Neil Brown. 1999 | |
1172 | <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html> | |
1173 | ||
1174 | A tour of the Linux VFS by Michael K. Johnson. 1996 | |
1175 | <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html> | |
1176 | ||
1177 | A small trail through the Linux kernel by Andries Brouwer. 2001 | |
1178 | <http://www.win.tue.nl/~aeb/linux/vfs/trail.html> |