Current Path :
/
usr
/
share
/
doc
/
fuse-2.8.3
/
Or
Select Your Path :
Upload File :
New :
File
Dir
//usr/share/doc/fuse-2.8.3/FAQ
This was generated on 2006/10/17 from http://sourceforge.net/apps/mediawiki/fuse/index.php?title=FAQ For an up to date version please see the above page. You can also add new entries there. General ======= How can I umount a filesystem? ------------------------------ FUSE filesystems can be unmounted either with: umount mountpoint or fusermount -u mountpoint The later does not need root privileges if the filesystem was mounted by the user doing the unmounting. What's the difference between FUSE and LUFS? -------------------------------------------- The main difference between them is that in LUFS the filesystem is a shared object (.so) which is loaded by lufsmount, and in FUSE the filesystem is a separate executable, which uses the fuse library. The actual API is very similar, and there's a translator, that can load LUFS modules and run them using the FUSE kernel module (see the lufis package on the FUSE page). Another difference is that LUFS does some caching of directories and file attributes. FUSE does not do this, so it provides a 'thinner' interface. By now LUFS development seems to have completely ceased. Why is it called FUSE? There's a ZX Spectrum emulator called Fuse too. ---------------------------------------------------------------------- At the time of christening it, the author of FUSE (the filesystem) hadn't heard of Fuse (the Speccy emulator). Which is ironic, since he knew Philip Kendall, the author of that other Fuse from earlier times. Btw. the author of FUSE (the filesystem) also created a Speccy emulator called Spectemu. The name wanted to be a clever acronym for "Filesystem in USErspace", but it turned out to be an unfortunate choice. The author has since vowed never to name a project after a common term, not even anything found more than a handful of times on Google. Is it possible to mount a fuse filesystem from fstab? ----------------------------------------------------- Yes, from version 2.4.0 this is possible. The filesystem must adhere to some rules about command line options to be able to work this way. Here's an example of mounting an sshfs filesystem: sshfs#user@host:/ /mnt/host fuse defaults 0 0 The mounting is performed by the /sbin/mount.fuse helper script. In this example the FUSE-linked binary must be called sshfs and must reside somewhere in $PATH. Licensing issues ~~~~~~~~~~~~~~~~ Under what license is FUSE released? ------------------------------------ The kernel part is released under the GNU GPL. Libfuse is released under the GNU LGPLv2. All other parts (examples, fusermount, etc) are released under the GNU GPL. Under what conditions may I modify or distribute FUSE? ------------------------------------------------------ See the files COPYING and COPYING.LIB in the distribution. More information can be found at http://www.gnu.org/licenses/ Under what conditions may I distribute a filesystem which uses libfuse? ----------------------------------------------------------------------- See COPYING.LIB in the distribution. In simple terms as long as you are linking dynamically (the default) there are no limitations on linking with libfuse. For example you may distribute the filesystem itself in binary form, without source code, under any propriatery license. Under what conditions may I distribute a filesystem that uses the raw --------------------------------------------------------------------- kernel interface of FUSE? ------------------------- There are no restrictions whatsoever for using the raw kernel interface. API === Which method is called on the close() system call? -------------------------------------------------- flush() and possibly release(). For details see the documentation of these methods in <fuse.h> Wouldn't it be simpler if there were a single close() method? ------------------------------------------------------------- No, because the relationship between the close() system call and the release of the file (the opposite of open) is not as simple as people tend to imagine. UNIX allows open files to acquire multiple references * after fork() two processes refer to the same open file * dup() and dup2() make another file descriptor refer to the same file * mmap() makes a memory mapping refer to an open file This means, that for a single open() system call, there could be more than one close() and possibly munmap() calls until the open file is finally released. Can I return an error from release()? ------------------------------------- No, it's not possible. If you need to return errors on close, you must do that from flush(). How do I know which is the last flush() before release()? --------------------------------------------------------- You can't. All flush() calls should be treated equally. Anyway it wouldn't be worth optimizing away non-final flushes, since it's fairly rare to have multiple write-flush sequences on an open file. Why doesn't FUSE forward ioctl() calls to the filesystem? --------------------------------------------------------- Because it's not possible: data passed to ioctl() doesn't have a well defined length and structure like read() and write(). Consider using getxattr() and setxattr() instead. Is there a way to know the uid, gid or pid of the process performing -------------------------------------------------------------------- the operation? -------------- Yes: fuse_get_context()->uid, etc. How should threads be started? ------------------------------ Miscellaneous threads should be started from the init() method. Threads started before fuse_main() will exit when the process goes into the background. Is it possible to store a pointer to private data in the -------------------------------------------------------- fuse_file_info structure? ------------------------- Yes, the 'fh' filed is for this purpose. This filed may be set in the open() and create() methods, and is available in all other methods having a struct fuse_file_info parameter. Note, that changing the value of 'fh' in any other method as open() or create() will have no affect. Since the type of 'fh' is unsigned long, you need to use casts when storing and retrieving a pointer. Under Linux (and most other architectures) an unsigned long will be able to hold a pointer. This could have been done with a union of 'void *' and 'unsigned long' but that would not have been any more type safe as having to use explicit casts. The recommended type safe solution is to write a small inline function that retrieves the pointer from the fuse_file_info structure. Problems ======== Version problems ~~~~~~~~~~~~~~~~ Why do I get Connection Refused after mounting? ----------------------------------------------- Library is too old (< 2.3.0) You can check which version of the library is being used by foofs by doing 'ldd path_to_foofs'. It will return something like this libfuse.so.2 => /usr/local/lib/libfuse.so.2 (0xb7fc9000) libpthread.so.0 => /lib/tls/libpthread.so.0 (0xb7fb9000) libglib-2.0.so.0 => /usr/lib/libglib-2.0.so.0 (0xb7f39000) libc.so.6 => /lib/tls/libc.so.6 (0xb7e04000) Then do 'ls -l path_to_libfuse' > ls -l /usr/local/lib/libfuse.so.2 lrwxrwxrwx 1 root root 16 Sep 26 13:41 /usr/local/lib/libfuse.so.2 -> libfuse.so.2.2.1 Why does fusermount fail with an Unknown option error? ------------------------------------------------------ Errors like 'fusermount: Unknown option -o' or 'fusermount: Unknown option --' mean, that an old version of fusermount is being used. You can check by doing 'which fusermount'. If you installed FUSE from source, then this is probably because there exists a binary package on your system which also contains a fusermount program, and is found first in the path, e.g. in /usr/bin/fusermount. The solution is to remove the binary package. Installation problems ~~~~~~~~~~~~~~~~~~~~~ Why is there an error loading shared libraries? ----------------------------------------------- If you get the following error when starting a FUSE-based filesystem: foofs: error while loading shared libraries: libfuse.so.2: cannot open shared object file: No such file or directory check /etc/ld.so.conf for a line containing '/usr/local/lib'. If it's missing, add it, and run ldconfig afterwards. Why doesn't mounting as user work if installing FUSE from a package? -------------------------------------------------------------------- Distributions often package 'fusermount' without the suid bit, or only executable to the 'fuse' group. This results in the following message, when trying to mount a filesystem as an unprivileged user: fusermount: mount failed: Operation not permitted The simplest solution is to change the mode of 'fusermount': chmod 4755 /usr/bin/fusermount Note, you may have to do this after each upgrade. Other problems ~~~~~~~~~~~~~~ Why are some bytes zeroed when reading a file? ---------------------------------------------- This happens if the filesystem returns a short count from the read() method. If the file wasn't opened in direct I/O mode, the read() method must return exactly the requested number of bytes, unless it's the end of the file. If the file was opened in direct I/O mode (with direct_io mount option, or by setting the direct_io field of fuse_file_info at open) the read can return a smaller value than requested. In this case the end of file can be signalled by returning zero. What do I do if /dev/fuse does not exist? ----------------------------------------- Maybe the FUSE module is not loaded. As root, try: modprobe fuse If nothing changes, as root run: mknod /dev/fuse c 10 229 What do I do if you don't have access to /dev/fuse? --------------------------------------------------- As root run: chmod o+rw /dev/fuse Remember that this will allow ordinary users to mount their own user space filesystems. If that's not what you want then use different permissions. Why does cp return operation not permitted when copying a file with no ---------------------------------------------------------------------- write permissions for the owner? -------------------------------- "cp" calls open(2) with read-only permissions and O_CREAT, the purpose being to atomically obtain a read/write file handle and make the file read-only. Unfortunately, this does not work very well in fuse, since you first get a mknod, and then an open call. At the time of open, you can't distinguish easily wether this is the first open issued by cp, or another process trying to write a read-only file. Defining the 'create' method solves this problem, however this requires a Linux kernel version of at least 2.6.15 and libfuse version 2.5 or greater (on FreeBSD you'll need fuse4bsd-0.3.0-pre1 or newer for this). There can be other workarounds, however the easy one is to use the "default_permissions" mount option, and to avoid checking permissions on open. If you store files on a filesystem, this can get tricky because you will have to change the file mode to allow writing. Using the stateful API (i.e. returning an handle on open) will simplify things. In this case, and using "-o default_permissions", when implementing the open call you have to: 1. check if the open is in write mode (i.e. mode has O_RDWR or O_WRONLY) 2. in that case (in mutual exclusion with other open, getattr etc. calls on the same file) change the mode from "M" to "M OR 0o200" 3. open the file, change back the mode even in case of errors, and return the obtained handle Why doesn't find work on my filesystem? --------------------------------------- The st_nlink member must be set correctly for directories to make find work. If it's not set correctly the -noleaf option of find can be used to make it ignore the hard link count (see man find). The correct value of st_nlink for directories is NSUB + 2. Where NSUB is the number of subdirectories. NOTE: regular-file/symlink/etc entries do not count into NSUB, only directories. If calculating NSUB is hard, the filesystem can set st_nlink of directories to 1, and find will still work. This is not documented behavior of find, and it's not clear whether this is intended or just by accident. But for example the NTFS filesysem relies on this, so it's unlikely that this "feature" will go away. What is the reason for IO errors? --------------------------------- The kernel part of FUSE returns the EIO error value, whenever the userspace filesystem sends a "bad" reply. Sometimes these are unavoidable, and not necessarily a fault of the filesystem. Possible causes of this are (non-exhaustive) * the filesystem returned a short count on write() * the type of the file has changed (e.g. a directory suddenly became a symlink) * a directory entry contained a filename that was too long (no, ENAMETOOLONG is not the right error here) * the same node ID value was used for two different directories (i.e. hard-linked directories are not allowed) * In the GETATTR function, st_mode needs to have a valid filetype bit set, like S_IFREG or S_IFDIR, see the stat manual for more * You are running a 64 bit kernel but using a 32 bit libfuse. In this case you will need to install a 64 bit version of the FUSE userspace library, 64 bit versions of all of the FUSE filesystems or language bindings that link to it, and 64 bit versions of all of their dependancies. Your distribution may provide 64 bit versions of the basic dependancies like libc even in its 32 bit environment Misc ==== Can the filesystem ask a question on the terminal of the user? -------------------------------------------------------------- It would not be possible generally speaking, since it might not be an interactive program but rather a daemon, or a GUI program doing the operation. However you should be able to get the PID for the caller, and by looking in /proc you should be able to find the process tty or something similar. But this is not recommended. You should rather think about solving this another way. If a filesystem is mounted over a directory, how can I access the old --------------------------------------------------------------------- contents? --------- There are two possibilities: The first is to use 'mount --bind DIR TMPDIR' to create a copy of the namespace under DIR. After mounting the FUSE filesystem over DIR, files can still be accessed through TMDIR. This needs root privileges. The second is to set the working directory to DIR after mounting the FUSE filesystem. For example before fuse_main() do save_dir = open(DIR, O_RDONLY); And from the init() method do fchdir(save_dir); close(save_dir); Then access the files with relative paths (with newer LIBC versions the *at() functions may also be used instead of changing the CWD). This method doesn't need root privileges, but only works on Linux (FreeBSD does path resolving in a different way), and it's not even guaranteed to work on future Linux versions.
