NAME

Lufs::Howto - howto write a module for perlfs

DESCRIPTION

This documentation contains some basic knowledge necessary for writing modules for perlfs. perlfs is a module for Lufs (Linux Userland FileSystem) http://lufs.sourceforge.net/ which in turn loads perl modules as Lufs modules. The perlfs module and some example perl modules that implement a filesystem can be found in the Lufs package on CPAN.

The concept is very simple, you just write a module implementing some basic filesystem operations (see "METHODS" below) and perlfs takes care of the rest.

Mounting

Once you wrote a module implementing a filesystem, say Foo::Bar, you can mount it with a command like this:

lufsmount -c 1 perlfs://Foo.Bar /mnt/foobar

Lufs normally uses an URL scheme to encode the filesystem that is to be mounted, but perlfs employs what normally would be the hostname to encode the module that is to be used. In this scheme the dot '.' is used as the namespace separator instead of '::'.

The "port" and "root" parts of the URL can be used as configuration arguments. You can supply other arguments to your module in two ways, you can supply them as mount options on the commandline, or put them in /etc/lufsd.conf. The commandline mount options work like this:

lufsmount -c 1 -o arg1=value1,arg2=value2 perlfs://Foo.Bar /mnt/foobar

To specify options in lufsd.conf the names needs to start with PERLFS::. Also it is good practice to prefix all names of options in lufsd.conf with the name of your module to avoid conflicts with other perl modules.

Both commandline options and options from lufsd.conf are supplied to the init() method.

TODO something bout automount stuff

METHODS

FIXME which methods are mandatory ?

All methods (except for init()) return true on success and false on failure. Methods that should result in other data always get a reference to a data structure to store this data.

When a method gets a file- or a directory-name these names are always relative to the mount point.

init($self, \%options)

This method is used instead of a constructor, $self is an empty hash blessed into your class.

The hash %options contains both mount options supplied on the command line and _all_ options from "etc/lufsd.conf" that start with PERLFS::. This hash contains a key host with your module name. Also this hash can contain the keys port and root which are the remaining parts of the URL that was "mounted".

mount($self)

Mount the "filesystem".

umount($self)

Umount the "filesystem".

stat($self, $node, \%attr)

This method should put information about a file or directory in the hash %attr. perldoc -f stat lists the keys with a nice verbose explanation. The keys should be prefixed with 'f_'.

FIXME a verbose explanation of the keys here

See also FIXME man page bout stat

read($self, $file, $offset, $count, $buffer)

This method should put $count number of bytes at offset $offset from $file into $buffer.

FIXME is $buffer a scalar or a scalar ref ?

write($self, $file, $offset, $count, $buffer)

Should write the $count number of bytes form $buffer to $file at offset $offset.

mkdir($self, $dir, $mode)

Create a new dir.

$mode is the octal bitmask for the wanted permissions.

readdir($self, $dir, \@list)

Should store a list of files in the array @list which is referenced by the third argument.

Make sure to remove . and .. from the list when using output from CORE::readdir.

rmdir($self, $dir)

Remove a dir.

create($self, $file, $mode)

Create a new file.

$mode is the octal bitmask for the wanted permissions.

unlink($self, $file)

Remove a file.

rename($self, $node1, $node2)

FIXME can this be done for both files and dirs ?

open($self, $file, $mode)

This should just return true or false. All filehandle bookkeepping should be done internally. You can get the constants for working with $mode with use Fcntl. Example:

use Fcntl;
if (($mode & O_WRONLY) == O_WRONLY) { q{just for writing} }

release($self, $file)

Close a file.

readlink($self, $file, $buffer)

FIXME is $buffer a scalar or a scalar ref ?

link($self, $file1, $file2)

Hard links are not allowed to directories.

symlink($self, $node1, $node2)

Symlinks can reference both files and directories.

setattr($self, $node, \%attr)

This module is the opposite of stat(), it should set the properties in %attr for $node.

touch($self, $file)

FIXME I suppose dirs can't be touched (?)

AUTHOR

This document was written by Jaap Karssenberg <pardus@cpan.org>. You are free to copy and modify it as you see fit.

The Lufs perl package is maintained by Raoul Zwart <rlzwart@cpan.org>.

SEE ALSO

Lufs, http://lufs.sourceforge.net/