diff options
Diffstat (limited to 'Documentation/filesystems')
| -rw-r--r-- | Documentation/filesystems/00-INDEX | 11 | ||||
| -rw-r--r-- | Documentation/filesystems/affs.txt | 59 | ||||
| -rw-r--r-- | Documentation/filesystems/coda.txt | 23 | ||||
| -rw-r--r-- | Documentation/filesystems/fat_cvf.txt | 16 | ||||
| -rw-r--r-- | Documentation/filesystems/hpfs.txt | 2 | ||||
| -rw-r--r-- | Documentation/filesystems/isofs.txt | 9 | ||||
| -rw-r--r-- | Documentation/filesystems/ncpfs.txt | 16 | ||||
| -rw-r--r-- | Documentation/filesystems/romfs.txt | 13 | ||||
| -rw-r--r-- | Documentation/filesystems/vfat.txt | 4 | ||||
| -rw-r--r-- | Documentation/filesystems/vfs.txt | 538 |
10 files changed, 487 insertions, 204 deletions
diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX index 679904d0b..f6b5cbad5 100644 --- a/Documentation/filesystems/00-INDEX +++ b/Documentation/filesystems/00-INDEX @@ -5,25 +5,24 @@ affs.txt coda.txt - description of the CODA filesystem. fat_cvf.txt - - Description of the Compressed Volume Files extension to the FAT - filesystem + - info on the Compressed Volume Files extension to the FAT filesystem hpfs.txt - info and mount options for the OS/2 HPFS. isofs.txt - - info and mount options for the ISO9660 (CDROM) filesystem. + - info and mount options for the ISO 9660 (CDROM) filesystem. ncpfs.txt - info on Novell Netware(tm) filesystem using NCP protocol. ntfs.txt - - info and mount options for the NTFS filesystem (Win NT). + - info and mount options for the NTFS filesystem (Windows NT). romfs.txt - Description of the ROMFS filesystem. smbfs.txt - - info on using filesystems with the SMB protocol (Win 3.11, Win NT) + - info on using filesystems with the SMB protocol (Windows 3.11 and NT) sysv-fs.txt - info on the SystemV/Coherent filesystem. umsdos.txt - info on the umsdos extensions to the msdos filesystem. vfat.txt - - info on using the VFAT filesystem used in Win NT and Win 95 + - info on using the VFAT filesystem used in Windows NT and Windows 95 vfs.txt - Overview of the Virtual File System diff --git a/Documentation/filesystems/affs.txt b/Documentation/filesystems/affs.txt index 85d5a58b1..f63a6e3aa 100644 --- a/Documentation/filesystems/affs.txt +++ b/Documentation/filesystems/affs.txt @@ -1,8 +1,8 @@ -Amiga filesystems Overview -========================== +Overview of Amiga Filesystems +============================= Not all varieties of the Amiga filesystems are supported for reading and -writing. The Amiga currently knows 6 different filesystems: +writing. The Amiga currently knows six different filesystems: DOS\0 The old or original filesystem, not really suited for hard disks and normally not used on them, either. @@ -26,7 +26,7 @@ DOS\5 The Fast File System with directory cache. Supported read only. All of the above filesystems allow block sizes from 512 to 32K bytes. Supported block sizes are: 512, 1024, 2048 and 4096 bytes. Larger blocks -speed up almost everything with the expense of wasted disk space. The speed +speed up almost everything at the expense of wasted disk space. The speed gain above 4K seems not really worth the price, so you don't lose too much here, either. @@ -45,12 +45,13 @@ setgid[=gid] Same as above, but for gid. mode=mode Sets the mode flags to the given (octal) value, regardless of the original permissions. Directories will get an x - permission, if the corresponding r bit is set. + permission if the corresponding r bit is set. This is useful since most of the plain AmigaOS files will map to 600. reserved=num Sets the number of reserved blocks at the start of the - partition to num. Default is 2. + partition to num. You should never need this option. + Default is 2. root=block Sets the block number of the root block. This should never be necessary. @@ -66,16 +67,18 @@ verbose The volume name, file system type and block size will be written to the syslog when the filesystem is mounted. mufs The filesystem is really a muFS, also it doesn't - identify itself as one. This option is neccessary if + identify itself as one. This option is necessary if the filesystem wasn't formatted as muFS, but is used as one. prefix=path Path will be prefixed to every absolute path name of - symbolic links on an AFFS partition. Default = / + symbolic links on an AFFS partition. Default = "/". + (See below.) volume=name When symbolic links with an absolute path are created - on an AFFS partition, volume will be prepended as the + on an AFFS partition, name will be prepended as the volume name. Default = "" (empty string). + (See below.) Handling of the Users/Groups and protection flags ================================================= @@ -92,11 +95,13 @@ The Amiga protection flags RWEDRWEDHSPARWED are handled as follows: - H and P are always retained and ignored under Linux. - - A is always reset when written. + - A is always reset when a file is written to. User id and group id will be used unless set[gu]id are given as mount options. Since most of the Amiga file systems are single user systems -they will be owned by root. +they will be owned by root. The root directory (the mount point) of the +Amiga filesystem will be owned by the user who actually mounts the +filesystem (the root directory doesn't have uid/gid fields). Linux -> Amiga: @@ -111,7 +116,7 @@ The Linux rwxrwxrwx file mode is handled as follows: - All other flags (suid, sgid, ...) are ignored and will not be retained. -Newly created files and directories will get the user and group id +Newly created files and directories will get the user and group ID of the current user and a mode according to the umask. Symbolic links @@ -121,7 +126,7 @@ Although the Amiga and Linux file systems resemble each other, there are some, not always subtle, differences. One of them becomes apparent with symbolic links. While Linux has a file system with exactly one root directory, the Amiga has a separate root directory for each -file system (e.g. partition, floppy disk, ...). With the Amiga, +file system (for example, partition, floppy disk, ...). With the Amiga, these entities are called "volumes". They have symbolic names which can be used to access them. Thus, symbolic links can point to a different volume. AFFS turns the volume name into a directory name @@ -139,12 +144,12 @@ might be "User", "WB" and "Graphics", the mount points /amiga/User, Examples ======== -Command line - mount Archive/Amiga/Workbench3.1.adf /mnt -t affs -o loop,reserved=4 +Command line: + mount Archive/Amiga/Workbench3.1.adf /mnt -t affs -o loop,verbose mount /dev/sda3 /Amiga -t affs -/etc/fstab example - /dev/sdb5 /d/f affs ro +/etc/fstab entry: + /dev/sdb5 /amiga/Workbench affs noauto,user,exec,verbose 0 0 Bugs, Restrictions, Caveats =========================== @@ -159,10 +164,10 @@ can be changed by setting the compile-time option AFFS_NO_TRUNCATE in include/linux/amigaffs.h). Case is ignored by the affs in filename matching, but Linux shells -do care about the case. Example (with /mnt being an affs mounted fs): - rm /mnt/WRONGCASE +do care about the case. Example (with /wb being an affs mounted fs): + rm /wb/WRONGCASE will remove /mnt/wrongcase, but - rm /mnt/WR* + rm /wb/WR* will not since the names are matched by the shell. The block allocation is designed for hard disk partitions. If more @@ -170,14 +175,20 @@ than 1 process writes to a (small) diskette, the blocks are allocated in an ugly way (but the real AFFS doesn't do much better). This is also true when space gets tight. +You cannot execute programs on an OFS (Old File System), since the +program files cannot be memory mapped due to the 488 byte blocks. +For the same reason you cannot mount an image on such a filesystem +via the loopback device. + The bitmap valid flag in the root block may not be accurate when the system crashes while an affs partition is mounted. There's currently -no way to fix this without an Amiga (disk validator) or manually -(who would do this?). Maybe later. +no way to fix a garbled filesystem without an Amiga (disk validator) +or manually (who would do this?). Maybe later. A fsck.affs and mkfs.affs will probably be available in the future. -Until then, you should do - ln -s /bin/true /etc/fs/mkfs.affs +If you mount them on system startup, you may want to tell fsck +that the fs should not be checked (place a '0' in the sixth field +of /etc/fstab). It's not possible to read floppy disks with a normal PC or workstation due to an incompatibility with the Amiga floppy controller. diff --git a/Documentation/filesystems/coda.txt b/Documentation/filesystems/coda.txt index 0c88ce6dc..b198ba4e5 100644 --- a/Documentation/filesystems/coda.txt +++ b/Documentation/filesystems/coda.txt @@ -1,4 +1,3 @@ - NOTE: This is one of the technical documents describing a component of Coda -- this document describes the client kernel-Venus interface. @@ -9,7 +8,7 @@ For user level software needed to run Coda: ftp://ftp.coda.cs.cmu.edu To run Coda you need to get a user level cache manager for the client, -named Venus, as well as tools to manipulate ACL's, to log in etc. The +named Venus, as well as tools to manipulate ACLs, to log in, etc. The client needs to have the Coda filesystem selected in the kernel configuration. @@ -27,7 +26,7 @@ kernel support. v1.0, Nov 9, 1997 This document describes the communication between Venus and kernel - level file system code needed for the operation of the Coda filesys- + level filesystem code needed for the operation of the Coda file sys- tem. This document version is meant to describe the current interface (version 1.0) as well as improvements we envisage. ______________________________________________________________________ @@ -177,7 +176,7 @@ kernel support. The interface between the kernel and Venus is very similar to the BSD VFS interface. Similar functionality is provided, and the format of the parameters and returned data is very similar to the BSD VFS. This - leads to an almost natural environment for implementing a kernel level + leads to an almost natural environment for implementing a kernel-level filesystem driver for Coda in a BSD system. However, other operating systems such as Linux and Windows 95 and NT have virtual filesystem with different interfaces. @@ -359,7 +358,7 @@ kernel support. 33..11.. IImmpplleemmeennttaattiioonn ddeettaaiillss The Unix implementation of this mechanism has been through the - implemenation of a character device associated with Coda. Venus + implementation of a character device associated with Coda. Venus retrieves messages by doing a read on the device, replies are sent with a write and notification is through the select system call on the file descriptor for the device. The process P is kept waiting on an @@ -369,7 +368,7 @@ kernel support. call is used. The DeviceIoControl call is designed to copy buffers from user memory to kernel memory with OPCODES. The sendmsg_to_kernel is issued as a synchronous call, while the getmsg_from_kernel call is - asynchrounous. Windows EventObjects are used for notification of + asynchronous. Windows EventObjects are used for notification of message arrival. The process P is kept waiting on a KernelEvent object in NT and a semaphore in Windows 95. @@ -429,7 +428,7 @@ kernel support. for the Windows environment when these mature. struct CodaCred { - vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, efftve, set, fs uid*/ + vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid*/ vgid_t cr_gid, cr_egid, cr_sgid, cr_fsgid; /* same for groups */ vgid_t cr_groups[NGROUPS]; /* Group membership for caller */ }; @@ -514,7 +513,7 @@ kernel support. Coda specific requests can be made by application through the pioctl interface. The pioctl is implemented as an ordinary ioctl on a - ficticious file /coda/.CONTROL. The pioctl call opens this file, gets + fictitious file /coda/.CONTROL. The pioctl call opens this file, gets a file handle and makes the ioctl call. Finally it closes the file. The kernel involvement in this is limited to providing the facility to @@ -721,7 +720,7 @@ kernel support. access will be granted. It is important to remember that Coda uses ACLs to enforce protection and that ultimately the servers, not the clients enforce the security of the system. The result of this call - will depend on wether a _t_o_k_e_n is held by the user. + will depend on whether a _t_o_k_e_n is held by the user. EErrrroorrss The object may not exist, or the ACL describing the protection may not be accessible. @@ -765,7 +764,7 @@ kernel support. are set by converting the CodaCred to a uid using a macro CRTOUID (this macro is platform dependent). Upon success the VFid and attributes of the file are returned. The Coda FS Driver will normally - instantiate a vnode, inode or filehandle at kernel level for the new + instantiate a vnode, inode or file handle at kernel level for the new object. @@ -780,7 +779,7 @@ kernel support. to return a file descriptor. The trunctate and exclusive options, together with the mode, could simply be part of the mode as it is under Unix. There should be no flags argument; this is used in open - (2) to return a filedescriptor for READ or WRITE mode. + (2) to return a file descriptor for READ or WRITE mode. The attributes of the directory should be returned too, since the size and mtime changed. @@ -1221,7 +1220,7 @@ kernel support. DDeessccrriippttiioonn Ask Venus to update RVM attributes of object VFid. This should be called as part of kernel level fsync type calls. The - result indicates if the synching was successful. + result indicates if the syncing was successful. EErrrroorrss diff --git a/Documentation/filesystems/fat_cvf.txt b/Documentation/filesystems/fat_cvf.txt index ef598932c..7eef569b6 100644 --- a/Documentation/filesystems/fat_cvf.txt +++ b/Documentation/filesystems/fat_cvf.txt @@ -20,7 +20,7 @@ Compressed Volume Files in FAT partitions. Popular CVF software, for example, are Microsoft's Doublespace/Drivespace and Stac's Stacker. Using the CVF-FAT interface, it is possible to load a module that handles all the low-level disk access that has to do with on-the-fly compression -and decompression. All other part of FAT filesystem access is still handled +and decompression. Any other part of FAT filesystem access is still handled by the FAT, MSDOS or VFAT or even UMSDOS driver. CVF access works by redirecting certain low-level routines from the FAT @@ -46,16 +46,16 @@ like compression and decompression silently. might be persuaded to implement it :). CVF-FAT is already prepared for using readpage. -- DOSEMU users attention +- attention, DOSEmu users - You may have to unmount all CVF partitions before running DOSEMU depending - on your configuration. If DOSEMU is configured to use wholedisk or - partition access (this is often the case to let DOSEMU access + You may have to unmount all CVF partitions before running DOSEmu depending + on your configuration. If DOSEmu is configured to use wholedisk or + partition access (this is often the case to let DOSEmu access compressed partitions) there's a risk of destroying your compressed partitions or crashing your system because of confused drivers. Note that it is always safe to redirect the compressed partitions with - lredir or emufs.sys. Refer to the DOSEMU documentation for details. + lredir or emufs.sys. Refer to the DOSEmu documentation for details. 3. Mount options @@ -88,7 +88,7 @@ driver's standard options: ------------------------------------------------------------------------------ Assuming you want to write your own CVF module, you need to write a lot of -interface funtions. Most of them are covered in the kernel documentation +interface functions. Most of them are covered in the kernel documentation you can find on the net, and thus won't be described here. They have been marked with "[...]" :-) Take a look at include/linux/fat_cvf.h. @@ -169,7 +169,7 @@ int register_cvf_format(struct cvf_format*cvf_format); call this function to introduce your CVF format to the FAT/CVF-FAT driver. This is usually done in init_module. Be sure to check the return value. Zero means success, everything else causes a kernel - message printed in the syslog describing the error that occured. + message printed in the syslog describing the error that occurred. Typical errors are: - a module with the same version id is already registered or - too many CVF formats. Hack fs/fat/cvf.c if you need more. diff --git a/Documentation/filesystems/hpfs.txt b/Documentation/filesystems/hpfs.txt index 03e0481bb..a14e81341 100644 --- a/Documentation/filesystems/hpfs.txt +++ b/Documentation/filesystems/hpfs.txt @@ -5,7 +5,7 @@ Mount options are the same as for msdos partitions. uid=nnn All files in the partition will be owned by user id nnn. gid=nnn All files in the partition will be in group nnn. umask=nnn The permission mask (see umask(1)) for the partition. - conv=binary Data is returned exactly as is, with CRLF's. [default] + conv=binary Data is returned exactly as is, with CRLFs. [default] conv=text (Carriage return, line feed) is replaced with newline. conv=auto Chooses, file by file, conv=binary or conv=text (by guessing) diff --git a/Documentation/filesystems/isofs.txt b/Documentation/filesystems/isofs.txt index 2f0a4249e..c186c4050 100644 --- a/Documentation/filesystems/isofs.txt +++ b/Documentation/filesystems/isofs.txt @@ -13,16 +13,17 @@ when using discs encoded using Microsoft's Joliet extensions. utf8 option. utf8 Encode Unicode names in UTF8 format. Default is no. -Mount options that are unique to the isofs filesystem. +Mount options unique to the isofs filesystem. block=512 Set the block size for the disk to 512 bytes block=1024 Set the block size for the disk to 1024 bytes block=2048 Set the block size for the disk to 2048 bytes check=relaxed Matches filenames with different cases check=strict Matches only filenames with the exact same case cruft Try to handle badly formatted CDs. - map=off Do not map non-rockridge filenames to lowercase - map=normal Map rockridge filenames to lowercase + map=off Do not map non-Rock Ridge filenames to lower case + map=normal Map non-Rock Ridge filenames to lower case + map=acorn As map=normal but also apply Acorn extensions if present mode=xxx Sets the permissions on files to xxx nojoliet Ignore Joliet extensions if they are present. - norock Ignore rockridge extensions if they are present. + norock Ignore Rock Ridge extensions if they are present. unhide Show hidden files. diff --git a/Documentation/filesystems/ncpfs.txt b/Documentation/filesystems/ncpfs.txt index 8698dba3f..f12c30c93 100644 --- a/Documentation/filesystems/ncpfs.txt +++ b/Documentation/filesystems/ncpfs.txt @@ -1,12 +1,12 @@ -ncpfs is a filesystem which understands the NCP protocol, designed by the -Novell Corporation for their NetWare(tm) product. NCP is functionally -similar to the NFS used in the tcp/ip community. -To mount a Netware-Filesystem, you need a special mount program, which -can be found in ncpfs package. Homesite for ncpfs is +The ncpfs filesystem understands the NCP protocol, designed by the +Novell Corporation for their NetWare(tm) product. NCP is functionally +similar to the NFS used in the TCP/IP community. +To mount a NetWare filesystem, you need a special mount program, which +can be found in the ncpfs package. The home site for ncpfs is ftp.gwdg.de/pub/linux/misc/ncpfs, but sunsite and its many mirrors will have it as well. Related products are linware and mars_nwe, which will give Linux partial -NetWare Server functionality. -Linware's home site is: klokan.sh.cvut.cz/pub/linux/linware, -Mars_nwe can be found on ftp.gwdg.de/pub/linux/misc/ncpfs. +NetWare server functionality. Linware's home site is +klokan.sh.cvut.cz/pub/linux/linware; mars_nwe can be found on +ftp.gwdg.de/pub/linux/misc/ncpfs. diff --git a/Documentation/filesystems/romfs.txt b/Documentation/filesystems/romfs.txt index 7df713201..2d2a7b2a1 100644 --- a/Documentation/filesystems/romfs.txt +++ b/Documentation/filesystems/romfs.txt @@ -1,7 +1,6 @@ - ROMFS - ROM FILE SYSTEM -This is a quite dumb, read only filesystem, mainly for initial ram +This is a quite dumb, read only filesystem, mainly for initial RAM disks of installation disks. It has grown up by the need of having modules linked at boot time. Using this filesystem, you get a very similar feature, and even the possibility of a small kernel, with a @@ -29,13 +28,13 @@ However, the main purpose of romfs is to have a very small kernel, which has only this filesystem linked in, and then can load any module later, with the current module utilities. It can also be used to run some program to decide if you need SCSI devices, and even IDE or -floppy drives can be loaded later if you use the "initrd" -- initial -ram disk -- feature of the kernel. This would not be really news +floppy drives can be loaded later if you use the "initrd"--initial +RAM disk--feature of the kernel. This would not be really news flash, but with romfs, you can even spare off your ext2 or minix or maybe even affs filesystem until you really know that you need it. For example, a distribution boot disk can contain only the cd disk -drivers (and possibly the SCSI drivers), and the ISO filesystem +drivers (and possibly the SCSI drivers), and the ISO 9660 filesystem module. The kernel can be small enough, since it doesn't have other filesystems, like the quite large ext2fs module, which can then be loaded off the CD at a later stage of the installation. Another use @@ -148,7 +147,7 @@ please contact me. However, think twice before wanting me to add features and code, because the primary and most important advantage of this file system is the small code. On the other hand, don't be alarmed, I'm not getting that much romfs related mail. Now I can -understand why Avery wrote poems in the arcnet docs to get some more +understand why Avery wrote poems in the ARCnet docs to get some more feedback. :) romfs has also a mailing list, and to date, it hasn't received any @@ -167,7 +166,7 @@ I have never found this limiting, but others might. one would want to write _anything_ to a file system, he still needs a writable file system, thus negating the size advantages. Possible solutions: implement write access as a compile-time option, or a new, -similarly small writable filesystem for ram disks. +similarly small writable filesystem for RAM disks. - Since the files are only required to have alignment on a 16 byte boundary, it is currently possibly suboptimal to read or execute files diff --git a/Documentation/filesystems/vfat.txt b/Documentation/filesystems/vfat.txt index 1a0da9d40..b475d510a 100644 --- a/Documentation/filesystems/vfat.txt +++ b/Documentation/filesystems/vfat.txt @@ -34,7 +34,7 @@ uni_xlate=<bool> -- Translate unhandled Unicode characters to special posix=<bool> -- Allow names of same letters, different case such as 'LongFileName' and 'longfilename' to coexist. This has some problems currently because 8.3 conflicts are not handled - correctly for Posix filesystem compliance. + correctly for POSIX filesystem compliance. nonumtail=<bool> -- When creating 8.3 aliases, normally the alias will end in '~1' or tilde followed by some number. If this option is set, then if the filename is @@ -61,7 +61,7 @@ TODO a get next directory entry approach. The only thing left that uses raw scanning is the directory renaming code. -* Fix the Posix filesystem support to work in 8.3 space. This involves +* Fix the POSIX filesystem support to work in 8.3 space. This involves renaming aliases if a conflict occurs between a new filename and an old alias. This is quite a mess. diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 9dfe8dc27..7e4f3d04e 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -1,174 +1,448 @@ -A Brief Overview of the Virtual File System -=========================================== - by Benjamin LaHaise (blah@dot.superaje.com) +/* -*- auto-fill -*- */ -Noone else seems to be writing this, so here's a quick description of what -I've learned while writing lofs... + Overview of the Virtual File System -The VFS is relatively simple, but it is nice not to have to browse through -pages of code to determine what is expected when writing a filesystem. -Hopefully this helps anyone attempting such a feat, as well as clearing up -a few important points/dependencies. + Richard Gooch <rgooch@atnf.csiro.au> -register_filesystem (struct file_system_type *fstype) -===================================================== + 27-JUN-1998 -All filesystems are created equal... or at least they start out that way. -A filesystem, be it in module form, or linked into the kernel, needs to add -itself to the table of filesystems by calling register_filesystem with an -initialized file_system_type structure. Any further functions of the -filesystem are accessed through the following function tables... +Conventions used in this document <section> +================================= -struct file_system_type -======================= +Each section in this document will have the string "<section>" at the +right-hand side of the section title. Each subsection will have +"<subsection>" at the right-hand side. These strings are meant to make +it easier to search through the document. - struct super_block *(*read_super) (struct super_block *sb, void *options, int silent); +NOTE that the master copy of this document is available online at: +http://www.atnf.csiro.au/~rgooch/linux/docs/vfs.txt - This is the entry point of all filesystems. If the filesystem succeeds - in mounting itself, sb should be returned, otherwise NULL. options is - a pointer to a maximum of PAGE_SIZE-1 bytes of options, typically a zero - terminated string passed from mount. This page is freed after read_super - returns, so do not use any pointers into it. - This routine _must_ set the s_op member of sb to point to a valid - super_operations structure. +What is it? <section> +=========== - const char *name; +The Virtual File System (otherwise known as the Virtual Filesystem +Switch) is the software layer in the kernel that provides the +filesystem interface to userspace programmes. It also provides an +abstraction within the kernel which allows different filesystem +implementations to co-exist. - Name points to a string that the system will know the filesystem by. - int requires_dev; +A Quick Look At How It Works <section> +============================ - Set this flag to 1 if the filesystem requires a block device to be mounted - on. +In this section I'll briefly describe how things work, before +launching into the details. I'll start with describing what happens +when user programmes open and manipulate files, and then look from the +other view which is how a filesystem is supported and subsequently +mounted. - struct file_system_type * next; +Opening a File <subsection> +-------------- + +The VFS implements the open(2) system call. The pathname argument is +used by the VFS to search through the directory entry cache (dentry +cache or "dcache"). This provides a very fast lookup mechanism to +translate a pathname (filename) into a specific dentry. + +An individual dentry usually has a pointer to an inode. Inodes are the +things that live on disc drives, and can be regular files (you know: +those things that you write data into), directories, FIFOs and other +beasts. Dentries live in RAM and are never saved to disc: they exist +only for performance. Inodes live on disc and are copied into memory +when required. Later any changes are written back to disc. The inode +that lives in RAM is a VFS inode, and it is this which the dentry +points to. + +The dcache is meant to be a view into your entire filespace. Unlike +Linus, most of us losers can't fit enough dentries into RAM to cover +all of our filespace, so the dcache has bits missing. In order to +resolve your pathname into a dentry, the VFS may have to resort to +creating dentries along the way, and then loading the inode. This is +done by looking up the inode. + +To lookup an inode (usually read from disc) requires that the VFS +calls the lookup() method of the parent directory inode. This method +is installed by the specific filesystem implementation that the inode +lives in. There will be more on this later. + +Once the VFS has the required dentry (and hence the inode), we can do +all those boring things like open(2) the file, or stat(2) it to peek +at the inode data. The stat(2) operation is fairly simple: once the +VFS has the dentry, it peeks at the inode data and passes some of it +back to userspace. + +Opening a file requires another operation: allocation of a file +structure (this is the kernel-side implementation of file +descriptors). The freshly allocated file structure is initialised with +a pointer to the dentry and a set of file operation member +functions. These are taken from the inode data. The open() file method +is then called so the specific filesystem implementation can do it's +work. You can see that this is another switch performed by the VFS. + +The file structure is placed into the file descriptor table for the +process. - This field points to the next file_system_type that is present in the system, - and should be initialized to NULL. +Reading, writing and closing files (and other assorted VFS operations) +is done by using the userspace file descriptor to grab the appropriate +file structure, and then calling the required file structure method +function to do whatever is required. -struct super_operations +For as long as the file is open, it keeps the dentry "open" (in use), +which in turn means that the VFS inode is still in use. + +Registering and Mounting a Filesystem <subsection> +------------------------------------- + +If you want to support a new kind of filesystem in the kernel, all you +need to do is call register_filesystem(). You pass a structure +describing the filesystem implementation (struct file_system_type) +which is then added to an internal table of supported filesystems. You +can do: + +% cat /proc/filesystems + +to see what filesystems are currently available on your system. + +When a request is made to mount a block device onto a directory in +your filespace the VFS will call the appropriate method for the +specific filesystem. The dentry for the mount point will then be +updated to point to the root inode for the new filesystem. + +It's now time to look at things in more detail. + + +struct file_system_type <section> ======================= -The super_operations structure is found through the s_op member of the -super_block structure. +This describes the filesystem. As of kernel 2.1.99, the following +members are defined: + +struct file_system_type { + const char *name; + int fs_flags; + struct super_block *(*read_super) (struct super_block *, void *, int); + struct file_system_type * next; +}; - void (*read_inode) (struct inode *inode); - [optional - doesn't quite make sense] - read_inode is called by the VFS when iget is called requesting an inode - not already present in the inode table. i_ino is set to the number of the - inode requested. + name: the name of the filesystem type, such as "ext2", "iso9660", + "msdos" and so on - The i_op member of inode should be set to a valid inode_operations - structure. Typically filesystems have separate inode_operations for - directories, files and symlinks. i_op can be NULL. + fs_flags: various flags (i.e. if it is a read-only FS) - int (*notify_change) (struct inode *, struct iattr *); - [optional] - void (*write_inode) (struct inode *); - [optional] + read_super: the method to call when a new instance of this + filesystem should be mounted + + next: for internal VFS use: you should initialise this to NULL + +The read_super() method has the following arguments: + + struct super_block *sb: the superblock structure. This is partially + initialised by the VFS and the rest must be initialised by the + read_super() method + + void *data: arbitrary mount options, usually comes as an ASCII + string + + int silent: whether or not to be silent on error + +The read_super() method must determine if the block device specified +in the superblock contains a filesystem of the type the method +supports. On success the method returns the superblock pointer, on +failure it returns NULL. + +The most interesting member of the superblock structure that the +read_super() method fills in is the "s_op" field. This is a pointer to +a "struct super_operations" which describes the next level of the +filesystem implementation. - int (*put_inode) (struct inode *inode); - [optional] - put_inode is called by the VFS when the last instance of inode is released - with a call to iput. The only special consideration that should be made - is that iget may reuse inode without calling read_inode unless clear_inode - is called. put_inode MUST return 1 if it called clear_inode on the inode, - otherwise zero. +struct super_operations <section> +======================= + +This describes how the VFS can manipulate the superblock of your +filesystem. As of kernel 2.1.99, the following members are defined: + +struct super_operations { + void (*read_inode) (struct inode *); + void (*write_inode) (struct inode *); + void (*put_inode) (struct inode *); + void (*delete_inode) (struct inode *); + int (*notify_change) (struct dentry *, struct iattr *); void (*put_super) (struct super_block *); - [optional] void (*write_super) (struct super_block *); - [optional] - void (*statfs) (struct super_block *, struct statfs *, int); - [optional] + int (*statfs) (struct super_block *, struct statfs *, int); int (*remount_fs) (struct super_block *, int *, char *); - [optional] + void (*clear_inode) (struct inode *); +}; + +All methods are called without any locks being held, unless otherwise +noted. This means that most methods can block safely. All methods are +only called from a process context (i.e. not from an interrupt handler +or bottom half). + + read_inode: this method is called to read a specific inode from the + mounted filesystem. The "i_ino" member in the "struct inode" + will be initialised by the VFS to indicate which inode to + read. Other members are filled in by this method + + write_inode: this method is called when the VFS needs to write an + inode to disc + + put_inode: called when the VFS inode is removed from the inode + cache. This method is optional + + delete_inode: called when the VFS wants to delete an inode + notify_change: called when VFS inode attributes are changed. If this + is NULL the VFS falls back to the write_inode() method. This + is called with the kernel lock held -struct inode_operations + put_super: called when the VFS wishes to free the superblock + (i.e. unmount). This is called with the superblock lock held + + write_super: called when the VFS superblock needs to be written to + disc. This method is optional + + statfs: called when the VFS needs to get filesystem statistics. This + is called with the kernel lock held + + remount_fs: called when the filesystem is remounted. This is called + with the kernel lock held + + clear_inode: called then the VFS clears the inode. Optional + +The read_inode() method is responsible for filling in the "i_op" +field. This is a pointer to a "struct inode_operations" which +describes the methods that can be performed on individual inodes. + + +struct inode_operations <section> ======================= - struct file_operations * default_file_ops; - [mandatory] - All inode_operations structures must have default_file_ops pointing to - a valid file_operations structure. - - int (*create) (struct inode *,const char *,int,int,struct inode **); - [optional] - - int (*lookup) (struct inode *dir, const char *name, int len, struct inode **result); - [optional] - lookup is called when the VFS wishes to have the filesystem resolve a name - into an inode. Dir is a directory on the filesystem that [hopefully] contains - the zero terminated string name (length len). A return value of zero indicates - that there is a valid inode stored in *result. - -*** Note: lofs assumes that any filesystem returns an inode within the filesystem - for all directory inodes. Therefore, __iget(sb,ino,0) should be used to fetch - the inode in a filesystem's lookup routine. - - int (*link) (struct inode *,struct inode *,const char *,int); - [optional] - int (*unlink) (struct inode *,const char *,int); - [optional] - int (*symlink) (struct inode *,const char *,int,const char *); - [optional] - int (*mkdir) (struct inode *,const char *,int,int); - [optional] - int (*rmdir) (struct inode *,const char *,int); - [optional] - int (*mknod) (struct inode *,const char *,int,int,int); - [optional] - int (*rename) (struct inode *,const char *,int,struct inode *,const char *,int, int); - [optional] - - int (*readlink) (struct inode *inode, char *buf, int len); - [optional] - readlink is called by the VFS to read the contents of a symbolic link. - inode is an inode that meets the S_ISLNK test, and buf points to a buffer - of len bytes. - - int (*follow_link) (struct inode *,struct inode *,int,int,struct inode **); - [optional] - follow_link must be implemented if readlink is implemented. - Note that follow_link can return a different inode than a - lookup_dentry() on the result of readlink() would return. - The proc filesystem, in particular, uses this feature heavily. - For most user filesystems, however, follow_link() and readlink() - should return consistent results. - - int (*readpage) (struct inode *, struct page *); [optional] - int (*writepage) (struct inode *, struct page *); [mandatory with readpage] - - In order for files to be mmap'd, readpage and writepage are required. - A filesystem can use generic_readpage/writepage if it supports the bmap - function. Otherwise, a custom version must be written. +This describes how the VFS can manipulate an inode in your +filesystem. As of kernel 2.1.99, the following members are defined: +struct inode_operations { + struct file_operations * default_file_ops; + int (*create) (struct inode *,struct dentry *,int); + int (*lookup) (struct inode *,struct dentry *); + int (*link) (struct dentry *,struct inode *,struct dentry *); + int (*unlink) (struct inode *,struct dentry *); + int (*symlink) (struct inode *,struct dentry *,const char *); + int (*mkdir) (struct inode *,struct dentry *,int); + int (*rmdir) (struct inode *,struct dentry *); + int (*mknod) (struct inode *,struct dentry *,int,int); + int (*rename) (struct inode *, struct dentry *, + struct inode *, struct dentry *); + int (*readlink) (struct dentry *, char *,int); + struct dentry * (*follow_link) (struct dentry *, struct dentry *); + int (*readpage) (struct file *, struct page *); + int (*writepage) (struct file *, struct page *); int (*bmap) (struct inode *,int); - [optional] void (*truncate) (struct inode *); - [optional] int (*permission) (struct inode *, int); - [optional] int (*smap) (struct inode *,int); - [optional] - -struct file_operations + int (*updatepage) (struct file *, struct page *, const char *, + unsigned long, unsigned int, int); + int (*revalidate) (struct dentry *); +}; + + default_file_ops: this is a pointer to a "struct file_operations" + which describes how to manipulate open files + + create: called by the open(2) and creat(2) system calls. Only + required if you want to support regular files. The dentry you + get should not have an inode (i.e. it should be a negative + dentry). Here you will probably call d_instantiate() with the + dentry and the newly created inode + + lookup: called when the VFS needs to lookup an inode in a parent + directory. The name to look for is found in the dentry. This + method must call d_add() to insert the found inode into the + dentry. The "i_count" field in the inode structure should be + incremented. If the named inode does not exist a NULL inode + should be inserted into the dentry (this is called a negative + dentry). Returning an error code from this routine must only + be done on a real error, otherwise creating inodes with system + calls like create(2), mknod(2), mkdir(2) and so on will fail. + If you wish to overload the dentry methods then you should + initialise the "d_dop" field in the dentry; this is a pointer + to a struct "dentry_operations". + This method is called with the directory semaphore held + + link: called by the link(2) system call. Only required if you want + to support hard links. You will probably need to call + d_instantiate() just as you would in the create() method + + unlink: called by the unlink(2) system call. Only required if you + want to support deleting inodes + + symlink: called by the symlink(2) system call. Only required if you + want to support symlinks. You will probably need to call + d_instantiate() just as you would in the create() method + + mkdir: called by the mkdir(2) system call. Only required if you want + to support creating subdirectories. You will probably need to + call d_instantiate() just as you would in the create() method + + rmdir: called by the rmdir(2) system call. Only required if you want + to support deleting subdirectories + + mknod: called by the mknod(2) system call to create a device (char, + block) inode or a named pipe (FIFO) or socket. Only required + if you want to support creating these types of inodes. You + will probably need to call d_instantiate() just as you would + in the create() method + + readlink: called by the readlink(2) system call. Only required if + you want to support reading symbolic links + + follow_link: called by the VFS to follow a symbolic link to the + inode it points to. Only required if you want to support + symbolic links + + +struct file_operations <section> ====================== - int (*lseek) (struct inode *, struct file *, off_t, int); - int (*read) (struct inode *, struct file *, char *, int); - int (*write) (struct inode *, struct file *, const char *, int); - int (*readdir) (struct inode *, struct file *, void *, filldir_t); - unsigned int (*poll) (struct file *, poll_table *); +This describes how the VFS can manipulate an open file. As of kernel +2.1.99, the following members are defined: + +struct file_operations { + loff_t (*llseek) (struct file *, loff_t, int); + ssize_t (*read) (struct file *, char *, size_t, loff_t *); + ssize_t (*write) (struct file *, const char *, size_t, loff_t *); + int (*readdir) (struct file *, void *, filldir_t); + unsigned int (*poll) (struct file *, struct poll_table_struct *); int (*ioctl) (struct inode *, struct file *, unsigned int, unsigned long); - int (*mmap) (struct inode *, struct file *, struct vm_area_struct *); + int (*mmap) (struct file *, struct vm_area_struct *); int (*open) (struct inode *, struct file *); - void (*release) (struct inode *, struct file *); - int (*fsync) (struct inode *, struct file *); - int (*fasync) (struct inode *, struct file *, int); + int (*release) (struct inode *, struct file *); + int (*fsync) (struct file *, struct dentry *); + int (*fasync) (struct file *, int); int (*check_media_change) (kdev_t dev); int (*revalidate) (kdev_t dev); + int (*lock) (struct file *, int, struct file_lock *); +}; + + llseek: called when the VFS needs to move the file position index + + read: called by the read(2) system call + + write: called by the write(2) system call + + readdir: called when the VFS needs to read the directory contents + + poll: called by the VFS when a process wants to check if there is + activity on this file and (optionally) go to sleep until there + is activity + + ioctl: called by the ioctl(2) system call + + mmap: called by the mmap(2) system call + + open: called by the VFS when an inode should be opened. When the VFS + opens a file, it creates a new "struct file" and initialises + the "f_op" file operations member with the "default_file_ops" + field in the inode structure. It then calls the open method + for the newly allocated file structure. You might think that + the open method really belongs in "struct inode_operations", + and you may be right. I think it's done the way it is because + it makes filesystems simpler to implement. The open() method + is a good place to initialise the "private_data" member in the + file structure if you want to point to a device structure + + release: called when the last reference to an open file is closed + + fsync: called by the fsync(2) system call + + fasync: called by the fcntl(2) system call when asynchronous + (non-blocking) mode is enabled for a file + +Note that the file operations are implemented by the specific +filesystem in which the inode resides. When opening a device node +(character or block special) most filesystems will call special +support routines in the VFS which will locate the required device +driver information. These support routines replace the filesystem file +operations with those for the device driver, and then proceed to call +the new open() method for the file. This is how opening a device file +in the filesystem eventually ends up calling the device driver open() +method. Note the devfs (the Device FileSystem) has a more direct path +from device node to device driver (this is an unofficial kernel +patch). + + +struct dentry_operations <section> +======================== + +This describes how a filesystem can overload the standard dentry +operations. Dentries and the dcache are the domain of the VFS and the +individual filesystem implementations. Device drivers have no business +here. As of kernel 2.1.99, the following members are defined: + +struct dentry_operations { + int (*d_revalidate)(struct dentry *); + int (*d_hash) (struct dentry *, struct qstr *); + int (*d_compare) (struct dentry *, struct qstr *, struct qstr *); + void (*d_delete)(struct dentry *); + void (*d_release)(struct dentry *); + void (*d_iput)(struct dentry *, struct inode *); +}; + + d_revalidate: called when the VFS needs to revalidate a dentry + + d_hash: called when the VFS adds a dentry to the hash table + + d_compare: called when a dentry should be compared with another + + d_delete: called when the last reference to a dentry is + deleted. This means no-one is using the dentry, however it is + still valid and in the dcache + + d_release: called when a dentry is deallocated + + d_iput: called when a dentry looses its inode (just prior to its + being deallocated). The default when this is NULL is that the + VFS calls iput(). If you define this method, you must call + iput() yourself + +Each dentry has a pointer to its parent dentry, as well as a hash list +of child dentries. Child dentries are basically like files in a +directory. + +There are a number of functions defined which permit a filesystem to +manipulate dentries: + + dget: open a new handle for an existing dentry (this just increments + the usage count) + + dput: close a handle for a dentry (decrements the usage count). If + the usage count drops to 0, the "d_delete" method is called + and the dentry is placed on the unused list if the dentry is + still in its parents hash list. Putting the dentry on the + unused list just means that if the system needs some RAM, it + goes through the unused list of dentries and deallocates them. + If the dentry has already been unhashed and the usage count + drops to 0, in this case the dentry is deallocated after the + "d_delete" method is called + d_drop: this unhashes a dentry from its parents hash list. A + subsequent call to dput() will dellocate the dentry if its + usage count drops to 0 + + d_delete: delete a dentry. If there are no other open references to + the dentry then the dentry is turned into a negative dentry + (the d_iput() method is called). If there are other + references, then d_drop() is called instead + + d_add: add a dentry to its parents hash list and then calls + d_instantiate() + + d_instantiate: add a dentry to the alias hash list for the inode and + updates the "d_inode" member. The "i_count" member in the + inode structure should be set/incremented. If the inode + pointer is NULL, the dentry is called a "negative + dentry". This function is commonly called when an inode is + created for an existing negative dentry |