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 notify_poll pollhandle_destroy) ],
24 'xattr' => [ qw(XATTR_CREATE XATTR_REPLACE) ],
25 'ioctl' => [ qw(FUSE_IOCTL_COMPAT FUSE_IOCTL_UNRESTRICTED FUSE_IOCTL_RETRY FUSE_IOCTL_MAX_IOV) ],
28 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
31 our $VERSION = '0.15';
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 };
65 bootstrap Fuse $VERSION;
67 use constant FUSE_IOCTL_COMPAT => (1 << 0);
68 use constant FUSE_IOCTL_UNRESTRICTED => (1 << 1);
69 use constant FUSE_IOCTL_RETRY => (1 << 2);
70 use constant FUSE_IOCTL_MAX_IOV => 256;
73 my @names = qw(getattr readlink getdir mknod mkdir unlink rmdir symlink
74 rename link chmod chown truncate utime open read write statfs
75 flush release fsync setxattr getxattr listxattr removexattr
76 opendir readdir releasedir fsyncdir init destroy access
77 create ftruncate fgetattr lock utimens bmap);
78 my $fuse_version = fuse_version();
79 if ($fuse_version >= 2.8) {
80 # junk doesn't contain a function pointer, and hopefully
81 # never will; it's a "dead" zone in the struct
82 # fuse_operations where a flag bit is declared. we don't
83 # need to concern ourselves with it, and it appears any
84 # arch with a 64 bit pointer will align everything to
85 # 8 bytes, making the question of pointer alignment for
86 # the last 2 wrapper functions no big thing.
87 push(@names, qw/junk ioctl poll/);
89 my @subs = map {undef} @names;
91 my %mapping = map { $_ => $tmp++ } @names;
92 my @otherargs = qw(debug threaded mountpoint mountopts nullpath_ok utimens_as_array);
99 utimens_as_array => 0,
101 while(my $name = shift) {
102 my ($subref) = shift;
103 if(exists($otherargs{$name})) {
104 $otherargs{$name} = $subref;
106 croak "There is no function $name" unless exists($mapping{$name});
107 croak "Usage: Fuse::main(getattr => \"main::my_getattr\", ...)" unless $subref;
108 $subs[$mapping{$name}] = $subref;
111 if($otherargs{threaded}) {
112 # make sure threads are both available, and loaded.
113 if($Config{useithreads}) {
114 if(exists($threads::{VERSION})) {
115 if(exists($threads::shared::{VERSION})) {
118 carp("Thread support requires you to use threads::shared.\nThreads are disabled.\n");
119 $otherargs{threaded} = 0;
122 carp("Thread support requires you to use threads and threads::shared.\nThreads are disabled.\n");
123 $otherargs{threaded} = 0;
126 carp("Thread support was not compiled into this build of perl.\nThreads are disabled.\n");
127 $otherargs{threaded} = 0;
130 perl_fuse_main(@otherargs{@otherargs},@subs);
133 # Autoload methods go after =cut, and are processed by the autosplit program.
140 Fuse - write filesystems in Perl using FUSE
145 my ($mountpoint) = "";
146 $mountpoint = shift(@ARGV) if @ARGV;
147 Fuse::main(mountpoint=>$mountpoint, getattr=>"main::my_getattr", getdir=>"main::my_getdir", ...);
151 This lets you implement filesystems in perl, through the FUSE
152 (Filesystem in USErspace) kernel/lib interface.
154 FUSE expects you to implement callbacks for the various functions.
156 In the following definitions, "errno" can be 0 (for a success),
157 -EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really.
159 You can import standard error constants by saying something like
160 "use POSIX qw(EDOTDOT ENOANO);".
162 Every constant you need (file types, open() flags, error values,
163 etc) can be imported either from POSIX or from Fcntl, often both.
164 See their respective documentations, for more information.
166 =head2 EXPORTED SYMBOLS
170 You can request all exportable symbols by using the tag ":all".
172 You can request the extended attribute symbols by using the tag ":xattr".
173 This will export XATTR_CREATE and XATTR_REPLACE.
179 Takes arguments in the form of hash key=>value pairs. There are
180 many valid keys. Most of them correspond with names of callback
181 functions, as described in section 'FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT'.
182 A few special keys also exist:
186 =item debug => boolean
188 This turns FUSE call tracing on and off. Default is 0 (which means off).
190 =item mountpoint => string
192 The point at which to mount this filesystem. There is no default, you must
193 specify this. An example would be '/mnt'.
195 =item mountopts => string
197 This is a comma separated 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
207 =item threaded => boolean
209 This turns FUSE multithreading on and off. The default is 0, meaning your FUSE
210 script will run in single-threaded mode. Note that single-threaded mode also
211 means that you will not have to worry about reentrancy, though you will have to
212 worry about recursive lookups. In single-threaded mode, FUSE holds a global
213 lock on your filesystem, and will wait for one callback to return before
214 calling another. This can lead to deadlocks, if your script makes any attempt
215 to access files or directories in the filesystem it is providing. (This
216 includes calling stat() on the mount-point, statfs() calls from the 'df'
217 command, and so on and so forth.) It is worth paying a little attention and
218 being careful about this.
220 Enabling multithreading will cause FUSE to make multiple simultaneous calls
221 into the various callback functions of your perl script. If you enable
222 threaded mode, you can enjoy all the parallel execution and interactive
223 response benefits of threads, and you get to enjoy all the benefits of race
224 conditions and locking bugs, too. Please also ensure any other perl modules
225 you're using are also thread-safe.
227 (If enabled, this option will cause a warning if your perl interpreter was not
228 built with USE_ITHREADS, or if you have failed to use threads or
231 =item nullpath_ok => boolean
233 This flag tells Fuse to not pass paths for functions that operate on file
234 or directory handles. This will yield empty path parameters for functions
235 including read, write, flush, release, fsync, readdir, releasedir,
236 fsyncdir, truncate, fgetattr and lock. If you use this, you must return
237 file/directory handles from open, opendir and create. Default is 0 (off).
238 Only effective on Fuse 2.8 and up; with earlier versions, this does nothing.
240 =item utimens_as_array => boolean
242 This flag causes timestamps passed via the utimens() call to be passed
243 as arrays containing the time in seconds, and a second value containing
244 the number of nanoseconds, instead of a floating point value. This allows
245 for more precise times, as the normal floating point type used by Perl
246 (double) loses accuracy starting at about tenths of a microsecond.
250 =head3 Fuse::fuse_get_context
252 use Fuse "fuse_get_context";
253 my $caller_uid = fuse_get_context()->{"uid"};
254 my $caller_gid = fuse_get_context()->{"gid"};
255 my $caller_pid = fuse_get_context()->{"pid"};
257 Access context information about the current Fuse operation.
259 =head3 Fuse::fuse_version
261 Indicates the Fuse version in use; more accurately, indicates the version
262 of the Fuse API in use at build time. Returned as a decimal value; i.e.,
263 for Fuse API v2.6, will return "2.6".
265 =head3 Fuse::notify_poll
267 Only available if the Fuse module is built against libfuse 2.8 or later.
268 Use fuse_version() to determine if this is the case. Calling this function
269 with a pollhandle argument (as provided to the C<poll> operation
270 implementation) will send a notification to the caller poll()ing for
271 I/O operation availability. If more than one pollhandle is provided for
272 the same filehandle, only use the latest; you *can* send notifications
273 to them all, but it is unnecessary and decreases performance.
275 ONLY supply poll handles fed to you through C<poll> to this function.
276 Due to thread safety requirements, we can't currently package the pointer
277 up in an object the way we'd like to to prevent this situation, but your
278 filesystem server program may segfault, or worse, if you feed things to
279 this function which it is not supposed to receive. If you do anyway, we
280 take no responsibility for whatever Bad Things(tm) may happen.
282 =head3 Fuse::pollhandle_destroy
284 Only available if the Fuse module is built against libfuse 2.8 or later.
285 Use fuse_version() to determine if this is the case. This function destroys
286 a poll handle (fed to your program through C<poll>). When you are done
287 with a poll handle, either because it has been replaced, or because a
288 notification has been sent to it, pass it to this function to dispose of
291 ONLY supply poll handles fed to you through C<poll> to this function.
292 Due to thread safety requirements, we can't currently package the pointer
293 up in an object the way we'd like to to prevent this situation, but your
294 filesystem server program may segfault, or worse, if you feed things to
295 this function which it is not supposed to receive. If you do anyway, we
296 take no responsibility for whatever Bad Things(tm) may happen.
298 =head2 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT
304 Returns a list, very similar to the 'stat' function (see
305 perlfunc). On error, simply return a single numeric scalar
306 value (e.g. "return -ENOENT();").
308 FIXME: the "ino" field is currently ignored. I tried setting it to 0
309 in an example script, which consistently caused segfaults.
311 Fields (the following was stolen from perlfunc(1) with apologies):
313 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
314 $atime,$mtime,$ctime,$blksize,$blocks)
315 = getattr($filename);
317 Here are the meaning of the fields:
319 0 dev device number of filesystem
321 2 mode file mode (type and permissions)
322 3 nlink number of (hard) links to the file
323 4 uid numeric user ID of file's owner
324 5 gid numeric group ID of file's owner
325 6 rdev the device identifier (special files only)
326 7 size total size of file, in bytes
327 8 atime last access time in seconds since the epoch
328 9 mtime last modify time in seconds since the epoch
329 10 ctime inode change time (NOT creation time!) in seconds
331 11 blksize preferred block size for file system I/O
332 12 blocks actual number of blocks allocated
334 (The epoch was at 00:00 January 1, 1970 GMT.)
336 If you wish to provide sub-second precision timestamps, they may be
337 passed either as the fractional part of a floating-point value, or as a
338 two-element array, passed as an array ref, with the first element
339 containing the number of seconds since the epoch, and the second
340 containing the number of nanoseconds. This provides complete time
341 precision, as a floating point number starts losing precision at about
342 a tenth of a microsecond. So if you really care about that sort of thing...
346 Arguments: link pathname.
348 Returns a scalar: either a numeric constant, or a text string.
350 This is called when dereferencing symbolic links, to learn the target.
352 example rv: return "/proc/self/fd/stdin";
356 Arguments: Containing directory name.
358 Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0).
360 This is used to obtain directory listings. It's opendir(), readdir(), filldir() and closedir() all in one call.
362 example rv: return ('.', 'a', 'b', 0);
366 Arguments: Filename, numeric modes, numeric device
368 Returns an errno (0 upon success, as usual).
370 This function is called for all non-directory, non-symlink nodes,
375 Arguments: New directory pathname, numeric modes.
379 Called to create a directory.
387 Called to remove a file, device, or symlink.
395 Called to remove a directory.
399 Arguments: Existing filename, symlink name.
403 Called to create a symbolic link.
407 Arguments: old filename, new filename.
411 Called to rename a file, and/or move a file from one directory to another.
415 Arguments: Existing filename, hardlink name.
419 Called to create hard links.
423 Arguments: Pathname, numeric modes.
427 Called to change permissions on a file/directory/device/symlink.
431 Arguments: Pathname, numeric uid, numeric gid.
435 Called to change ownership of a file/directory/device/symlink.
439 Arguments: Pathname, numeric offset.
443 Called to truncate a file, at the given offset.
447 Arguments: Pathname, numeric actime, numeric modtime.
451 Called to change access/modification times for a file/directory/device/symlink.
455 Arguments: Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY
456 and O_SYNC, constants you can import from POSIX), fileinfo hash reference.
458 Returns an errno, a file handle (optional).
460 No creation, or truncation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open().
461 The fileinfo hash reference contains flags from the Fuse open call which may be modified by the module. The only fields presently supported are:
462 direct_io (version 2.4 onwards)
463 keep_cache (version 2.4 onwards)
464 nonseekable (version 2.8 onwards)
465 Your open() method needs only check if the operation is permitted for the given flags, and return 0 for success.
466 Optionally a file handle may be returned, which will be passed to subsequent read, write, flush, fsync and release calls.
470 Arguments: Pathname, numeric requested size, numeric offset, file handle
472 Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data.
474 Called in an attempt to fetch a portion of the file.
478 Arguments: Pathname, scalar buffer, numeric offset, file handle. You can use length($buffer) to
480 Returns length($buffer) if successful (number of bytes written).
482 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.
488 Returns any of the following:
494 $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
498 -ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
502 Arguments: Pathname, file handle
504 Returns an errno or 0 on success.
506 Called to synchronise any cached data. This is called before the file
507 is closed. It may be called multiple times before a file is closed.
511 Arguments: Pathname, numeric flags passed to open, file handle
513 Returns an errno or 0 on success.
515 Called to indicate that there are no more references to the file. Called once
516 for every file with the same pathname and flags as were passed to open.
520 Arguments: Pathname, numeric flags
522 Returns an errno or 0 on success.
524 Called to synchronise the file's contents. If flags is non-zero,
525 only synchronise the user data. Otherwise synchronise the user and meta data.
529 Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE
531 Returns an errno or 0 on success.
533 Called to set the value of the named extended attribute.
535 If you wish to reject setting of a particular form of extended attribute name
536 (e.g.: regexps matching user\..* or security\..*), then return - EOPNOTSUPP.
538 If flags is set to XATTR_CREATE and the extended attribute already exists,
539 this should fail with - EEXIST. If flags is set to XATTR_REPLACE
540 and the extended attribute doesn't exist, this should fail with - ENOATTR.
542 XATTR_CREATE and XATTR_REPLACE are provided by this module, but not exported
543 by default. To import them:
553 Arguments: Pathname, extended attribute's name
555 Returns an errno, 0 if there was no value, or the extended attribute's value.
557 Called to get the value of the named extended attribute.
563 Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0).
567 Arguments: Pathname, extended attribute's name
569 Returns an errno or 0 on success.
571 Removes the named extended attribute (if present) from a file.
575 Arguments: Pathname of a directory
576 Returns an errno, and a directory handle (optional)
578 Called when opening a directory for reading. If special handling is
579 required to open a directory, this operation can be implemented to handle
584 Arguments: Pathname of a directory, numeric offset, (optional) directory handle
586 Returns a list of 0 or more entries, followed by a numeric errno (usually 0).
587 The entries can be simple strings (filenames), or arrays containing an
588 offset number, the filename, and optionally an array ref containing the
589 stat values (as would be returned from getattr()).
591 This is used to read entries from a directory. It can be used to return just
592 entry names like getdir(), or can get a segment of the available entries,
593 which requires using array refs and the 2- or 3-item form, with offset values
594 starting from 1. If you wish to return the parameters to fill each entry's
595 struct stat, but do not wish to do partial entry lists/entry counting, set
596 the first element of each array to 0 always.
598 Note that if this call is implemented, it overrides getdir() ALWAYS.
602 Arguments: Pathname of a directory, (optional) directory handle
604 Returns an errno or 0 on success
606 Called when there are no more references to an opened directory. Called once
607 for each pathname or handle passed to opendir(). Similar to release(), but
608 for directories. Accepts a return value, but like release(), the response
609 code will not propagate to any corresponding closedir() calls.
613 Arguments: Pathname of a directory, numeric flags, (optional) directory handle
615 Returns an errno or 0 on success.
617 Called to synchronize any changes to a directory's contents. If flag is
618 non-zero, only synchronize user data, otherwise synchronize user data and
625 Returns (optionally) an SV to be passed as private_data via fuse_get_context().
629 Arguments: (optional) private data SV returned from init(), if any.
635 Arguments: Pathname, access mode flags
637 Returns an errno or 0 on success.
639 Determine if the user attempting to access the indicated file has access to
640 perform the requested actions. The user ID can be determined by calling
641 fuse_get_context(). See access(2) for more information.
645 Arguments: Pathname, create mask, open mode flags
647 Returns errno or 0 on success, and (optional) file handle.
649 Create a file with the path indicated, then open a handle for reading and/or
650 writing with the supplied mode flags. Can also return a file handle like
651 open() as part of the call.
655 Arguments: Pathname, numeric offset, (optional) file handle
657 Returns errno or 0 on success
659 Like truncate(), but on an opened file.
663 Arguments: Pathname, (optional) file handle
665 Returns a list, very similar to the 'stat' function (see
666 perlfunc). On error, simply return a single numeric scalar
667 value (e.g. "return -ENOENT();").
669 Like getattr(), but on an opened file.
673 Arguments: Pathname, numeric command code, hashref containing lock parameters, (optional) file handle
675 Returns errno or 0 on success
677 Used to lock or unlock regions of a file. Locking is handled locally, but this
678 allows (especially for networked file systems) for protocol-level locking
679 semantics to also be employed, if any are available.
681 See the Fuse documentation for more explanation of lock(). The needed symbols
682 for the lock constants can be obtained by importing Fcntl.
686 Arguments: Pathname, last accessed time, last modified time
688 Returns errno or 0 on success
690 Like utime(), but allows time resolution down to the nanosecond. By default,
691 times are passed as "numeric" (internally these are typically represented
692 as "double"), so the sub-second portion is represented as fractions of a
693 second. If you want times passed as arrays instead of floating point
694 values, for higher precision, you should pass the C<utimens_as_array> option
697 Note that if this call is implemented, it overrides utime() ALWAYS.
701 Arguments: Pathname, numeric blocksize, numeric block number
703 Returns errno or 0 on success, and physical block number if successful
705 Used to map a block number offset in a file to the physical block offset
706 on the block device backing the file system. This is intended for
707 filesystems that are stored on an actual block device, with the 'blkdev'
712 Arguments: Pathname, ioctl command code, flags, data if ioctl op is a write, (optional) file handle
714 Returns errno or 0 on success, and data if ioctl op is a read
716 Used to handle ioctl() operations on files. See ioctl(2) for more
717 information on the fine details of ioctl operation numbers. May need to
718 h2ph system headers to get the necessary macros; keep in mind the macros
719 are highly OS-dependent.
721 Keep in mind that read and write are from the client perspective, so
722 read from our end means data is going *out*, and write means data is
723 coming *in*. It can be slightly confusing.
727 Arguments: Pathname, poll handle ID (or undef if none), event mask, (optional) file handle
729 Returns errno or 0 on success, and updated event mask on success
731 Used to handle poll() operations on files. See poll(2) to learn more about
732 event polling. Use IO::Poll to get the POLLIN, POLLOUT, and other symbols
733 to describe the events which can happen on the filehandle. Save the poll
734 handle ID to be passed to C<notify_poll> and C<pollhandle_destroy>
735 functions, if it is not undef. Threading will likely be necessary for this
738 There is not an "out of band" data transfer channel provided as part of
739 FUSE, so POLLPRI/POLLRDBAND/POLLWRBAND won't work.
741 Poll handle is currently a read-only scalar; we are investigating a way
742 to make this an object instead.
746 Mark Glines, E<lt>mark@glines.orgE<gt>
750 L<perl>, the FUSE documentation.