13 our @ISA = qw(Exporter DynaLoader);
15 # Items to export into callers namespace by default. Note: do not export
16 # names by default without a very good reason. Use EXPORT_OK instead.
17 # Do not simply export all your public functions/methods/constants.
19 # This allows declaration use Fuse ':all';
20 # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
23 'all' => [ qw(FUSE_DEBUG XATTR_CREATE XATTR_REPLACE) ],
24 'debug' => [ qw(FUSE_DEBUG) ],
25 'xattr' => [ qw(XATTR_CREATE XATTR_REPLACE) ]
28 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
33 our $VERSION = '0.06';
36 # This AUTOLOAD is used to 'autoload' constants from the constant()
37 # XS function. If a constant is not found then control is passed
38 # to the AUTOLOAD in AutoLoader.
42 ($constname = $AUTOLOAD) =~ s/.*:://;
43 croak "& not defined" if $constname eq 'constant';
44 my $val = constant($constname, @_ ? $_[0] : 0);
47 $AutoLoader::AUTOLOAD = $AUTOLOAD;
48 goto &AutoLoader::AUTOLOAD;
51 croak "Your vendor has not defined Fuse macro $constname";
56 # Fixed between 5.005_53 and 5.005_61
58 *$AUTOLOAD = sub () { $val };
61 *$AUTOLOAD = sub { $val };
77 bootstrap Fuse $VERSION;
80 my (@subs) = (0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0);
81 my (@names) = qw(getattr readlink getdir mknod mkdir unlink rmdir symlink
82 rename link chmod chown truncate utime open read write statfs
83 flush release fsync setxattr getxattr listxattr removexattr);
85 my (%mapping) = map { $_ => $tmp++ } (@names);
86 my (%otherargs) = (debug=>0, mountpoint=>"");
87 while(my $name = shift) {
89 if(exists($otherargs{$name})) {
90 $otherargs{$name} = $subref;
92 croak "There is no function $name" unless exists($mapping{$name});
93 croak "Usage: Fuse::main(getattr => &my_getattr, ...)" unless $subref;
94 croak "Usage: Fuse::main(getattr => &my_getattr, ...)" unless ref($subref);
95 croak "Usage: Fuse::main(getattr => &my_getattr, ...)" unless ref($subref) eq "CODE";
96 $subs[$mapping{$name}] = $subref;
99 perl_fuse_main($otherargs{debug},$otherargs{mountpoint},@subs);
102 # Autoload methods go after =cut, and are processed by the autosplit program.
109 Fuse - write filesystems in Perl using FUSE
114 my ($mountpoint) = "";
115 $mountpoint = shift(@ARGV) if @ARGV;
116 Fuse::main(mountpoint=>$mountpoint, getattr=>\&my_getattr, getdir=>\&my_getdir, ...);
120 This lets you implement filesystems in perl, through the FUSE
121 (Filesystem in USErspace) kernel/lib interface.
123 FUSE expects you to implement callbacks for the various functions.
125 NOTE: I have only tested the things implemented in example.pl!
126 It should work, but some things may not.
128 In the following definitions, "errno" can be 0 (for a success),
129 -EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really.
131 You can import standard error constants by saying something like
132 "use POSIX qw(EDOTDOT ENOANO);".
134 Every constant you need (file types, open() flags, error values,
135 etc) can be imported either from POSIX or from Fcntl, often both.
136 See their respective documentations, for more information.
138 =head2 EXPORTED SYMBOLS
140 FUSE_DEBUG by default.
142 You can request all exportable symbols by using the tag ":all".
144 You can request all debug symbols by using the tag ":debug".
145 This will export FUSE_DEBUG.
147 You can request the extended attribute symbols by using the tag ":xattr".
148 This will export XATTR_CREATE and XATTR_REPLACE.
154 Takes arguments in the form of hash key=>value pairs. There are
155 many valid keys. Most of them correspond with names of callback
156 functions, as described in section 'FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT'.
157 A few special keys also exist:
164 This turns FUSE call tracing on and off. Default is 0 (which means off).
172 The point at which to mount this filesystem. There is no default, you must
173 specify this. An example would be '/mnt'.
177 unthreaded => boolean
181 This turns FUSE multithreading off and on. NOTE: This perlmodule does not
182 currently work properly in multithreaded mode! The author is unfortunately
183 not familiar enough with perl-threads internals, and according to the
184 documentation available at time of writing (2002-03-08), those internals are
185 subject to changing anyway. Note that singlethreaded mode also means that
186 you will not have to worry about reentrancy, though you will have to worry
187 about recursive lookups (since the kernel holds a global lock on your
188 filesystem and blocks waiting for one callback to complete before calling
191 I hope to add full multithreading functionality later, but for now, I
192 recommend you leave this option at the default, 1 (which means
193 unthreaded, no threads will be used and no reentrancy is needed).
197 =head2 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT
202 Returns a list, very similar to the 'stat' function (see
203 perlfunc). On error, simply return a single numeric scalar
204 value (e.g. "return -ENOENT();").
206 FIXME: the "ino" field is currently ignored. I tried setting it to 0
207 in an example script, which consistently caused segfaults.
209 Fields (the following was stolen from perlfunc(1) with apologies):
211 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
212 $atime,$mtime,$ctime,$blksize,$blocks)
213 = getattr($filename);
215 Here are the meaning of the fields:
217 0 dev device number of filesystem
219 2 mode file mode (type and permissions)
220 3 nlink number of (hard) links to the file
221 4 uid numeric user ID of file's owner
222 5 gid numeric group ID of file's owner
223 6 rdev the device identifier (special files only)
224 7 size total size of file, in bytes
225 8 atime last access time in seconds since the epoch
226 9 mtime last modify time in seconds since the epoch
227 10 ctime inode change time (NOT creation time!) in seconds
229 11 blksize preferred block size for file system I/O
230 12 blocks actual number of blocks allocated
232 (The epoch was at 00:00 January 1, 1970 GMT.)
236 Arguments: link pathname.
237 Returns a scalar: either a numeric constant, or a text string.
239 This is called when dereferencing symbolic links, to learn the target.
241 example rv: return "/proc/self/fd/stdin";
245 Arguments: Containing directory name.
246 Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0).
248 This is used to obtain directory listings. Its opendir(), readdir(), filldir() and closedir() all in one call.
250 example rv: return ('.', 'a', 'b', 0);
254 Arguments: Filename, numeric modes, numeric device
255 Returns an errno (0 upon success, as usual).
257 This function is called for all non-directory, non-symlink nodes,
262 Arguments: New directory pathname, numeric modes.
265 Called to create a directory.
272 Called to remove a file, device, or symlink.
279 Called to remove a directory.
283 Arguments: Existing filename, symlink name.
286 Called to create a symbolic link.
290 Arguments: old filename, new filename.
293 Called to rename a file, and/or move a file from one directory to another.
297 Arguments: Existing filename, hardlink name.
300 Called to create hard links.
304 Arguments: Pathname, numeric modes.
307 Called to change permissions on a file/directory/device/symlink.
311 Arguments: Pathname, numeric uid, numeric gid.
314 Called to change ownership of a file/directory/device/symlink.
318 Arguments: Pathname, numeric offset.
321 Called to truncate a file, at the given offset.
325 Arguments: Pathname, numeric actime, numeric modtime.
328 Called to change access/modification times for a file/directory/device/symlink.
332 Arguments: Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY
333 and O_SYNC, constants you can import from POSIX).
336 No creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open().
337 Your open() method needs only check if the operation is permitted for the given flags, and return 0 for success.
341 Arguments: Pathname, numeric requestedsize, numeric offset.
342 Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data.
344 Called in an attempt to fetch a portion of the file.
348 Arguments: Pathname, scalar buffer, numeric offset. You can use length($buffer) to
352 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.
357 Returns any of the following:
363 $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
367 -ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
372 Returns an errno or 0 on success.
374 Called to synchronise any cached data. This is called before the file
375 is closed. It may be called multiple times before a file is closed.
379 Arguments: Pathname, numeric flags passed to open
380 Returns an errno or 0 on success.
382 Called to indicate that there are no more references to the file. Called once
383 for every file with the same pathname and flags as were passed to open.
387 Arguments: Pathname, numeric flags
388 Returns an errno or 0 on success.
390 Called to synchronise the file's contents. If flags is non-zero,
391 only synchronise the user data. Otherwise synchronise the user and meta data.
395 Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE
396 Returns an errno or 0 on success.
398 Called to set the value of the named extended attribute.
400 If you wish to reject setting of a particular form of extended attribute name
401 (e.g.: regexps matching user\..* or security\..*), then return - EOPNOTSUPP.
403 If flags is set to XATTR_CREATE and the extended attribute already exists,
404 this should fail with - EEXIST. If flags is set to XATTR_REPLACE
405 and the extended attribute doesn't exist, this should fail with - ENOATTR.
407 XATTR_CREATE and XATTR_REPLACE are provided by this module, but not exported
408 by default. To import them:
418 Arguments: Pathname, extended attribute's name
419 Returns an errno, 0 if there was no value, or the extended attribute's value.
421 Called to get the value of the named extended attribute.
426 Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0).
430 Arguments: Pathname, extended attribute's name
431 Returns an errno or 0 on success.
435 Mark Glines, E<lt>mark@glines.orgE<gt>
439 L<perl>, the FUSE documentation.