From: Nikolaus Rath Date: Sun, 16 Oct 2016 22:05:57 +0000 (-0700) Subject: Various documentation updates X-Git-Tag: fuse-3.0.0rc1~32 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=1c08ee91f68220c1904efbb278f6641403380474;p=qemu-gpiodev%2Flibfuse.git Various documentation updates Move README.NFS into doc/ Update project URL Remove reference to non-existent INSTALL file Remove outdated/obsolete NEWS and how-fuse-works files. Update references to examples. --- diff --git a/NEWS b/NEWS deleted file mode 100644 index 559ee86..0000000 --- a/NEWS +++ /dev/null @@ -1,303 +0,0 @@ -What is new in 2.9 - - - Add "zero copy" support for kernel 2.6.35 or newer - - - Make maximum background requests tunable on kernel 2.6.32 or newer - - - Require --no-canonicalize in (u)mount (util-linux version 2.18 or - newer) to fix security problems with fusermount - - - Use dynamically sized hash tables in high level library - - - Memory use of filesystem daemon can shrink more easily - - - Add "auto_unmount" option - - - Add "remember" option - - - Add man pages for fusermount, mount.fuse and ulockmgr_server - - - API changes: - - o Introduce "store" and "retrieve" for accessing kernel buffers on - kernel 2.6.36 or newer - - o Introduce abstract buffer for zero copy operations - - o Allow path calculation to be omitted on certain operations - - o Allow batching forget requests - - o Add "flock" method - - o Add support for ioctl on directories - - o Add delete notification - - o Add fallocate operation (linux kernel 3.5 or newer) - - - Bug fixes and small improvements - -============================================================================ - -What is new in 2.8 - - - More scalable directory tree locking - - - Atomic open(O_TRUNC) support - - - Support big write requests on kernels 2.6.26 and newer - - - Out-of-tree fuse module removed - - - Better NFS exporting support - - - New ioctl and poll requests - - - New CUSE (Character Device in Userspace) interface - - - Allow umask processing in userspace - - - Added cache invalidation notifications - - - Bugfixes and small improvements - -============================================================================ - -What is new in 2.7 - - - Stacking support for the high level API - - - Add filename charset conversion module - - - Improved mounting - -============================================================================ - -What is new in 2.6 - - - Improved read characteristics (asynchronous reads) - - - Support for aborting filesystem connection - - - POSIX file locking support - - - Request interruption support - - - Building module for Linux kernels earlier than 2.6.9 not supported - - - Allow block device based filesystems to support swap files - - - Several bugs fixed, including a rare system hang on SMP - -============================================================================ - -What is new in 2.5 - - - Merge library part of FreeBSD port - - - New atomic create+open, access and ftruncate operations - - - On filesystems implementing the new create+open operation, and - running on Linux kernels 2.6.15 or later, the 'cp' operation will - work correctly when copying read-only files. - - - New option parsing interface added to the library - - - Lots of minor improvements and fixes - -============================================================================ - -What is new in 2.4 - - - Simplify device opening. Now '/dev/fuse' is a requirement - - - Allow module auto-loading if user has access to '/dev/fuse' - - - Allow mounting over a regular file for unprivileged users - - - Allow mounting of arbitrary FUSE filesystems from /etc/fstab - - - New mount options: 'umask=M', 'uid=N', 'gid=N' - - - Check for non-empty mountpoint, and refuse mount by default. New - mount option: 'nonempty' - - - Low level (inode based) API added - - - Allow 'direct_io' and 'keep_cache' options to be set on a - case-by-case basis on open. - - - Add 'attr_timeout' and 'entry_timeout' mount options to the - high-level library. Until now these timeouts were fixed at 1 sec. - - - Some bugfixes - -============================================================================ - -What is new in 2.3 - - - Add new directory related operations: opendir(), readdir(), - releasedir() and fsyncdir() - - - Add init() and destroy() operations which are called before the - event loop is started and after it has exited - - - Update kernel ABI so that on dual architectures (e.g. AMD64) 32bit - binaries work under a 64bit kernel - - - Bugfixes - -============================================================================ - -What is new in 2.2 - -Userspace changes: - - - Add fuse_file_info structure to file operations, this allows the - filesystem to return a file handle in open() which is passed to - read(), write(), flush(), fsync() and release(). - - - Add source compatibility with 2.1 and 1.4 releases - - - Binary compatibility with 2.1 release is retained - -Kernel changes: - - - Make requests interruptible. This prevents the filesystem to go - into an unbreakable deadlock with itself. - - - Make readpages() synchronous. Asynchronous requests are deadlock - prone, since they cannot be interrupted (see above) - - - Remove shared-writeable mapping support, which could deadlock the - machine - - - Remove INVALIDATE userspace initiated request - - - Update ABI to be independent of sizeof(long), so dual-size archs - don't cause problems - - - Remove /sys/fs/fuse/version. Version checking is now done through - the fuse device - - - Replace directory reading method on the kernel interface. Instead - of passing an open file descriptor to the kernel, send data through - the FUSE device, like all other operations. - -============================================================================ - -What is new in 2.1 - -* Bug fixes - -* Improved support for filesystems implementing a custom event-loop - -* Add 'pkg-config' support - -* Kernel module can be compiled separately - -============================================================================ - -What is new in 1.9 - -* Lots of bugs fixed - -* Minor modifications to the library API - -* Improvements to the kernel/userspace interface - -* Mounting by non-root made more secure - -* Build shared library in addition to the static one - -* Consolidated mount options - -* Optimized reading under 2.6 kernels - -* Direct I/O support - -* Support file I/O on deleted files - -* Extended attributes support - -============================================================================ - -What is new in 1.3 - -* Thanks to user bugreports and stress testing with LTP and sfx-linux -a number of bugs were fixed, some quite serious. - -* Fix compile problems with recent SuSE kernles - -============================================================================ - -What is new in 1.2 - -* Fix mount problems on recent 2.6 kernels with SELinux enabled - -* Fixed writing files lager than 2GBytes - -* Other bugfixes - -============================================================================ - -What is new in 1.1 - -* Support for the 2.6 kernels - -* Support for exporting filesystem over NFS in 2.6 kernels - -* Read efficiency improvements: read in 64k blocks instead of 4k -(Michael Grigoriev). Can be turned on with '-l' option of fusermount - -* Lazy automatic unmount - -* Added 'fsync()' VFS call to the FUSE interface - -* Bugfixes - -============================================================================ - -What is new in 1.0 - -* Cleanups and bugfixes - -* Added 'release()' VFS call to the FUSE interface - -* 64 bit file offsets (handling of > 4 GByte files) - -* libfuse is now under LGPL - -* New 'statfs' call (Mark Glines) - -* Cleaned up mount procedure (mostly by Mark Glines) - - NOTE: Binaries linked with with a previous version of libavfs may - not work with the new version of the fusermount program. In such - case recompile the program after installing the new libavfs library. - -* Fix for problems under linux kernel 2.4.19 - -============================================================================ - -What is new in 0.95 - -* Optimized read/write operations. Raw throughput has increased to -about 60Mbyte/s on a Celeron/360 - -* Python bindings by Jeff Epler - -* Perl bindings by Mark Glines - -* Improved multithreaded operation - -* Simplified library interface - -* Bugfixes - -============================================================================ - -What is new in 0.9: - -* Everything diff --git a/README.NFS b/README.NFS deleted file mode 100644 index f3348d5..0000000 --- a/README.NFS +++ /dev/null @@ -1,33 +0,0 @@ -NFS exporting is supported in Linux kernels 2.6.27 or later. - -You need to add an fsid=NNN option to /etc/exports to make exporting a -FUSE directory work. - -Filesystem support ------------------- - -NFS exporting works to some extent on all fuse filesystems, but not -perfectly. This is due to the stateless nature of the protocol, the -server has no way of knowing whether the client is keeping a reference -to a file or not, and hence that file may be removed from the server's -cache. In that case there has to be a way to look up that object -using the inode number, otherwise an ESTALE error will be returned. - -1) low-level interface - -Filesystems need to implement special lookups for the names "." and -"..". The former may be requested on any inode, including -non-directories, while the latter is only requested for directories. -Otherwise these special lookups should behave identically to ordinary -lookups. - -2) high-level interface - -Because the high-level interface is path based, it is not possible to -delegate looking up by inode to the filesystem. - -To work around this, currently a "noforget" option is provided, which -makes the library remember nodes forever. This will make the NFS -server happy, but also results in an ever growing memory footprint for -the filesystem. For this reason if the filesystem is large (or the -memory is small), then this option is not recommended. diff --git a/README.md b/README.md index 33c9df9..f2d9ceb 100644 --- a/README.md +++ b/README.md @@ -70,8 +70,6 @@ create the `configure` script. You'll also need a fuse kernel module (Linux kernels 2.6.14 or later contain FUSE support). -For more details see the file `INSTALL` - Security implications --------------------- @@ -97,8 +95,8 @@ Building your own filesystem ------------------------------ FUSE comes with several example file systems in the `examples` -directory. For example, the *fusexmp* example mirrors the contents of -the root directory under the mountpoint. Start from there and adapt +directory. For example, the *passthrough* examples mirror the contents +of the root directory under the mountpoint. Start from there and adapt the code! The documentation of the API functions and necessary callbacks is diff --git a/doc/Makefile.am b/doc/Makefile.am index 2f2fa0f..1644383 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -2,4 +2,4 @@ dist_man_MANS = fusermount.1 mount.fuse.8 -EXTRA_DIST = how-fuse-works kernel.txt Doxyfile html +EXTRA_DIST = kernel.txt Doxyfile html README.NFS developer-notes.rst diff --git a/doc/README.NFS b/doc/README.NFS new file mode 100644 index 0000000..f3348d5 --- /dev/null +++ b/doc/README.NFS @@ -0,0 +1,33 @@ +NFS exporting is supported in Linux kernels 2.6.27 or later. + +You need to add an fsid=NNN option to /etc/exports to make exporting a +FUSE directory work. + +Filesystem support +------------------ + +NFS exporting works to some extent on all fuse filesystems, but not +perfectly. This is due to the stateless nature of the protocol, the +server has no way of knowing whether the client is keeping a reference +to a file or not, and hence that file may be removed from the server's +cache. In that case there has to be a way to look up that object +using the inode number, otherwise an ESTALE error will be returned. + +1) low-level interface + +Filesystems need to implement special lookups for the names "." and +"..". The former may be requested on any inode, including +non-directories, while the latter is only requested for directories. +Otherwise these special lookups should behave identically to ordinary +lookups. + +2) high-level interface + +Because the high-level interface is path based, it is not possible to +delegate looking up by inode to the filesystem. + +To work around this, currently a "noforget" option is provided, which +makes the library remember nodes forever. This will make the NFS +server happy, but also results in an ever growing memory footprint for +the filesystem. For this reason if the filesystem is large (or the +memory is small), then this option is not recommended. diff --git a/doc/how-fuse-works b/doc/how-fuse-works deleted file mode 100644 index a5febe3..0000000 --- a/doc/how-fuse-works +++ /dev/null @@ -1,54 +0,0 @@ - How Fuse-1.3 Works - -[Written by Terje Oseberg] - -1. The fuse library. - -When your user mode program calls fuse_main() (lib/helper.c), -fuse_main() parses the arguments passed to your user mode program, -then calls fuse_mount() (lib/mount.c). - -fuse_mount() creates a UNIX domain socket pair, then forks and execs -fusermount (util/fusermount.c) passing it one end of the socket in the -FUSE_COMMFD_ENV environment variable. - -fusermount (util/fusermount.c) makes sure that the fuse module is -loaded. fusermount then open /dev/fuse and send the file handle over a -UNIX domain socket back to fuse_mount(). - -fuse_mount() returns the filehandle for /dev/fuse to fuse_main(). - -fuse_main() calls fuse_new() (lib/fuse.c) which allocates the struct -fuse datastructure that stores and maintains a cached image of the -filesystem data. - -Lastly, fuse_main() calls either fuse_loop() (lib/fuse.c) or -fuse_loop_mt() (lib/fuse_mt.c) which both start to read the filesystem -system calls from the /dev/fuse, call the usermode functions -stored in struct fuse_operations datastructure before calling -fuse_main(). The results of those calls are then written back to the -/dev/fuse file where they can be forwarded back to the system -calls. - -2. The kernel module. - -The kernel module consists of two parts. First the proc filesystem -component in kernel/dev.c -and second the filesystem system calls -kernel/file.c, kernel/inode.c, and kernel/dir.c - -All the system calls in kernel/file.c, kernel/inode.c, and -kernel/dir.c make calls to either request_send(), -request_send_noreply(), or request_send_nonblock(). Most of the calls -(all but 2) are to request_send(). request_send() adds the request to, -"list of requests" structure (fc->pending), then waits for a response. -request_send_noreply() and request_send_nonblock() are both similar in -function to request_send() except that one is non-blocking, and the -other does not respond with a reply. - -The proc filesystem component in kernel/dev.c responds to file io -requests to the file /dev/fuse. fuse_dev_read() handles the -file reads and returns commands from the "list of requests" structure -to the calling program. fuse_dev_write() handles file writes and takes -the data written and places them into the req->out datastructure where -they can be returned to the system call through the "list of requests" -structure and request_send(). diff --git a/doc/kernel.txt b/doc/kernel.txt index 397a41a..fd3f174 100644 --- a/doc/kernel.txt +++ b/doc/kernel.txt @@ -49,7 +49,7 @@ using the sftp protocol. The userspace library and utilities are available from the FUSE homepage: - http://fuse.sourceforge.net/ + https://github.com/libfuse/libfuse/ Filesystem type ~~~~~~~~~~~~~~~