X-Git-Url: http://git.rot13.org/?a=blobdiff_plain;f=Fuse.pm;h=f1061ead64bdf4c0bbac734b8b1a4584c141015f;hb=e6ca93074661d3d28f01d3cc96d00a252952803e;hp=0cf443357bc0ec6f8e1c05f26351d6ba7498ea54;hpb=68a77227e4290ac2cb4927db088205a3b5b3e011;p=perl-fuse.git diff --git a/Fuse.pm b/Fuse.pm old mode 100644 new mode 100755 index 0cf4433..f1061ea --- a/Fuse.pm +++ b/Fuse.pm @@ -10,7 +10,6 @@ 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 @@ -21,14 +20,15 @@ our @ISA = qw(Exporter DynaLoader); # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK # will save memory. our %EXPORT_TAGS = ( - 'all' => [ qw(XATTR_CREATE XATTR_REPLACE) ], - 'xattr' => [ qw(XATTR_CREATE XATTR_REPLACE) ] + '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) ], + 'xattr' => [ qw(XATTR_CREATE XATTR_REPLACE) ], + 'ioctl' => [ qw(FUSE_IOCTL_COMPAT FUSE_IOCTL_UNRESTRICTED FUSE_IOCTL_RETRY FUSE_IOCTL_MAX_IOV) ], ); our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); our @EXPORT = (); -our $VERSION = '0.07_4'; +our $VERSION = '0.14'; sub AUTOLOAD { # This AUTOLOAD is used to 'autoload' constants from the constant() @@ -62,29 +62,49 @@ sub AUTOLOAD { goto &$AUTOLOAD; } -sub XATTR_CREATE { - # See . - return 1; -} - -sub XATTR_REPLACE { - # See . - return 2; -} - bootstrap Fuse $VERSION; +use constant FUSE_IOCTL_COMPAT => (1 << 0); +use constant FUSE_IOCTL_UNRESTRICTED => (1 << 1); +use constant FUSE_IOCTL_RETRY => (1 << 2); +use constant FUSE_IOCTL_MAX_IOV => 256; + sub main { 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 @validOpts = qw(ro allow_other default_permissions fsname use_ino nonempty); my $tmp = 0; my %mapping = map { $_ => $tmp++ } @names; - my %optmap = map { $_ => 1 } @validOpts; - my @otherargs = qw(debug threaded mountpoint mountopts); - my %otherargs = (debug=>0, threaded=>0, mountpoint=>"", mountopts=>""); + my @otherargs = qw(debug threaded mountpoint mountopts nullpath_ok utimens_as_array); + my %otherargs = ( + debug => 0, + threaded => 0, + mountpoint => "", + mountopts => "", + nullpath_ok => 0, + utimens_as_array => 0, + ); while(my $name = shift) { my ($subref) = shift; if(exists($otherargs{$name})) { @@ -95,10 +115,6 @@ sub main { $subs[$mapping{$name}] = $subref; } } - foreach my $opt ( map {m/^([^=]*)/; $1} split(/,/,$otherargs{mountopts}) ) { - next if exists($optmap{$opt}); - croak "Fuse::main: invalid '$opt' argument in mountopts"; - } if($otherargs{threaded}) { # make sure threads are both available, and loaded. if($Config{useithreads}) { @@ -172,29 +188,20 @@ many valid keys. Most of them correspond with names of callback functions, as described in section 'FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT'. A few special keys also exist: - -debug => boolean - =over 1 -This turns FUSE call tracing on and off. Default is 0 (which means off). - -=back +=item debug => boolean -mountpoint => string +This turns FUSE call tracing on and off. Default is 0 (which means off). -=over 1 +=item mountpoint => string The point at which to mount this filesystem. There is no default, you must specify this. An example would be '/mnt'. -=back - -mountopts => string - -=over 1 +=item mountopts => string -This is a comma seperated list of mount options to pass to the FUSE kernel +This is a comma separated list of mount options to pass to the FUSE kernel module. At present, it allows the specification of the allow_other @@ -204,11 +211,7 @@ need 'user_allow_other' in /etc/fuse.conf as per the FUSE documention mountopts => "allow_other" or mountopts => "" -=back - -threaded => boolean - -=over 1 +=item threaded => boolean 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 @@ -232,13 +235,79 @@ you're using are also thread-safe. built with USE_ITHREADS, or if you have failed to use threads or threads::shared.) +=item nullpath_ok => boolean + +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. + +=item utimens_as_array => boolean + +This flag causes timestamps passed via the utimens() call to be passed +as arrays containing the time in seconds, and a second value containing +the number of nanoseconds, instead of a floating point value. This allows +for more precise times, as the normal floating point type used by Perl +(double) loses accuracy starting at about tenths of a microsecond. + =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". + +=head3 Fuse::notify_poll + +Only available if the Fuse module is built against libfuse 2.8 or later. +Use fuse_version() to determine if this is the case. Calling this function +with a pollhandle argument (as provided to the C operation +implementation) will send a notification to the caller poll()ing for +I/O operation availability. If more than one pollhandle is provided for +the same filehandle, only use the latest; you *can* send notifications +to them all, but it is unnecessary and decreases performance. + +ONLY supply poll handles fed to you through C to this function. +Due to thread safety requirements, we can't currently package the pointer +up in an object the way we'd like to to prevent this situation, but your +filesystem server program may segfault, or worse, if you feed things to +this function which it is not supposed to receive. If you do anyway, we +take no responsibility for whatever Bad Things(tm) may happen. + +=head3 Fuse::pollhandle_destroy + +Only available if the Fuse module is built against libfuse 2.8 or later. +Use fuse_version() to determine if this is the case. This function destroys +a poll handle (fed to your program through C). When you are done +with a poll handle, either because it has been replaced, or because a +notification has been sent to it, pass it to this function to dispose of +it safely. + +ONLY supply poll handles fed to you through C to this function. +Due to thread safety requirements, we can't currently package the pointer +up in an object the way we'd like to to prevent this situation, but your +filesystem server program may segfault, or worse, if you feed things to +this function which it is not supposed to receive. If you do anyway, we +take no responsibility for whatever Bad Things(tm) may happen. + =head2 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT =head3 getattr Arguments: filename. + Returns a list, very similar to the 'stat' function (see perlfunc). On error, simply return a single numeric scalar value (e.g. "return -ENOENT();"). @@ -271,9 +340,18 @@ Here are the meaning of the fields: (The epoch was at 00:00 January 1, 1970 GMT.) +If you wish to provide sub-second precision timestamps, they may be +passed either as the fractional part of a floating-point value, or as a +two-element array, passed as an array ref, with the first element +containing the number of seconds since the epoch, and the second +containing the number of nanoseconds. This provides complete time +precision, as a floating point number starts losing precision at about +a tenth of a microsecond. So if you really care about that sort of thing... + =head3 readlink Arguments: link pathname. + Returns a scalar: either a numeric constant, or a text string. This is called when dereferencing symbolic links, to learn the target. @@ -283,15 +361,17 @@ example rv: return "/proc/self/fd/stdin"; =head3 getdir 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); =head3 mknod Arguments: Filename, numeric modes, numeric device + Returns an errno (0 upon success, as usual). This function is called for all non-directory, non-symlink nodes, @@ -300,6 +380,7 @@ not just devices. =head3 mkdir Arguments: New directory pathname, numeric modes. + Returns an errno. Called to create a directory. @@ -307,6 +388,7 @@ Called to create a directory. =head3 unlink Arguments: Filename. + Returns an errno. Called to remove a file, device, or symlink. @@ -314,6 +396,7 @@ Called to remove a file, device, or symlink. =head3 rmdir Arguments: Pathname. + Returns an errno. Called to remove a directory. @@ -321,6 +404,7 @@ Called to remove a directory. =head3 symlink Arguments: Existing filename, symlink name. + Returns an errno. Called to create a symbolic link. @@ -328,6 +412,7 @@ Called to create a symbolic link. =head3 rename Arguments: old filename, new filename. + Returns an errno. Called to rename a file, and/or move a file from one directory to another. @@ -335,6 +420,7 @@ Called to rename a file, and/or move a file from one directory to another. =head3 link Arguments: Existing filename, hardlink name. + Returns an errno. Called to create hard links. @@ -342,6 +428,7 @@ Called to create hard links. =head3 chmod Arguments: Pathname, numeric modes. + Returns an errno. Called to change permissions on a file/directory/device/symlink. @@ -349,6 +436,7 @@ Called to change permissions on a file/directory/device/symlink. =head3 chown Arguments: Pathname, numeric uid, numeric gid. + Returns an errno. Called to change ownership of a file/directory/device/symlink. @@ -356,6 +444,7 @@ Called to change ownership of a file/directory/device/symlink. =head3 truncate Arguments: Pathname, numeric offset. + Returns an errno. Called to truncate a file, at the given offset. @@ -363,6 +452,7 @@ Called to truncate a file, at the given offset. =head3 utime Arguments: Pathname, numeric actime, numeric modtime. + Returns an errno. Called to change access/modification times for a file/directory/device/symlink. @@ -370,30 +460,38 @@ 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. -No creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open(). +Returns an errno, a file handle (optional). + +No creation, or truncation 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.8 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 Arguments: none + Returns any of the following: -ENOANO() @@ -408,7 +506,8 @@ or =head3 flush -Arguments: Pathname +Arguments: Pathname, file handle + Returns an errno or 0 on success. Called to synchronise any cached data. This is called before the file @@ -416,7 +515,8 @@ is closed. It may be called multiple times before a file is closed. =head3 release -Arguments: Pathname, numeric flags passed to open +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 @@ -425,6 +525,7 @@ 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, @@ -433,6 +534,7 @@ 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. @@ -456,6 +558,7 @@ or: =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. @@ -463,13 +566,188 @@ 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. +Removes the named extended attribute (if present) from a file. + +=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. By default, +times are passed as "numeric" (internally these are typically represented +as "double"), so the sub-second portion is represented as fractions of a +second. If you want times passed as arrays instead of floating point +values, for higher precision, you should pass the C option +to C. + +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. + +=head3 ioctl + +Arguments: Pathname, ioctl command code, flags, data if ioctl op is a write, (optional) file handle + +Returns errno or 0 on success, and data if ioctl op is a read + +Used to handle ioctl() operations on files. See ioctl(2) for more +information on the fine details of ioctl operation numbers. May need to +h2ph system headers to get the necessary macros; keep in mind the macros +are highly OS-dependent. + +Keep in mind that read and write are from the client perspective, so +read from our end means data is going *out*, and write means data is +coming *in*. It can be slightly confusing. + +=head3 poll + +Arguments: Pathname, poll handle ID (or undef if none), event mask, (optional) file handle + +Returns errno or 0 on success, and updated event mask on success + +Used to handle poll() operations on files. See poll(2) to learn more about +event polling. Use IO::Poll to get the POLLIN, POLLOUT, and other symbols +to describe the events which can happen on the filehandle. Save the poll +handle ID to be passed to C and C +functions, if it is not undef. Threading will likely be necessary for this +operation to work. + +There is not an "out of band" data transfer channel provided as part of +FUSE, so POLLPRI/POLLRDBAND/POLLWRBAND won't work. + +Poll handle is currently a read-only scalar; we are investigating a way +to make this an object instead. + =head1 AUTHOR Mark Glines, Emark@glines.orgE