third_party_libfuse/FAQ

This was generated on 2005/09/27 from

  http://fuse.sourceforge.net/wiki/index.php/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
-----------------------------

Filesystems mounted without sysadmin privileges can be umounted with
the command

    fusermount -u mountpoint

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.

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.

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.

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)

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.