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
# 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.11';
+our $VERSION = '0.14';
sub AUTOLOAD {
# This AUTOLOAD is used to 'autoload' constants from the constant()
goto &$AUTOLOAD;
}
-sub XATTR_CREATE {
- # See <sys/xattr.h>.
- return 1;
-}
-
-sub XATTR_REPLACE {
- # See <sys/xattr.h>.
- 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 opendir readdir releasedir fsyncdir);
+ 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;
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
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
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
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<poll> 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<poll> 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<poll>). 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<poll> 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();").
(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.
=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. It's opendir(), readdir(), filldir() and closedir() all in one call.
example rv: return ('.', 'a', 'b', 0);
-=head3 readdir
-
-Arguments: Directory name, offset
-Returns: filename, offset to the next dirent, numeric errno 0 or -ENOENT()
-
=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,
=head3 mkdir
Arguments: New directory pathname, numeric modes.
+
Returns an errno.
Called to create a directory.
=head3 unlink
Arguments: Filename.
+
Returns an errno.
Called to remove a file, device, or symlink.
=head3 rmdir
Arguments: Pathname.
+
Returns an errno.
Called to remove a directory.
=head3 symlink
Arguments: Existing filename, symlink name.
+
Returns an errno.
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.
=head3 link
Arguments: Existing filename, hardlink name.
+
Returns an errno.
Called to create hard links.
=head3 chmod
Arguments: Pathname, numeric modes.
+
Returns an errno.
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.
=head3 truncate
Arguments: Pathname, numeric offset.
+
Returns an errno.
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.
Arguments: Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY
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)
=head3 read
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 statfs
Arguments: none
+
Returns any of the following:
-ENOANO()
=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
=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,
=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.
=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.
+
+=head3 ioctl
+
+Arguments: Pathname, (signed) 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<notify_poll> and C<pollhandle_destroy>
+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, E<lt>mark@glines.orgE<gt>