1===================== 2 General Information 3===================== 4 5.. currentmodule:: llfuse 6 7.. _getting_started: 8 9Getting started 10=============== 11 12A file system is implemented by subclassing the `llfuse.Operations` 13class and implementing the various request handlers. The handlers 14respond to requests received from the FUSE kernel module and perform 15functions like looking up the inode given a file name, looking up 16attributes of an inode, opening a (file) inode for reading or writing 17or listing the contents of a (directory) inode. 18 19An instance of the operations class is passed to `llfuse.init` to 20mount the file system. To enter the request handling loop, run 21`llfuse.main`. This function will return when the file system should 22be unmounted again, which is done by calling `llfuse.close`. 23 24All character data (directory entry names, extended attribute names 25and values, symbolic link targets etc) are passed as `bytes` and must 26be returned as `bytes`. This applies to both running under Python 2.x 27and 3.x 28 29For easier debugging, it is strongly recommended that applications 30using Python-LLFUSE also make use of the faulthandler_ module. 31 32.. _faulthandler: http://docs.python.org/3/library/faulthandler.html 33 34 35Lookup Counts 36============= 37 38Most file systems need to keep track which inodes are currently known 39to the kernel. This is, for example, necessary to correctly implement 40the *unlink* system call: when unlinking a directory entry whose 41associated inode is currently opened, the file system must defer 42removal of the inode (and thus the file contents) until it is no 43longer in use by any process. 44 45FUSE file systems achieve this by using "lookup counts". A lookup 46count is a number that's associated with an inode. An inode with a 47lookup count of zero is currently not known to the kernel. This means 48that if there are no directory entries referring to such an inode it 49can be safely removed, or (if a file system implements dynamic inode 50numbers), the inode number can be safely recycled. 51 52The lookup count of an inode is increased by one for each call to the 53`~Operations.lookup`, `~Operations.create`, `~Operations.symlink`, 54`~Operations.mknod`, `~Operations.link` and `~Operations.mkdir` 55handlers. The lookup count is decreased by calls to the 56`~Operations.forget` handler. 57 58 59FUSE and VFS Locking 60==================== 61 62FUSE and the kernel's VFS layer provide some basic locking that FUSE 63file systems automatically take advantage of. Specifically: 64 65* Calls to `~Operations.rename`, `~Operations.create`, 66 `~Operations.symlink`, `~Operations.mknod`, `~Operations.link` and 67 `~Operations.mkdir` acquire a write-lock on the inode of the 68 directory in which the respective operation takes place (two in case 69 of rename). 70 71* Calls to `~Operations.lookup` acquire a read-lock on the inode of the 72 parent directory (meaning that lookups in the same directory may run 73 concurrently, but never at the same time as e.g. a rename or mkdir 74 operation). 75 76* Unless writeback caching is enabled (which Python-LLFUSE does not 77 yet allow), calls to `~Operations.write` for the same inode are 78 automatically serialized (i.e., there are never concurrent calls for 79 the same inode even when multithreading is enabled). 80