Fuse.3pm

Langue: en

Version: 2008-05-11 (ubuntu - 08/07/09)

Section: 3 (Bibliothèques de fonctions)

NAME

Fuse - write filesystems in Perl using FUSE

SYNOPSIS

   use Fuse;
   my ($mountpoint) = "";
   $mountpoint = shift(@ARGV) if @ARGV;
   Fuse::main(mountpoint=>$mountpoint, getattr=>"main::my_getattr", getdir=>"main::my_getdir", ...);
 
 

DESCRIPTION

This lets you implement filesystems in perl, through the FUSE (Filesystem in USErspace) kernel/lib interface.

FUSE expects you to implement callbacks for the various functions.

In the following definitions, ``errno'' can be 0 (for a success), -EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really.

You can import standard error constants by saying something like ``use POSIX qw(EDOTDOT ENOANO);''.

Every constant you need (file types, open() flags, error values, etc) can be imported either from POSIX or from Fcntl, often both. See their respective documentations, for more information.

EXPORTED SYMBOLS

None by default.

You can request all exportable symbols by using the tag ``:all''.

You can request the extended attribute symbols by using the tag ``:xattr''. This will export XATTR_CREATE and XATTR_REPLACE.

FUNCTIONS

Fuse::main

Takes arguments in the form of hash key=>value pairs. There are many valid keys. Most of them correspond with names of callback functions, as described in section 'FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT'. A few special keys also exist:

debug => boolean

This turns FUSE call tracing on and off. Default is 0 (which means off).

mountpoint => string

The point at which to mount this filesystem. There is no default, you must specify this. An example would be '/mnt'.

mountopts => string

This is a comma seperated list of mount options to pass to the FUSE kernel module.
At present, it allows the specification of the allow_other argument when mounting the new FUSE filesystem. To use this, you will also need 'user_allow_other' in /etc/fuse.conf as per the FUSE documention
   mountopts => "allow_other" or
   mountopts => ""
 
 

threaded => boolean

This turns FUSE multithreading on and off. The default is 0, meaning your FUSE script will run in single-threaded mode. Note that single-threaded mode also means that you will not have to worry about reentrancy, though you will have to worry about recursive lookups. In single-threaded mode, FUSE holds a global lock on your filesystem, and will wait for one callback to return before calling another. This can lead to deadlocks, if your script makes any attempt to access files or directories in the filesystem it is providing. (This includes calling stat() on the mount-point, statfs() calls from the 'df' command, and so on and so forth.) It is worth paying a little attention and being careful about this.
Enabling multithreading will cause FUSE to make multiple simultaneous calls into the various callback functions of your perl script. If you enable threaded mode, you can enjoy all the parallel execution and interactive response benefits of threads, and you get to enjoy all the benefits of race conditions and locking bugs, too. Please also ensure any other perl modules you're using are also thread-safe.
(If enabled, this option will cause a warning if your perl interpreter was not built with USE_ITHREADS, or if you have failed to use threads or threads::shared.)

FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT

getattr

Arguments: filename. Returns a list, very similar to the 'stat' function (see perlfunc). On error, simply return a single numeric scalar value (e.g. ``return -ENOENT();'').

FIXME: the ``ino'' field is currently ignored. I tried setting it to 0 in an example script, which consistently caused segfaults.

Fields (the following was stolen from perlfunc(1) with apologies):

($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
        $atime,$mtime,$ctime,$blksize,$blocks)
                         = getattr($filename);

Here are the meaning of the fields:

  0 dev      device number of filesystem
  1 ino      inode number
  2 mode     file mode  (type and permissions)
  3 nlink    number of (hard) links to the file
  4 uid      numeric user ID of file's owner
  5 gid      numeric group ID of file's owner
  6 rdev     the device identifier (special files only)
  7 size     total size of file, in bytes
  8 atime    last access time in seconds since the epoch
  9 mtime    last modify time in seconds since the epoch
 10 ctime    inode change time (NOT creation time!) in seconds
             since the epoch
 11 blksize  preferred block size for file system I/O
 12 blocks   actual number of blocks allocated
 
 

(The epoch was at 00:00 January 1, 1970 GMT.)

readlink

Arguments: link pathname. Returns a scalar: either a numeric constant, or a text string.

This is called when dereferencing symbolic links, to learn the target.

example rv: return ``/proc/self/fd/stdin'';

getdir

Arguments: Containing directory name. Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0).

This is used to obtain directory listings. Its opendir(), readdir(), filldir() and closedir() all in one call.

example rv: return ('.', 'a', 'b', 0);

mknod

Arguments: Filename, numeric modes, numeric device Returns an errno (0 upon success, as usual).

This function is called for all non-directory, non-symlink nodes, not just devices.

mkdir

Arguments: New directory pathname, numeric modes. Returns an errno.

Called to create a directory.

unlink

Arguments: Filename. Returns an errno.

Called to remove a file, device, or symlink.

rmdir

Arguments: Pathname. Returns an errno.

Called to remove a directory.

symlink

Arguments: Existing filename, symlink name. Returns an errno.

Called to create a symbolic link.

rename

Arguments: old filename, new filename. Returns an errno.

Called to rename a file, and/or move a file from one directory to another.

link

Arguments: Existing filename, hardlink name. Returns an errno.

Called to create hard links.

chmod

Arguments: Pathname, numeric modes. Returns an errno.

Called to change permissions on a file/directory/device/symlink.

chown

Arguments: Pathname, numeric uid, numeric gid. Returns an errno.

Called to change ownership of a file/directory/device/symlink.

truncate

Arguments: Pathname, numeric offset. Returns an errno.

Called to truncate a file, at the given offset.

utime

Arguments: Pathname, numeric actime, numeric modtime. Returns an errno.

Called to change access/modification times for a file/directory/device/symlink.

open

Arguments: Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY and O_SYNC, constants you can import from POSIX). Returns an errno.

No creation, or truncation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open(). Your open() method needs only check if the operation is permitted for the given flags, and return 0 for success.

read

Arguments: Pathname, numeric requestedsize, numeric offset. Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data.

Called in an attempt to fetch a portion of the file.

write

Arguments: Pathname, scalar buffer, numeric offset. You can use length($buffer) to find the buffersize. Returns an errno.

Called in an attempt to write (or overwrite) a portion of the file. Be prepared because $buffer could contain random binary data with NULLs and all sorts of other wonderful stuff.

statfs

Arguments: none Returns any of the following:

-ENOANO()

or

$namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize

or

-ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize

flush

Arguments: Pathname Returns an errno or 0 on success.

Called to synchronise any cached data. This is called before the file is closed. It may be called multiple times before a file is closed.

release

Arguments: Pathname, numeric flags passed to open Returns an errno or 0 on success.

Called to indicate that there are no more references to the file. Called once for every file with the same pathname and flags as were passed to open.

fsync

Arguments: Pathname, numeric flags Returns an errno or 0 on success.

Called to synchronise the file's contents. If flags is non-zero, only synchronise the user data. Otherwise synchronise the user and meta data.

setxattr

Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE Returns an errno or 0 on success.

Called to set the value of the named extended attribute.

If you wish to reject setting of a particular form of extended attribute name (e.g.: regexps matching user\..* or security\..*), then return - EOPNOTSUPP.

If flags is set to XATTR_CREATE and the extended attribute already exists, this should fail with - EEXIST. If flags is set to XATTR_REPLACE and the extended attribute doesn't exist, this should fail with - ENOATTR.

XATTR_CREATE and XATTR_REPLACE are provided by this module, but not exported by default. To import them:

     use Fuse ':xattr';
 
 

or:

     use Fuse ':all';
 
 

getxattr

Arguments: Pathname, extended attribute's name Returns an errno, 0 if there was no value, or the extended attribute's value.

Called to get the value of the named extended attribute.

listxattr

Arguments: Pathname Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0).

removexattr

Arguments: Pathname, extended attribute's name Returns an errno or 0 on success.

AUTHOR

Mark Glines, <mark@glines.org>

SEE ALSO

perl, the FUSE documentation.