X-Git-Url: http://git.rot13.org/?p=perl-fuse.git;a=blobdiff_plain;f=Fuse.pm;h=708fedf05bd5a9499da7b03fc4da21632c4356d2;hp=e7bf1e03ef3335a34743478c6162022f73cb08c6;hb=c872ed31deaaa06128547ff845ea2dd669e953fa;hpb=2c3682bf309dac408db9ee2e30f91a2c8f832ef4 diff --git a/Fuse.pm b/Fuse.pm old mode 100644 new mode 100755 index e7bf1e0..708fedf --- a/Fuse.pm +++ b/Fuse.pm @@ -5,11 +5,11 @@ use strict; use warnings; use Errno; use Carp; +use Config; require Exporter; require DynaLoader; use AutoLoader; -use Data::Dumper; our @ISA = qw(Exporter DynaLoader); # Items to export into callers namespace by default. Note: do not export @@ -19,16 +19,15 @@ our @ISA = qw(Exporter DynaLoader); # This allows declaration use Fuse ':all'; # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK # will save memory. -our %EXPORT_TAGS = ( 'all' => [ qw( - FUSE_DEBUG -) ] ); +our %EXPORT_TAGS = ( + 'all' => [ qw(XATTR_CREATE XATTR_REPLACE fuse_get_context fuse_version) ], + 'xattr' => [ qw(XATTR_CREATE XATTR_REPLACE) ] + ); our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); -our @EXPORT = qw( - FUSE_DEBUG -); -our $VERSION = '0.05'; +our @EXPORT = (); +our $VERSION = '0.13'; sub AUTOLOAD { # This AUTOLOAD is used to 'autoload' constants from the constant() @@ -65,25 +64,70 @@ sub AUTOLOAD { bootstrap Fuse $VERSION; sub main { - my (@subs) = (0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0); - my (@names) = qw(getattr readlink getdir mknod mkdir unlink rmdir symlink - rename link chmod chown truncate utime open read write statfs); - my ($tmp) = 0; - my (%mapping) = map { $_ => $tmp++ } (@names); - my (%otherargs) = (debug=>0, mountpoint=>""); + my @names = qw(getattr readlink getdir mknod mkdir unlink rmdir symlink + rename link chmod chown truncate utime open read write statfs + flush release fsync setxattr getxattr listxattr removexattr); + my $fuse_version = fuse_version(); + if ($fuse_version >= 2.3) { + push(@names, qw/opendir readdir releasedir fsyncdir init destroy/); + } + if ($fuse_version >= 2.5) { + push(@names, qw/access create ftruncate fgetattr/); + } + if ($fuse_version >= 2.6) { + push(@names, qw/lock utimens bmap/); + } +# if ($fuse_version >= 2.8) { +# # junk doesn't contain a function pointer, and hopefully +# # never will; it's a "dead" zone in the struct +# # fuse_operations where a flag bit is declared. we don't +# # need to concern ourselves with it, and it appears any +# # arch with a 64 bit pointer will align everything to +# # 8 bytes, making the question of pointer alignment for +# # the last 2 wrapper functions no big thing. +# push(@names, qw/junk ioctl poll/); +# } + my @subs = map {undef} @names; + my $tmp = 0; + my %mapping = map { $_ => $tmp++ } @names; + my @otherargs = qw(debug threaded mountpoint mountopts nullpath_ok); + my %otherargs = ( + debug => 0, + threaded => 0, + mountpoint => "", + mountopts => "", + nullpath_ok => 0, + ); while(my $name = shift) { my ($subref) = shift; if(exists($otherargs{$name})) { $otherargs{$name} = $subref; } else { croak "There is no function $name" unless exists($mapping{$name}); - croak "Usage: Fuse::main(getattr => &my_getattr, ...)" unless $subref; - croak "Usage: Fuse::main(getattr => &my_getattr, ...)" unless ref($subref); - croak "Usage: Fuse::main(getattr => &my_getattr, ...)" unless ref($subref) eq "CODE"; + croak "Usage: Fuse::main(getattr => \"main::my_getattr\", ...)" unless $subref; $subs[$mapping{$name}] = $subref; } } - perl_fuse_main($otherargs{debug},$otherargs{mountpoint},@subs); + if($otherargs{threaded}) { + # make sure threads are both available, and loaded. + if($Config{useithreads}) { + if(exists($threads::{VERSION})) { + if(exists($threads::shared::{VERSION})) { + # threads will work. + } else { + carp("Thread support requires you to use threads::shared.\nThreads are disabled.\n"); + $otherargs{threaded} = 0; + } + } else { + carp("Thread support requires you to use threads and threads::shared.\nThreads are disabled.\n"); + $otherargs{threaded} = 0; + } + } else { + carp("Thread support was not compiled into this build of perl.\nThreads are disabled.\n"); + $otherargs{threaded} = 0; + } + } + perl_fuse_main(@otherargs{@otherargs},@subs); } # Autoload methods go after =cut, and are processed by the autosplit program. @@ -100,7 +144,7 @@ Fuse - write filesystems in Perl using FUSE use Fuse; my ($mountpoint) = ""; $mountpoint = shift(@ARGV) if @ARGV; - Fuse::main(mountpoint=>$mountpoint, getattr=>\&my_getattr, getdir=>\&my_getdir, ...); + Fuse::main(mountpoint=>$mountpoint, getattr=>"main::my_getattr", getdir=>"main::my_getdir", ...); =head1 DESCRIPTION @@ -109,9 +153,6 @@ This lets you implement filesystems in perl, through the FUSE FUSE expects you to implement callbacks for the various functions. -NOTE: I have only tested the things implemented in example.pl! -It should work, but some things may not. - In the following definitions, "errno" can be 0 (for a success), -EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really. @@ -122,13 +163,14 @@ Every constant you need (file types, open() flags, error values, etc) can be imported either from POSIX or from Fcntl, often both. See their respective documentations, for more information. -=head2 EXPORT +=head2 EXPORTED SYMBOLS None by default. -=head2 EXPORTABLE CONSTANTS +You can request all exportable symbols by using the tag ":all". -None. +You can request the extended attribute symbols by using the tag ":xattr". +This will export XATTR_CREATE and XATTR_REPLACE. =head2 FUNCTIONS @@ -157,26 +199,78 @@ specify this. An example would be '/mnt'. =back -unthreaded => boolean +mountopts => string + +=over 1 + +This is a comma seperated list of mount options to pass to the FUSE kernel +module. + +At present, it allows the specification of the allow_other +argument when mounting the new FUSE filesystem. To use this, you will also +need 'user_allow_other' in /etc/fuse.conf as per the FUSE documention + + mountopts => "allow_other" or + mountopts => "" + +=back + +threaded => boolean =over 1 -This turns FUSE multithreading off and on. NOTE: This perlmodule does not -currently work properly in multithreaded mode! The author is unfortunately -not familiar enough with perl-threads internals, and according to the -documentation available at time of writing (2002-03-08), those internals are -subject to changing anyway. Note that singlethreaded mode also means that -you will not have to worry about reentrancy, though you will have to worry -about recursive lookups (since the kernel holds a global lock on your -filesystem and blocks waiting for one callback to complete before calling -another). +This turns FUSE multithreading on and off. The default is 0, meaning your FUSE +script will run in single-threaded mode. Note that single-threaded mode also +means that you will not have to worry about reentrancy, though you will have to +worry about recursive lookups. In single-threaded mode, FUSE holds a global +lock on your filesystem, and will wait for one callback to return before +calling another. This can lead to deadlocks, if your script makes any attempt +to access files or directories in the filesystem it is providing. (This +includes calling stat() on the mount-point, statfs() calls from the 'df' +command, and so on and so forth.) It is worth paying a little attention and +being careful about this. + +Enabling multithreading will cause FUSE to make multiple simultaneous calls +into the various callback functions of your perl script. If you enable +threaded mode, you can enjoy all the parallel execution and interactive +response benefits of threads, and you get to enjoy all the benefits of race +conditions and locking bugs, too. Please also ensure any other perl modules +you're using are also thread-safe. + +(If enabled, this option will cause a warning if your perl interpreter was not +built with USE_ITHREADS, or if you have failed to use threads or +threads::shared.) + +=back + +nullpath_ok => boolean -I hope to add full multithreading functionality later, but for now, I -recommend you leave this option at the default, 1 (which means -unthreaded, no threads will be used and no reentrancy is needed). +=over 1 + +This flag tells Fuse to not pass paths for functions that operate on file +or directory handles. This will yield empty path parameters for functions +including read, write, flush, release, fsync, readdir, releasedir, +fsyncdir, truncate, fgetattr and lock. If you use this, you must return +file/directory handles from open, opendir and create. Default is 0 (off). +Only effective on Fuse 2.8 and up; with earlier versions, this does nothing. =back +=head3 Fuse::fuse_get_context + + use Fuse "fuse_get_context"; + my $caller_uid = fuse_get_context()->{"uid"}; + my $caller_gid = fuse_get_context()->{"gid"}; + my $caller_pid = fuse_get_context()->{"pid"}; + +Access context information about the current Fuse operation. + +=head3 Fuse::fuse_version + +Indicates the Fuse version in use; more accurately, indicates the version +of the Fuse API in use at build time. Returned as a decimal value; i.e., +for Fuse API v2.6, will return "2.6". + =head2 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT =head3 getattr @@ -228,7 +322,7 @@ example rv: return "/proc/self/fd/stdin"; Arguments: Containing directory name. Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0). -This is used to obtain directory listings. Its opendir(), readdir(), filldir() and closedir() all in one call. +This is used to obtain directory listings. It's opendir(), readdir(), filldir() and closedir() all in one call. example rv: return ('.', 'a', 'b', 0); @@ -313,26 +407,31 @@ Called to change access/modification times for a file/directory/device/symlink. =head3 open Arguments: Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY -and O_SYNC, constants you can import from POSIX). -Returns an errno. +and O_SYNC, constants you can import from POSIX), fileinfo hash reference. +Returns an errno, a file handle (optional). No creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open(). +The fileinfo hash reference contains flags from the Fuse open call which may be modified by the module. The only fields presently supported are: + direct_io (version 2.4 onwards) + keep_cache (version 2.4 onwards) + nonseekable (version 2.9 onwards) Your open() method needs only check if the operation is permitted for the given flags, and return 0 for success. +Optionally a file handle may be returned, which will be passed to subsequent read, write, flush, fsync and release calls. =head3 read -Arguments: Pathname, numeric requestedsize, numeric offset. +Arguments: Pathname, numeric requested size, numeric offset, file handle Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data. Called in an attempt to fetch a portion of the file. =head3 write -Arguments: Pathname, scalar buffer, numeric offset. You can use length($buffer) to +Arguments: Pathname, scalar buffer, numeric offset, file handle. You can use length($buffer) to find the buffersize. -Returns an errno. +Returns length($buffer) if successful (number of bytes written). -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. +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. =head3 statfs @@ -349,6 +448,193 @@ or -ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize +=head3 flush + +Arguments: Pathname, file handle +Returns an errno or 0 on success. + +Called to synchronise any cached data. This is called before the file +is closed. It may be called multiple times before a file is closed. + +=head3 release + +Arguments: Pathname, numeric flags passed to open, file handle +Returns an errno or 0 on success. + +Called to indicate that there are no more references to the file. Called once +for every file with the same pathname and flags as were passed to open. + +=head3 fsync + +Arguments: Pathname, numeric flags +Returns an errno or 0 on success. + +Called to synchronise the file's contents. If flags is non-zero, +only synchronise the user data. Otherwise synchronise the user and meta data. + +=head3 setxattr + +Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE +Returns an errno or 0 on success. + +Called to set the value of the named extended attribute. + +If you wish to reject setting of a particular form of extended attribute name +(e.g.: regexps matching user\..* or security\..*), then return - EOPNOTSUPP. + +If flags is set to XATTR_CREATE and the extended attribute already exists, +this should fail with - EEXIST. If flags is set to XATTR_REPLACE +and the extended attribute doesn't exist, this should fail with - ENOATTR. + +XATTR_CREATE and XATTR_REPLACE are provided by this module, but not exported +by default. To import them: + + use Fuse ':xattr'; + +or: + + use Fuse ':all'; + +=head3 getxattr + +Arguments: Pathname, extended attribute's name +Returns an errno, 0 if there was no value, or the extended attribute's value. + +Called to get the value of the named extended attribute. + +=head3 listxattr + +Arguments: Pathname +Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0). + +=head3 removexattr + +Arguments: Pathname, extended attribute's name +Returns an errno or 0 on success. + +=head3 opendir + +Arguments: Pathname of a directory +Returns an errno, and a directory handle (optional) + +Called when opening a directory for reading. If special handling is +required to open a directory, this operation can be implemented to handle +that. + +=head3 readdir + +Arguments: Pathname of a directory, numeric offset, (optional) directory handle +Returns a list of 0 or more entries, followed by a numeric errno (usually 0). +The entries can be simple strings (filenames), or arrays containing an +offset number, the filename, and optionally an array ref containing the +stat values (as would be returned from getattr()). + +This is used to read entries from a directory. It can be used to return just +entry names like getdir(), or can get a segment of the available entries, +which requires using array refs and the 2- or 3-item form, with offset values +starting from 1. If you wish to return the parameters to fill each entry's +struct stat, but do not wish to do partial entry lists/entry counting, set +the first element of each array to 0 always. + +Note that if this call is implemented, it overrides getdir() ALWAYS. + +=head3 releasedir + +Arguments: Pathname of a directory, (optional) directory handle +Returns an errno or 0 on success + +Called when there are no more references to an opened directory. Called once +for each pathname or handle passed to opendir(). Similar to release(), but +for directories. Accepts a return value, but like release(), the response +code will not propagate to any corresponding closedir() calls. + +=head3 fsyncdir + +Arguments: Pathname of a directory, numeric flags, (optional) directory handle +Returns an errno or 0 on success. + +Called to synchronize any changes to a directory's contents. If flag is +non-zero, only synchronize user data, otherwise synchronize user data and +metadata. + +=head3 init + +Arguments: None. +Returns (optionally) an SV to be passed as private_data via fuse_get_context(). + +=head3 destroy + +Arguments: (optional) private data SV returned from init(), if any. +Returns nothing. + +=head3 access + +Arguments: Pathname, access mode flags +Returns an errno or 0 on success. + +Determine if the user attempting to access the indicated file has access to +perform the requested actions. The user ID can be determined by calling +fuse_get_context(). See access(2) for more information. + +=head3 create + +Arguments: Pathname, create mask, open mode flags +Returns errno or 0 on success, and (optional) file handle. + +Create a file with the path indicated, then open a handle for reading and/or +writing with the supplied mode flags. Can also return a file handle like +open() as part of the call. + +=head3 ftruncate + +Arguments: Pathname, numeric offset, (optional) file handle +Returns errno or 0 on success + +Like truncate(), but on an opened file. + +=head3 fgetattr + +Arguments: Pathname, (optional) file handle +Returns a list, very similar to the 'stat' function (see +perlfunc). On error, simply return a single numeric scalar +value (e.g. "return -ENOENT();"). + +Like getattr(), but on an opened file. + +=head3 lock + +Arguments: Pathname, numeric command code, hashref containing lock parameters, (optional) file handle +Returns errno or 0 on success + +Used to lock or unlock regions of a file. Locking is handled locally, but this +allows (especially for networked file systems) for protocol-level locking +semantics to also be employed, if any are available. + +See the Fuse documentation for more explanation of lock(). The needed symbols +for the lock constants can be obtained by importing Fcntl. + +=head3 utimens + +Arguments: Pathname, last accessed time, last modified time +Returns errno or 0 on success + +Like utime(), but allows time resolution down to the nanosecond. Currently +times are passed as "numeric" (internally I believe these are represented +typically as "long double"), so the sub-second portion is represented as +fractions of a second. + +Note that if this call is implemented, it overrides utime() ALWAYS. + +=head3 bmap + +Arguments: Pathname, numeric blocksize, numeric block number +Returns errno or 0 on success, and physical block number if successful + +Used to map a block number offset in a file to the physical block offset +on the block device backing the file system. This is intended for +filesystems that are stored on an actual block device, with the 'blkdev' +option passed. + =head1 AUTHOR Mark Glines, Emark@glines.orgE