X-Git-Url: http://git.rot13.org/?a=blobdiff_plain;f=Fuse.pm;h=53ac10993f7caccc22e5cfb084a4f27ff8a8ee7f;hb=48e91793fca961bcf8c0cda9b62aa9deb722a45a;hp=1e3573d7443a127c478838be9f65200a0dfa0761;hpb=a407dfe21750b50b58defff2408b5c79d5e5803e;p=perl-fuse.git diff --git a/Fuse.pm b/Fuse.pm index 1e3573d..53ac109 100755 --- a/Fuse.pm +++ b/Fuse.pm @@ -20,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 fuse_get_context fuse_version) ], - '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.14'; +our $VERSION = '0.15'; sub AUTOLOAD { # This AUTOLOAD is used to 'autoload' constants from the constant() @@ -63,6 +64,11 @@ sub AUTOLOAD { 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 @@ -85,19 +91,19 @@ sub main { # 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/); -# push(@names, qw/junk ioctl poll/); + 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 = qw(debug threaded mountpoint mountopts nullpath_ok utimens_as_array); my %otherargs = ( - debug => 0, - threaded => 0, - mountpoint => "", - mountopts => "", - nullpath_ok => 0, + debug => 0, + threaded => 0, + mountpoint => "", + mountopts => "", + nullpath_ok => 0, + utimens_as_array => 0, ); while(my $name = shift) { my ($subref) = shift; @@ -182,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 @@ -214,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 @@ -242,11 +235,7 @@ you're using are also thread-safe. built with USE_ITHREADS, or if you have failed to use threads or threads::shared.) -=back - -nullpath_ok => boolean - -=over 1 +=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 @@ -255,6 +244,14 @@ 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 @@ -272,6 +269,39 @@ 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 @@ -310,6 +340,14 @@ 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. @@ -426,11 +464,11 @@ 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(). +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.9 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. @@ -478,6 +516,7 @@ 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 @@ -536,6 +575,8 @@ 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 @@ -653,10 +694,12 @@ 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. +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. @@ -673,7 +716,7 @@ option passed. =head3 ioctl -Arguments: Pathname, (signed) ioctl command code, flags, data if ioctl op is a write, (optional) file handle +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 @@ -686,6 +729,25 @@ 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