# 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.12';
+our $VERSION = '0.14';
sub AUTOLOAD {
# This AUTOLOAD is used to 'autoload' constants from the constant()
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
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/);
-# }
+ 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).
+=item debug => boolean
-=back
-
-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
+=item mountopts => string
-=over 1
-
-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.
=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
=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
=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
=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
=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
=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
=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();").
=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
=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
=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
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>