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_3';
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);
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 =head3 Fuse::fuse_get_context
239 use Fuse "fuse_get_context";
240 my $caller_uid = fuse_get_context()->{"uid"};
241 my $caller_gid = fuse_get_context()->{"gid"};
242 my $caller_pid = fuse_get_context()->{"pid"};
244 Access context information about the current Fuse operation.
246 =head2 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT
251 Returns a list, very similar to the 'stat' function (see
252 perlfunc). On error, simply return a single numeric scalar
253 value (e.g. "return -ENOENT();").
255 FIXME: the "ino" field is currently ignored. I tried setting it to 0
256 in an example script, which consistently caused segfaults.
258 Fields (the following was stolen from perlfunc(1) with apologies):
260 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
261 $atime,$mtime,$ctime,$blksize,$blocks)
262 = getattr($filename);
264 Here are the meaning of the fields:
266 0 dev device number of filesystem
268 2 mode file mode (type and permissions)
269 3 nlink number of (hard) links to the file
270 4 uid numeric user ID of file's owner
271 5 gid numeric group ID of file's owner
272 6 rdev the device identifier (special files only)
273 7 size total size of file, in bytes
274 8 atime last access time in seconds since the epoch
275 9 mtime last modify time in seconds since the epoch
276 10 ctime inode change time (NOT creation time!) in seconds
278 11 blksize preferred block size for file system I/O
279 12 blocks actual number of blocks allocated
281 (The epoch was at 00:00 January 1, 1970 GMT.)
285 Arguments: link pathname.
286 Returns a scalar: either a numeric constant, or a text string.
288 This is called when dereferencing symbolic links, to learn the target.
290 example rv: return "/proc/self/fd/stdin";
294 Arguments: Containing directory name.
295 Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0).
297 This is used to obtain directory listings. Its opendir(), readdir(), filldir() and closedir() all in one call.
299 example rv: return ('.', 'a', 'b', 0);
303 Arguments: Filename, numeric modes, numeric device
304 Returns an errno (0 upon success, as usual).
306 This function is called for all non-directory, non-symlink nodes,
311 Arguments: New directory pathname, numeric modes.
314 Called to create a directory.
321 Called to remove a file, device, or symlink.
328 Called to remove a directory.
332 Arguments: Existing filename, symlink name.
335 Called to create a symbolic link.
339 Arguments: old filename, new filename.
342 Called to rename a file, and/or move a file from one directory to another.
346 Arguments: Existing filename, hardlink name.
349 Called to create hard links.
353 Arguments: Pathname, numeric modes.
356 Called to change permissions on a file/directory/device/symlink.
360 Arguments: Pathname, numeric uid, numeric gid.
363 Called to change ownership of a file/directory/device/symlink.
367 Arguments: Pathname, numeric offset.
370 Called to truncate a file, at the given offset.
374 Arguments: Pathname, numeric actime, numeric modtime.
377 Called to change access/modification times for a file/directory/device/symlink.
381 Arguments: Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY
382 and O_SYNC, constants you can import from POSIX).
385 No creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open().
386 Your open() method needs only check if the operation is permitted for the given flags, and return 0 for success.
390 Arguments: Pathname, numeric requestedsize, numeric offset.
391 Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data.
393 Called in an attempt to fetch a portion of the file.
397 Arguments: Pathname, scalar buffer, numeric offset. You can use length($buffer) to
399 Returns length($buffer) if successful (number of bytes written).
401 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.
406 Returns any of the following:
412 $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
416 -ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
421 Returns an errno or 0 on success.
423 Called to synchronise any cached data. This is called before the file
424 is closed. It may be called multiple times before a file is closed.
428 Arguments: Pathname, numeric flags passed to open
429 Returns an errno or 0 on success.
431 Called to indicate that there are no more references to the file. Called once
432 for every file with the same pathname and flags as were passed to open.
436 Arguments: Pathname, numeric flags
437 Returns an errno or 0 on success.
439 Called to synchronise the file's contents. If flags is non-zero,
440 only synchronise the user data. Otherwise synchronise the user and meta data.
444 Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE
445 Returns an errno or 0 on success.
447 Called to set the value of the named extended attribute.
449 If you wish to reject setting of a particular form of extended attribute name
450 (e.g.: regexps matching user\..* or security\..*), then return - EOPNOTSUPP.
452 If flags is set to XATTR_CREATE and the extended attribute already exists,
453 this should fail with - EEXIST. If flags is set to XATTR_REPLACE
454 and the extended attribute doesn't exist, this should fail with - ENOATTR.
456 XATTR_CREATE and XATTR_REPLACE are provided by this module, but not exported
457 by default. To import them:
467 Arguments: Pathname, extended attribute's name
468 Returns an errno, 0 if there was no value, or the extended attribute's value.
470 Called to get the value of the named extended attribute.
475 Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0).
479 Arguments: Pathname, extended attribute's name
480 Returns an errno or 0 on success.
484 Mark Glines, E<lt>mark@glines.orgE<gt>
488 L<perl>, the FUSE documentation.