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(XATTR_CREATE XATTR_REPLACE fuse_get_context fuse_version FUSE_IOCTL_COMPAT FUSE_IOCTL_UNRESTRICTED FUSE_IOCTL_RETRY FUSE_IOCTL_MAX_IOV) ],
24 'xattr' => [ qw(XATTR_CREATE XATTR_REPLACE) ],
25 'ioctl' => [ qw(FUSE_IOCTL_COMPAT FUSE_IOCTL_UNRESTRICTED FUSE_IOCTL_RETRY FUSE_IOCTL_MAX_IOV) ],
28 if (fuse_version() >= 2.8) {
29 push(@{$EXPORT_TAGS{'all'}}, qw(notify_poll pollhandle_destroy));
31 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
34 our $VERSION = '0.14';
37 # This AUTOLOAD is used to 'autoload' constants from the constant()
38 # XS function. If a constant is not found then control is passed
39 # to the AUTOLOAD in AutoLoader.
43 ($constname = $AUTOLOAD) =~ s/.*:://;
44 croak "& not defined" if $constname eq 'constant';
45 my $val = constant($constname, @_ ? $_[0] : 0);
48 $AutoLoader::AUTOLOAD = $AUTOLOAD;
49 goto &AutoLoader::AUTOLOAD;
52 croak "Your vendor has not defined Fuse macro $constname";
57 # Fixed between 5.005_53 and 5.005_61
59 *$AUTOLOAD = sub () { $val };
62 *$AUTOLOAD = sub { $val };
68 bootstrap Fuse $VERSION;
70 use constant FUSE_IOCTL_COMPAT => (1 << 0);
71 use constant FUSE_IOCTL_UNRESTRICTED => (1 << 1);
72 use constant FUSE_IOCTL_RETRY => (1 << 2);
73 use constant FUSE_IOCTL_MAX_IOV => 256;
76 my @names = qw(getattr readlink getdir mknod mkdir unlink rmdir symlink
77 rename link chmod chown truncate utime open read write statfs
78 flush release fsync setxattr getxattr listxattr removexattr);
79 my $fuse_version = fuse_version();
80 if ($fuse_version >= 2.3) {
81 push(@names, qw/opendir readdir releasedir fsyncdir init destroy/);
83 if ($fuse_version >= 2.5) {
84 push(@names, qw/access create ftruncate fgetattr/);
86 if ($fuse_version >= 2.6) {
87 push(@names, qw/lock utimens bmap/);
89 if ($fuse_version >= 2.8) {
90 # junk doesn't contain a function pointer, and hopefully
91 # never will; it's a "dead" zone in the struct
92 # fuse_operations where a flag bit is declared. we don't
93 # need to concern ourselves with it, and it appears any
94 # arch with a 64 bit pointer will align everything to
95 # 8 bytes, making the question of pointer alignment for
96 # the last 2 wrapper functions no big thing.
97 push(@names, qw/junk ioctl poll/);
99 my @subs = map {undef} @names;
101 my %mapping = map { $_ => $tmp++ } @names;
102 my @otherargs = qw(debug threaded mountpoint mountopts nullpath_ok);
110 while(my $name = shift) {
111 my ($subref) = shift;
112 if(exists($otherargs{$name})) {
113 $otherargs{$name} = $subref;
115 croak "There is no function $name" unless exists($mapping{$name});
116 croak "Usage: Fuse::main(getattr => \"main::my_getattr\", ...)" unless $subref;
117 $subs[$mapping{$name}] = $subref;
120 if($otherargs{threaded}) {
121 # make sure threads are both available, and loaded.
122 if($Config{useithreads}) {
123 if(exists($threads::{VERSION})) {
124 if(exists($threads::shared::{VERSION})) {
127 carp("Thread support requires you to use threads::shared.\nThreads are disabled.\n");
128 $otherargs{threaded} = 0;
131 carp("Thread support requires you to use threads and threads::shared.\nThreads are disabled.\n");
132 $otherargs{threaded} = 0;
135 carp("Thread support was not compiled into this build of perl.\nThreads are disabled.\n");
136 $otherargs{threaded} = 0;
139 perl_fuse_main(@otherargs{@otherargs},@subs);
142 # Autoload methods go after =cut, and are processed by the autosplit program.
149 Fuse - write filesystems in Perl using FUSE
154 my ($mountpoint) = "";
155 $mountpoint = shift(@ARGV) if @ARGV;
156 Fuse::main(mountpoint=>$mountpoint, getattr=>"main::my_getattr", getdir=>"main::my_getdir", ...);
160 This lets you implement filesystems in perl, through the FUSE
161 (Filesystem in USErspace) kernel/lib interface.
163 FUSE expects you to implement callbacks for the various functions.
165 In the following definitions, "errno" can be 0 (for a success),
166 -EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really.
168 You can import standard error constants by saying something like
169 "use POSIX qw(EDOTDOT ENOANO);".
171 Every constant you need (file types, open() flags, error values,
172 etc) can be imported either from POSIX or from Fcntl, often both.
173 See their respective documentations, for more information.
175 =head2 EXPORTED SYMBOLS
179 You can request all exportable symbols by using the tag ":all".
181 You can request the extended attribute symbols by using the tag ":xattr".
182 This will export XATTR_CREATE and XATTR_REPLACE.
188 Takes arguments in the form of hash key=>value pairs. There are
189 many valid keys. Most of them correspond with names of callback
190 functions, as described in section 'FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT'.
191 A few special keys also exist:
198 This turns FUSE call tracing on and off. Default is 0 (which means off).
206 The point at which to mount this filesystem. There is no default, you must
207 specify this. An example would be '/mnt'.
215 This is a comma seperated list of mount options to pass to the FUSE kernel
218 At present, it allows the specification of the allow_other
219 argument when mounting the new FUSE filesystem. To use this, you will also
220 need 'user_allow_other' in /etc/fuse.conf as per the FUSE documention
222 mountopts => "allow_other" or
231 This turns FUSE multithreading on and off. The default is 0, meaning your FUSE
232 script will run in single-threaded mode. Note that single-threaded mode also
233 means that you will not have to worry about reentrancy, though you will have to
234 worry about recursive lookups. In single-threaded mode, FUSE holds a global
235 lock on your filesystem, and will wait for one callback to return before
236 calling another. This can lead to deadlocks, if your script makes any attempt
237 to access files or directories in the filesystem it is providing. (This
238 includes calling stat() on the mount-point, statfs() calls from the 'df'
239 command, and so on and so forth.) It is worth paying a little attention and
240 being careful about this.
242 Enabling multithreading will cause FUSE to make multiple simultaneous calls
243 into the various callback functions of your perl script. If you enable
244 threaded mode, you can enjoy all the parallel execution and interactive
245 response benefits of threads, and you get to enjoy all the benefits of race
246 conditions and locking bugs, too. Please also ensure any other perl modules
247 you're using are also thread-safe.
249 (If enabled, this option will cause a warning if your perl interpreter was not
250 built with USE_ITHREADS, or if you have failed to use threads or
255 nullpath_ok => boolean
259 This flag tells Fuse to not pass paths for functions that operate on file
260 or directory handles. This will yield empty path parameters for functions
261 including read, write, flush, release, fsync, readdir, releasedir,
262 fsyncdir, truncate, fgetattr and lock. If you use this, you must return
263 file/directory handles from open, opendir and create. Default is 0 (off).
264 Only effective on Fuse 2.8 and up; with earlier versions, this does nothing.
268 =head3 Fuse::fuse_get_context
270 use Fuse "fuse_get_context";
271 my $caller_uid = fuse_get_context()->{"uid"};
272 my $caller_gid = fuse_get_context()->{"gid"};
273 my $caller_pid = fuse_get_context()->{"pid"};
275 Access context information about the current Fuse operation.
277 =head3 Fuse::fuse_version
279 Indicates the Fuse version in use; more accurately, indicates the version
280 of the Fuse API in use at build time. Returned as a decimal value; i.e.,
281 for Fuse API v2.6, will return "2.6".
283 =head3 Fuse::notify_poll
285 Only available if the Fuse module is built against libfuse 2.8 or later.
286 Use fuse_version() to determine if this is the case. Calling this function
287 with a pollhandle argument (as provided to the C<poll> operation
288 implementation) will send a notification to the caller poll()ing for
289 I/O operation availability. If more than one pollhandle is provided for
290 the same filehandle, only use the latest; you *can* send notifications
291 to them all, but it is unnecessary and decreases performance.
293 ONLY supply poll handles fed to you through C<poll> to this function.
294 Due to thread safety requirements, we can't currently package the pointer
295 up in an object the way we'd like to to prevent this situation, but your
296 filesystem server program may segfault, or worse, if you feed things to
297 this function which it is not supposed to receive. If you do anyway, we
298 take no responsibility for whatever Bad Things(tm) may happen.
300 =head3 Fuse::pollhandle_destroy
302 Only available if the Fuse module is built against libfuse 2.8 or later.
303 Use fuse_version() to determine if this is the case. This function destroys
304 a poll handle (fed to your program through C<poll>). When you are done
305 with a poll handle, either because it has been replaced, or because a
306 notification has been sent to it, pass it to this function to dispose of
309 ONLY supply poll handles fed to you through C<poll> to this function.
310 Due to thread safety requirements, we can't currently package the pointer
311 up in an object the way we'd like to to prevent this situation, but your
312 filesystem server program may segfault, or worse, if you feed things to
313 this function which it is not supposed to receive. If you do anyway, we
314 take no responsibility for whatever Bad Things(tm) may happen.
316 =head2 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT
322 Returns a list, very similar to the 'stat' function (see
323 perlfunc). On error, simply return a single numeric scalar
324 value (e.g. "return -ENOENT();").
326 FIXME: the "ino" field is currently ignored. I tried setting it to 0
327 in an example script, which consistently caused segfaults.
329 Fields (the following was stolen from perlfunc(1) with apologies):
331 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
332 $atime,$mtime,$ctime,$blksize,$blocks)
333 = getattr($filename);
335 Here are the meaning of the fields:
337 0 dev device number of filesystem
339 2 mode file mode (type and permissions)
340 3 nlink number of (hard) links to the file
341 4 uid numeric user ID of file's owner
342 5 gid numeric group ID of file's owner
343 6 rdev the device identifier (special files only)
344 7 size total size of file, in bytes
345 8 atime last access time in seconds since the epoch
346 9 mtime last modify time in seconds since the epoch
347 10 ctime inode change time (NOT creation time!) in seconds
349 11 blksize preferred block size for file system I/O
350 12 blocks actual number of blocks allocated
352 (The epoch was at 00:00 January 1, 1970 GMT.)
356 Arguments: link pathname.
358 Returns a scalar: either a numeric constant, or a text string.
360 This is called when dereferencing symbolic links, to learn the target.
362 example rv: return "/proc/self/fd/stdin";
366 Arguments: Containing directory name.
368 Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0).
370 This is used to obtain directory listings. It's opendir(), readdir(), filldir() and closedir() all in one call.
372 example rv: return ('.', 'a', 'b', 0);
376 Arguments: Filename, numeric modes, numeric device
378 Returns an errno (0 upon success, as usual).
380 This function is called for all non-directory, non-symlink nodes,
385 Arguments: New directory pathname, numeric modes.
389 Called to create a directory.
397 Called to remove a file, device, or symlink.
405 Called to remove a directory.
409 Arguments: Existing filename, symlink name.
413 Called to create a symbolic link.
417 Arguments: old filename, new filename.
421 Called to rename a file, and/or move a file from one directory to another.
425 Arguments: Existing filename, hardlink name.
429 Called to create hard links.
433 Arguments: Pathname, numeric modes.
437 Called to change permissions on a file/directory/device/symlink.
441 Arguments: Pathname, numeric uid, numeric gid.
445 Called to change ownership of a file/directory/device/symlink.
449 Arguments: Pathname, numeric offset.
453 Called to truncate a file, at the given offset.
457 Arguments: Pathname, numeric actime, numeric modtime.
461 Called to change access/modification times for a file/directory/device/symlink.
465 Arguments: Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY
466 and O_SYNC, constants you can import from POSIX), fileinfo hash reference.
468 Returns an errno, a file handle (optional).
470 No creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open().
471 The fileinfo hash reference contains flags from the Fuse open call which may be modified by the module. The only fields presently supported are:
472 direct_io (version 2.4 onwards)
473 keep_cache (version 2.4 onwards)
474 nonseekable (version 2.9 onwards)
475 Your open() method needs only check if the operation is permitted for the given flags, and return 0 for success.
476 Optionally a file handle may be returned, which will be passed to subsequent read, write, flush, fsync and release calls.
480 Arguments: Pathname, numeric requested size, numeric offset, file handle
482 Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data.
484 Called in an attempt to fetch a portion of the file.
488 Arguments: Pathname, scalar buffer, numeric offset, file handle. You can use length($buffer) to
490 Returns length($buffer) if successful (number of bytes written).
492 Called in an attempt to write (or overwrite) a portion of the file. Be prepared because $buffer could contain random binary data with NULs and all sorts of other wonderful stuff.
498 Returns any of the following:
504 $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
508 -ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
512 Arguments: Pathname, file handle
514 Returns an errno or 0 on success.
516 Called to synchronise any cached data. This is called before the file
517 is closed. It may be called multiple times before a file is closed.
521 Arguments: Pathname, numeric flags passed to open, file handle
522 Returns an errno or 0 on success.
524 Called to indicate that there are no more references to the file. Called once
525 for every file with the same pathname and flags as were passed to open.
529 Arguments: Pathname, numeric flags
531 Returns an errno or 0 on success.
533 Called to synchronise the file's contents. If flags is non-zero,
534 only synchronise the user data. Otherwise synchronise the user and meta data.
538 Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE
540 Returns an errno or 0 on success.
542 Called to set the value of the named extended attribute.
544 If you wish to reject setting of a particular form of extended attribute name
545 (e.g.: regexps matching user\..* or security\..*), then return - EOPNOTSUPP.
547 If flags is set to XATTR_CREATE and the extended attribute already exists,
548 this should fail with - EEXIST. If flags is set to XATTR_REPLACE
549 and the extended attribute doesn't exist, this should fail with - ENOATTR.
551 XATTR_CREATE and XATTR_REPLACE are provided by this module, but not exported
552 by default. To import them:
562 Arguments: Pathname, extended attribute's name
564 Returns an errno, 0 if there was no value, or the extended attribute's value.
566 Called to get the value of the named extended attribute.
572 Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0).
576 Arguments: Pathname, extended attribute's name
578 Returns an errno or 0 on success.
582 Arguments: Pathname of a directory
583 Returns an errno, and a directory handle (optional)
585 Called when opening a directory for reading. If special handling is
586 required to open a directory, this operation can be implemented to handle
591 Arguments: Pathname of a directory, numeric offset, (optional) directory handle
593 Returns a list of 0 or more entries, followed by a numeric errno (usually 0).
594 The entries can be simple strings (filenames), or arrays containing an
595 offset number, the filename, and optionally an array ref containing the
596 stat values (as would be returned from getattr()).
598 This is used to read entries from a directory. It can be used to return just
599 entry names like getdir(), or can get a segment of the available entries,
600 which requires using array refs and the 2- or 3-item form, with offset values
601 starting from 1. If you wish to return the parameters to fill each entry's
602 struct stat, but do not wish to do partial entry lists/entry counting, set
603 the first element of each array to 0 always.
605 Note that if this call is implemented, it overrides getdir() ALWAYS.
609 Arguments: Pathname of a directory, (optional) directory handle
611 Returns an errno or 0 on success
613 Called when there are no more references to an opened directory. Called once
614 for each pathname or handle passed to opendir(). Similar to release(), but
615 for directories. Accepts a return value, but like release(), the response
616 code will not propagate to any corresponding closedir() calls.
620 Arguments: Pathname of a directory, numeric flags, (optional) directory handle
622 Returns an errno or 0 on success.
624 Called to synchronize any changes to a directory's contents. If flag is
625 non-zero, only synchronize user data, otherwise synchronize user data and
632 Returns (optionally) an SV to be passed as private_data via fuse_get_context().
636 Arguments: (optional) private data SV returned from init(), if any.
642 Arguments: Pathname, access mode flags
644 Returns an errno or 0 on success.
646 Determine if the user attempting to access the indicated file has access to
647 perform the requested actions. The user ID can be determined by calling
648 fuse_get_context(). See access(2) for more information.
652 Arguments: Pathname, create mask, open mode flags
654 Returns errno or 0 on success, and (optional) file handle.
656 Create a file with the path indicated, then open a handle for reading and/or
657 writing with the supplied mode flags. Can also return a file handle like
658 open() as part of the call.
662 Arguments: Pathname, numeric offset, (optional) file handle
664 Returns errno or 0 on success
666 Like truncate(), but on an opened file.
670 Arguments: Pathname, (optional) file handle
672 Returns a list, very similar to the 'stat' function (see
673 perlfunc). On error, simply return a single numeric scalar
674 value (e.g. "return -ENOENT();").
676 Like getattr(), but on an opened file.
680 Arguments: Pathname, numeric command code, hashref containing lock parameters, (optional) file handle
682 Returns errno or 0 on success
684 Used to lock or unlock regions of a file. Locking is handled locally, but this
685 allows (especially for networked file systems) for protocol-level locking
686 semantics to also be employed, if any are available.
688 See the Fuse documentation for more explanation of lock(). The needed symbols
689 for the lock constants can be obtained by importing Fcntl.
693 Arguments: Pathname, last accessed time, last modified time
695 Returns errno or 0 on success
697 Like utime(), but allows time resolution down to the nanosecond. Currently
698 times are passed as "numeric" (internally I believe these are represented
699 typically as "long double"), so the sub-second portion is represented as
700 fractions of a second.
702 Note that if this call is implemented, it overrides utime() ALWAYS.
706 Arguments: Pathname, numeric blocksize, numeric block number
708 Returns errno or 0 on success, and physical block number if successful
710 Used to map a block number offset in a file to the physical block offset
711 on the block device backing the file system. This is intended for
712 filesystems that are stored on an actual block device, with the 'blkdev'
717 Arguments: Pathname, (signed) ioctl command code, flags, data if ioctl op is a write, (optional) file handle
719 Returns errno or 0 on success, and data if ioctl op is a read
721 Used to handle ioctl() operations on files. See ioctl(2) for more
722 information on the fine details of ioctl operation numbers. May need to
723 h2ph system headers to get the necessary macros; keep in mind the macros
724 are highly OS-dependent.
726 Keep in mind that read and write are from the client perspective, so
727 read from our end means data is going *out*, and write means data is
728 coming *in*. It can be slightly confusing.
732 Arguments: Pathname, poll handle ID (or undef if none), event mask, (optional) file handle
734 Returns errno or 0 on success, and updated event mask on success
736 Used to handle poll() operations on files. See poll(2) to learn more about
737 event polling. Use IO::Poll to get the POLLIN, POLLOUT, and other symbols
738 to describe the events which can happen on the filehandle. Save the poll
739 handle ID to be passed to C<notify_poll> and C<pollhandle_destroy>
740 functions, if it is not undef. Threading will likely be necessary for this
743 There is not an "out of band" data transfer channel provided as part of
744 FUSE, so POLLPRI/POLLRDBAND/POLLWRBAND won't work.
746 Poll handle is currently a read-only scalar; we are investigating a way
747 to make this an object instead.
751 Mark Glines, E<lt>mark@glines.orgE<gt>
755 L<perl>, the FUSE documentation.