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 my $fuse_version = fuse_version();
77 if ($fuse_version >= 2.3) {
78 push(@names, qw/opendir readdir releasedir fsyncdir init destroy/);
80 if ($fuse_version >= 2.5) {
81 push(@names, qw/access create ftruncate fgetattr/);
83 if ($fuse_version >= 2.6) {
84 push(@names, qw/lock utimens bmap/);
86 if ($fuse_version >= 2.8) {
87 # junk doesn't contain a function pointer, and hopefully
88 # never will; it's a "dead" zone in the struct
89 # fuse_operations where a flag bit is declared. we don't
90 # need to concern ourselves with it, and it appears any
91 # arch with a 64 bit pointer will align everything to
92 # 8 bytes, making the question of pointer alignment for
93 # the last 2 wrapper functions no big thing.
94 push(@names, qw/junk ioctl poll/);
96 my @subs = map {undef} @names;
98 my %mapping = map { $_ => $tmp++ } @names;
99 my @otherargs = qw(debug threaded mountpoint mountopts nullpath_ok utimens_as_array);
106 utimens_as_array => 0,
108 while(my $name = shift) {
109 my ($subref) = shift;
110 if(exists($otherargs{$name})) {
111 $otherargs{$name} = $subref;
113 croak "There is no function $name" unless exists($mapping{$name});
114 croak "Usage: Fuse::main(getattr => \"main::my_getattr\", ...)" unless $subref;
115 $subs[$mapping{$name}] = $subref;
118 if($otherargs{threaded}) {
119 # make sure threads are both available, and loaded.
120 if($Config{useithreads}) {
121 if(exists($threads::{VERSION})) {
122 if(exists($threads::shared::{VERSION})) {
125 carp("Thread support requires you to use threads::shared.\nThreads are disabled.\n");
126 $otherargs{threaded} = 0;
129 carp("Thread support requires you to use threads and threads::shared.\nThreads are disabled.\n");
130 $otherargs{threaded} = 0;
133 carp("Thread support was not compiled into this build of perl.\nThreads are disabled.\n");
134 $otherargs{threaded} = 0;
137 perl_fuse_main(@otherargs{@otherargs},@subs);
140 # Autoload methods go after =cut, and are processed by the autosplit program.
147 Fuse - write filesystems in Perl using FUSE
152 my ($mountpoint) = "";
153 $mountpoint = shift(@ARGV) if @ARGV;
154 Fuse::main(mountpoint=>$mountpoint, getattr=>"main::my_getattr", getdir=>"main::my_getdir", ...);
158 This lets you implement filesystems in perl, through the FUSE
159 (Filesystem in USErspace) kernel/lib interface.
161 FUSE expects you to implement callbacks for the various functions.
163 In the following definitions, "errno" can be 0 (for a success),
164 -EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really.
166 You can import standard error constants by saying something like
167 "use POSIX qw(EDOTDOT ENOANO);".
169 Every constant you need (file types, open() flags, error values,
170 etc) can be imported either from POSIX or from Fcntl, often both.
171 See their respective documentations, for more information.
173 =head2 EXPORTED SYMBOLS
177 You can request all exportable symbols by using the tag ":all".
179 You can request the extended attribute symbols by using the tag ":xattr".
180 This will export XATTR_CREATE and XATTR_REPLACE.
186 Takes arguments in the form of hash key=>value pairs. There are
187 many valid keys. Most of them correspond with names of callback
188 functions, as described in section 'FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT'.
189 A few special keys also exist:
193 =item debug => boolean
195 This turns FUSE call tracing on and off. Default is 0 (which means off).
197 =item mountpoint => string
199 The point at which to mount this filesystem. There is no default, you must
200 specify this. An example would be '/mnt'.
202 =item mountopts => string
204 This is a comma separated list of mount options to pass to the FUSE kernel
207 At present, it allows the specification of the allow_other
208 argument when mounting the new FUSE filesystem. To use this, you will also
209 need 'user_allow_other' in /etc/fuse.conf as per the FUSE documention
211 mountopts => "allow_other" or
214 =item threaded => boolean
216 This turns FUSE multithreading on and off. The default is 0, meaning your FUSE
217 script will run in single-threaded mode. Note that single-threaded mode also
218 means that you will not have to worry about reentrancy, though you will have to
219 worry about recursive lookups. In single-threaded mode, FUSE holds a global
220 lock on your filesystem, and will wait for one callback to return before
221 calling another. This can lead to deadlocks, if your script makes any attempt
222 to access files or directories in the filesystem it is providing. (This
223 includes calling stat() on the mount-point, statfs() calls from the 'df'
224 command, and so on and so forth.) It is worth paying a little attention and
225 being careful about this.
227 Enabling multithreading will cause FUSE to make multiple simultaneous calls
228 into the various callback functions of your perl script. If you enable
229 threaded mode, you can enjoy all the parallel execution and interactive
230 response benefits of threads, and you get to enjoy all the benefits of race
231 conditions and locking bugs, too. Please also ensure any other perl modules
232 you're using are also thread-safe.
234 (If enabled, this option will cause a warning if your perl interpreter was not
235 built with USE_ITHREADS, or if you have failed to use threads or
238 =item nullpath_ok => boolean
240 This flag tells Fuse to not pass paths for functions that operate on file
241 or directory handles. This will yield empty path parameters for functions
242 including read, write, flush, release, fsync, readdir, releasedir,
243 fsyncdir, truncate, fgetattr and lock. If you use this, you must return
244 file/directory handles from open, opendir and create. Default is 0 (off).
245 Only effective on Fuse 2.8 and up; with earlier versions, this does nothing.
247 =item utimens_as_array => boolean
249 This flag causes timestamps passed via the utimens() call to be passed
250 as arrays containing the time in seconds, and a second value containing
251 the number of nanoseconds, instead of a floating point value. This allows
252 for more precise times, as the normal floating point type used by Perl
253 (double) loses accuracy starting at about tenths of a microsecond.
257 =head3 Fuse::fuse_get_context
259 use Fuse "fuse_get_context";
260 my $caller_uid = fuse_get_context()->{"uid"};
261 my $caller_gid = fuse_get_context()->{"gid"};
262 my $caller_pid = fuse_get_context()->{"pid"};
264 Access context information about the current Fuse operation.
266 =head3 Fuse::fuse_version
268 Indicates the Fuse version in use; more accurately, indicates the version
269 of the Fuse API in use at build time. Returned as a decimal value; i.e.,
270 for Fuse API v2.6, will return "2.6".
272 =head3 Fuse::notify_poll
274 Only available if the Fuse module is built against libfuse 2.8 or later.
275 Use fuse_version() to determine if this is the case. Calling this function
276 with a pollhandle argument (as provided to the C<poll> operation
277 implementation) will send a notification to the caller poll()ing for
278 I/O operation availability. If more than one pollhandle is provided for
279 the same filehandle, only use the latest; you *can* send notifications
280 to them all, but it is unnecessary and decreases performance.
282 ONLY supply poll handles fed to you through C<poll> to this function.
283 Due to thread safety requirements, we can't currently package the pointer
284 up in an object the way we'd like to to prevent this situation, but your
285 filesystem server program may segfault, or worse, if you feed things to
286 this function which it is not supposed to receive. If you do anyway, we
287 take no responsibility for whatever Bad Things(tm) may happen.
289 =head3 Fuse::pollhandle_destroy
291 Only available if the Fuse module is built against libfuse 2.8 or later.
292 Use fuse_version() to determine if this is the case. This function destroys
293 a poll handle (fed to your program through C<poll>). When you are done
294 with a poll handle, either because it has been replaced, or because a
295 notification has been sent to it, pass it to this function to dispose of
298 ONLY supply poll handles fed to you through C<poll> to this function.
299 Due to thread safety requirements, we can't currently package the pointer
300 up in an object the way we'd like to to prevent this situation, but your
301 filesystem server program may segfault, or worse, if you feed things to
302 this function which it is not supposed to receive. If you do anyway, we
303 take no responsibility for whatever Bad Things(tm) may happen.
305 =head2 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT
311 Returns a list, very similar to the 'stat' function (see
312 perlfunc). On error, simply return a single numeric scalar
313 value (e.g. "return -ENOENT();").
315 FIXME: the "ino" field is currently ignored. I tried setting it to 0
316 in an example script, which consistently caused segfaults.
318 Fields (the following was stolen from perlfunc(1) with apologies):
320 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
321 $atime,$mtime,$ctime,$blksize,$blocks)
322 = getattr($filename);
324 Here are the meaning of the fields:
326 0 dev device number of filesystem
328 2 mode file mode (type and permissions)
329 3 nlink number of (hard) links to the file
330 4 uid numeric user ID of file's owner
331 5 gid numeric group ID of file's owner
332 6 rdev the device identifier (special files only)
333 7 size total size of file, in bytes
334 8 atime last access time in seconds since the epoch
335 9 mtime last modify time in seconds since the epoch
336 10 ctime inode change time (NOT creation time!) in seconds
338 11 blksize preferred block size for file system I/O
339 12 blocks actual number of blocks allocated
341 (The epoch was at 00:00 January 1, 1970 GMT.)
343 If you wish to provide sub-second precision timestamps, they may be
344 passed either as the fractional part of a floating-point value, or as a
345 two-element array, passed as an array ref, with the first element
346 containing the number of seconds since the epoch, and the second
347 containing the number of nanoseconds. This provides complete time
348 precision, as a floating point number starts losing precision at about
349 a tenth of a microsecond. So if you really care about that sort of thing...
353 Arguments: link pathname.
355 Returns a scalar: either a numeric constant, or a text string.
357 This is called when dereferencing symbolic links, to learn the target.
359 example rv: return "/proc/self/fd/stdin";
363 Arguments: Containing directory name.
365 Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0).
367 This is used to obtain directory listings. It's opendir(), readdir(), filldir() and closedir() all in one call.
369 example rv: return ('.', 'a', 'b', 0);
373 Arguments: Filename, numeric modes, numeric device
375 Returns an errno (0 upon success, as usual).
377 This function is called for all non-directory, non-symlink nodes,
382 Arguments: New directory pathname, numeric modes.
386 Called to create a directory.
394 Called to remove a file, device, or symlink.
402 Called to remove a directory.
406 Arguments: Existing filename, symlink name.
410 Called to create a symbolic link.
414 Arguments: old filename, new filename.
418 Called to rename a file, and/or move a file from one directory to another.
422 Arguments: Existing filename, hardlink name.
426 Called to create hard links.
430 Arguments: Pathname, numeric modes.
434 Called to change permissions on a file/directory/device/symlink.
438 Arguments: Pathname, numeric uid, numeric gid.
442 Called to change ownership of a file/directory/device/symlink.
446 Arguments: Pathname, numeric offset.
450 Called to truncate a file, at the given offset.
454 Arguments: Pathname, numeric actime, numeric modtime.
458 Called to change access/modification times for a file/directory/device/symlink.
462 Arguments: Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY
463 and O_SYNC, constants you can import from POSIX), fileinfo hash reference.
465 Returns an errno, a file handle (optional).
467 No creation, or truncation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open().
468 The fileinfo hash reference contains flags from the Fuse open call which may be modified by the module. The only fields presently supported are:
469 direct_io (version 2.4 onwards)
470 keep_cache (version 2.4 onwards)
471 nonseekable (version 2.8 onwards)
472 Your open() method needs only check if the operation is permitted for the given flags, and return 0 for success.
473 Optionally a file handle may be returned, which will be passed to subsequent read, write, flush, fsync and release calls.
477 Arguments: Pathname, numeric requested size, numeric offset, file handle
479 Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data.
481 Called in an attempt to fetch a portion of the file.
485 Arguments: Pathname, scalar buffer, numeric offset, file handle. You can use length($buffer) to
487 Returns length($buffer) if successful (number of bytes written).
489 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.
495 Returns any of the following:
501 $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
505 -ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
509 Arguments: Pathname, file handle
511 Returns an errno or 0 on success.
513 Called to synchronise any cached data. This is called before the file
514 is closed. It may be called multiple times before a file is closed.
518 Arguments: Pathname, numeric flags passed to open, file handle
520 Returns an errno or 0 on success.
522 Called to indicate that there are no more references to the file. Called once
523 for every file with the same pathname and flags as were passed to open.
527 Arguments: Pathname, numeric flags
529 Returns an errno or 0 on success.
531 Called to synchronise the file's contents. If flags is non-zero,
532 only synchronise the user data. Otherwise synchronise the user and meta data.
536 Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE
538 Returns an errno or 0 on success.
540 Called to set the value of the named extended attribute.
542 If you wish to reject setting of a particular form of extended attribute name
543 (e.g.: regexps matching user\..* or security\..*), then return - EOPNOTSUPP.
545 If flags is set to XATTR_CREATE and the extended attribute already exists,
546 this should fail with - EEXIST. If flags is set to XATTR_REPLACE
547 and the extended attribute doesn't exist, this should fail with - ENOATTR.
549 XATTR_CREATE and XATTR_REPLACE are provided by this module, but not exported
550 by default. To import them:
560 Arguments: Pathname, extended attribute's name
562 Returns an errno, 0 if there was no value, or the extended attribute's value.
564 Called to get the value of the named extended attribute.
570 Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0).
574 Arguments: Pathname, extended attribute's name
576 Returns an errno or 0 on success.
578 Removes the named extended attribute (if present) from a file.
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. By default,
698 times are passed as "numeric" (internally these are typically represented
699 as "double"), so the sub-second portion is represented as fractions of a
700 second. If you want times passed as arrays instead of floating point
701 values, for higher precision, you should pass the C<utimens_as_array> option
704 Note that if this call is implemented, it overrides utime() ALWAYS.
708 Arguments: Pathname, numeric blocksize, numeric block number
710 Returns errno or 0 on success, and physical block number if successful
712 Used to map a block number offset in a file to the physical block offset
713 on the block device backing the file system. This is intended for
714 filesystems that are stored on an actual block device, with the 'blkdev'
719 Arguments: Pathname, ioctl command code, flags, data if ioctl op is a write, (optional) file handle
721 Returns errno or 0 on success, and data if ioctl op is a read
723 Used to handle ioctl() operations on files. See ioctl(2) for more
724 information on the fine details of ioctl operation numbers. May need to
725 h2ph system headers to get the necessary macros; keep in mind the macros
726 are highly OS-dependent.
728 Keep in mind that read and write are from the client perspective, so
729 read from our end means data is going *out*, and write means data is
730 coming *in*. It can be slightly confusing.
734 Arguments: Pathname, poll handle ID (or undef if none), event mask, (optional) file handle
736 Returns errno or 0 on success, and updated event mask on success
738 Used to handle poll() operations on files. See poll(2) to learn more about
739 event polling. Use IO::Poll to get the POLLIN, POLLOUT, and other symbols
740 to describe the events which can happen on the filehandle. Save the poll
741 handle ID to be passed to C<notify_poll> and C<pollhandle_destroy>
742 functions, if it is not undef. Threading will likely be necessary for this
745 There is not an "out of band" data transfer channel provided as part of
746 FUSE, so POLLPRI/POLLRDBAND/POLLWRBAND won't work.
748 Poll handle is currently a read-only scalar; we are investigating a way
749 to make this an object instead.
753 Mark Glines, E<lt>mark@glines.orgE<gt>
757 L<perl>, the FUSE documentation.