14 our @ISA = qw(Exporter DynaLoader);
16 # Items to export into callers namespace by default. Note: do not export
17 # names by default without a very good reason. Use EXPORT_OK instead.
18 # Do not simply export all your public functions/methods/constants.
20 # This allows declaration use Fuse ':all';
21 # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
24 'all' => [ qw(XATTR_CREATE XATTR_REPLACE fuse_get_context) ],
25 'xattr' => [ qw(XATTR_CREATE XATTR_REPLACE) ]
28 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
31 our $VERSION = '0.09';
34 # This AUTOLOAD is used to 'autoload' constants from the constant()
35 # XS function. If a constant is not found then control is passed
36 # to the AUTOLOAD in AutoLoader.
40 ($constname = $AUTOLOAD) =~ s/.*:://;
41 croak "& not defined" if $constname eq 'constant';
42 my $val = constant($constname, @_ ? $_[0] : 0);
45 $AutoLoader::AUTOLOAD = $AUTOLOAD;
46 goto &AutoLoader::AUTOLOAD;
49 croak "Your vendor has not defined Fuse macro $constname";
54 # Fixed between 5.005_53 and 5.005_61
56 *$AUTOLOAD = sub () { $val };
59 *$AUTOLOAD = sub { $val };
75 bootstrap Fuse $VERSION;
78 my @names = qw(getattr readlink getdir mknod mkdir unlink rmdir symlink
79 rename link chmod chown truncate utime open read write statfs
80 flush release fsync setxattr getxattr listxattr removexattr opendir readdir releasedir fsyncdir);
81 my @subs = map {undef} @names;
82 my @validOpts = qw(ro allow_other default_permissions fsname use_ino nonempty);
84 my %mapping = map { $_ => $tmp++ } @names;
85 my %optmap = map { $_ => 1 } @validOpts;
86 my @otherargs = qw(debug threaded mountpoint mountopts);
87 my %otherargs = (debug=>0, threaded=>0, mountpoint=>"", mountopts=>"");
88 while(my $name = shift) {
90 if(exists($otherargs{$name})) {
91 $otherargs{$name} = $subref;
93 croak "There is no function $name" unless exists($mapping{$name});
94 croak "Usage: Fuse::main(getattr => \"main::my_getattr\", ...)" unless $subref;
95 $subs[$mapping{$name}] = $subref;
98 foreach my $opt ( map {m/^([^=]*)/; $1} split(/,/,$otherargs{mountopts}) ) {
99 next if exists($optmap{$opt});
100 croak "Fuse::main: invalid '$opt' argument in mountopts";
102 if($otherargs{threaded}) {
103 # make sure threads are both available, and loaded.
104 if($Config{useithreads}) {
105 if(exists($threads::{VERSION})) {
106 if(exists($threads::shared::{VERSION})) {
109 carp("Thread support requires you to use threads::shared.\nThreads are disabled.\n");
110 $otherargs{threaded} = 0;
113 carp("Thread support requires you to use threads and threads::shared.\nThreads are disabled.\n");
114 $otherargs{threaded} = 0;
117 carp("Thread support was not compiled into this build of perl.\nThreads are disabled.\n");
118 $otherargs{threaded} = 0;
121 perl_fuse_main(@otherargs{@otherargs},@subs);
124 # Autoload methods go after =cut, and are processed by the autosplit program.
131 Fuse - write filesystems in Perl using FUSE
136 my ($mountpoint) = "";
137 $mountpoint = shift(@ARGV) if @ARGV;
138 Fuse::main(mountpoint=>$mountpoint, getattr=>"main::my_getattr", getdir=>"main::my_getdir", ...);
142 This lets you implement filesystems in perl, through the FUSE
143 (Filesystem in USErspace) kernel/lib interface.
145 FUSE expects you to implement callbacks for the various functions.
147 In the following definitions, "errno" can be 0 (for a success),
148 -EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really.
150 You can import standard error constants by saying something like
151 "use POSIX qw(EDOTDOT ENOANO);".
153 Every constant you need (file types, open() flags, error values,
154 etc) can be imported either from POSIX or from Fcntl, often both.
155 See their respective documentations, for more information.
157 =head2 EXPORTED SYMBOLS
161 You can request all exportable symbols by using the tag ":all".
163 You can request the extended attribute symbols by using the tag ":xattr".
164 This will export XATTR_CREATE and XATTR_REPLACE.
170 Takes arguments in the form of hash key=>value pairs. There are
171 many valid keys. Most of them correspond with names of callback
172 functions, as described in section 'FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT'.
173 A few special keys also exist:
180 This turns FUSE call tracing on and off. Default is 0 (which means off).
188 The point at which to mount this filesystem. There is no default, you must
189 specify this. An example would be '/mnt'.
197 This is a comma seperated list of mount options to pass to the FUSE kernel
200 At present, it allows the specification of the allow_other
201 argument when mounting the new FUSE filesystem. To use this, you will also
202 need 'user_allow_other' in /etc/fuse.conf as per the FUSE documention
204 mountopts => "allow_other" or
213 This turns FUSE multithreading on and off. The default is 0, meaning your FUSE
214 script will run in single-threaded mode. Note that single-threaded mode also
215 means that you will not have to worry about reentrancy, though you will have to
216 worry about recursive lookups. In single-threaded mode, FUSE holds a global
217 lock on your filesystem, and will wait for one callback to return before
218 calling another. This can lead to deadlocks, if your script makes any attempt
219 to access files or directories in the filesystem it is providing. (This
220 includes calling stat() on the mount-point, statfs() calls from the 'df'
221 command, and so on and so forth.) It is worth paying a little attention and
222 being careful about this.
224 Enabling multithreading will cause FUSE to make multiple simultaneous calls
225 into the various callback functions of your perl script. If you enable
226 threaded mode, you can enjoy all the parallel execution and interactive
227 response benefits of threads, and you get to enjoy all the benefits of race
228 conditions and locking bugs, too. Please also ensure any other perl modules
229 you're using are also thread-safe.
231 (If enabled, this option will cause a warning if your perl interpreter was not
232 built with USE_ITHREADS, or if you have failed to use threads or
237 =head2 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT
242 Returns a list, very similar to the 'stat' function (see
243 perlfunc). On error, simply return a single numeric scalar
244 value (e.g. "return -ENOENT();").
246 FIXME: the "ino" field is currently ignored. I tried setting it to 0
247 in an example script, which consistently caused segfaults.
249 Fields (the following was stolen from perlfunc(1) with apologies):
251 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
252 $atime,$mtime,$ctime,$blksize,$blocks)
253 = getattr($filename);
255 Here are the meaning of the fields:
257 0 dev device number of filesystem
259 2 mode file mode (type and permissions)
260 3 nlink number of (hard) links to the file
261 4 uid numeric user ID of file's owner
262 5 gid numeric group ID of file's owner
263 6 rdev the device identifier (special files only)
264 7 size total size of file, in bytes
265 8 atime last access time in seconds since the epoch
266 9 mtime last modify time in seconds since the epoch
267 10 ctime inode change time (NOT creation time!) in seconds
269 11 blksize preferred block size for file system I/O
270 12 blocks actual number of blocks allocated
272 (The epoch was at 00:00 January 1, 1970 GMT.)
276 Arguments: link pathname.
277 Returns a scalar: either a numeric constant, or a text string.
279 This is called when dereferencing symbolic links, to learn the target.
281 example rv: return "/proc/self/fd/stdin";
285 Arguments: Containing directory name.
286 Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0).
288 This is used to obtain directory listings. Its opendir(), readdir(), filldir() and closedir() all in one call.
290 example rv: return ('.', 'a', 'b', 0);
294 Arguments: Filename, numeric modes, numeric device
295 Returns an errno (0 upon success, as usual).
297 This function is called for all non-directory, non-symlink nodes,
302 Arguments: New directory pathname, numeric modes.
305 Called to create a directory.
312 Called to remove a file, device, or symlink.
319 Called to remove a directory.
323 Arguments: Existing filename, symlink name.
326 Called to create a symbolic link.
330 Arguments: old filename, new filename.
333 Called to rename a file, and/or move a file from one directory to another.
337 Arguments: Existing filename, hardlink name.
340 Called to create hard links.
344 Arguments: Pathname, numeric modes.
347 Called to change permissions on a file/directory/device/symlink.
351 Arguments: Pathname, numeric uid, numeric gid.
354 Called to change ownership of a file/directory/device/symlink.
358 Arguments: Pathname, numeric offset.
361 Called to truncate a file, at the given offset.
365 Arguments: Pathname, numeric actime, numeric modtime.
368 Called to change access/modification times for a file/directory/device/symlink.
372 Arguments: Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY
373 and O_SYNC, constants you can import from POSIX).
376 No creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open().
377 Your open() method needs only check if the operation is permitted for the given flags, and return 0 for success.
381 Arguments: Pathname, numeric requestedsize, numeric offset.
382 Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data.
384 Called in an attempt to fetch a portion of the file.
388 Arguments: Pathname, scalar buffer, numeric offset. You can use length($buffer) to
392 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.
397 Returns any of the following:
403 $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
407 -ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
412 Returns an errno or 0 on success.
414 Called to synchronise any cached data. This is called before the file
415 is closed. It may be called multiple times before a file is closed.
419 Arguments: Pathname, numeric flags passed to open
420 Returns an errno or 0 on success.
422 Called to indicate that there are no more references to the file. Called once
423 for every file with the same pathname and flags as were passed to open.
427 Arguments: Pathname, numeric flags
428 Returns an errno or 0 on success.
430 Called to synchronise the file's contents. If flags is non-zero,
431 only synchronise the user data. Otherwise synchronise the user and meta data.
435 Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE
436 Returns an errno or 0 on success.
438 Called to set the value of the named extended attribute.
440 If you wish to reject setting of a particular form of extended attribute name
441 (e.g.: regexps matching user\..* or security\..*), then return - EOPNOTSUPP.
443 If flags is set to XATTR_CREATE and the extended attribute already exists,
444 this should fail with - EEXIST. If flags is set to XATTR_REPLACE
445 and the extended attribute doesn't exist, this should fail with - ENOATTR.
447 XATTR_CREATE and XATTR_REPLACE are provided by this module, but not exported
448 by default. To import them:
458 Arguments: Pathname, extended attribute's name
459 Returns an errno, 0 if there was no value, or the extended attribute's value.
461 Called to get the value of the named extended attribute.
466 Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0).
470 Arguments: Pathname, extended attribute's name
471 Returns an errno or 0 on success.
475 Mark Glines, E<lt>mark@glines.orgE<gt>
479 L<perl>, the FUSE documentation.