File Manager

Editing File: /usr/share/doc/fuse-2.9.2/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

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 proprietary 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.