Fuse.pm

   1 package Fuse;
   2
   3 use 5.006;
   4 use strict;
   5 use warnings;
   6 use Errno;
   7 use Carp;
   8 use Config;
   9
  10 require Exporter;
  11 require DynaLoader;
  12 use AutoLoader;
  13 our @ISA = qw(Exporter DynaLoader);
  14
  15 # Items to export into callers namespace by default. Note: do not export
  16 # names by default without a very good reason. Use EXPORT_OK instead.
  17 # Do not simply export all your public functions/methods/constants.
  18
  19 # This allows declaration       use Fuse ':all';
  20 # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
  21 # will save memory.
  22 our %EXPORT_TAGS = (
  23                     '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) ],
  24                     'xattr' => [ qw(XATTR_CREATE XATTR_REPLACE) ],
  25                     'ioctl' => [ qw(FUSE_IOCTL_COMPAT FUSE_IOCTL_UNRESTRICTED FUSE_IOCTL_RETRY FUSE_IOCTL_MAX_IOV) ],
  26                     );
  27
  28 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
  29
  30 our @EXPORT = ();
  31 our $VERSION = '0.14';
  32
  33 sub AUTOLOAD {
  34     # This AUTOLOAD is used to 'autoload' constants from the constant()
  35     # XS function.  If a constant is not found then control is passed
  36     # to the AUTOLOAD in AutoLoader.
  37
  38     my $constname;
  39     our $AUTOLOAD;
  40     ($constname = $AUTOLOAD) =~ s/.*:://;
  41     croak "& not defined" if $constname eq 'constant';
  42     my $val = constant($constname, @_ ? $_[0] : 0);
  43     if ($! != 0) {
  44         if ($!{EINVAL}) {
  45             $AutoLoader::AUTOLOAD = $AUTOLOAD;
  46             goto &AutoLoader::AUTOLOAD;
  47         }
  48         else {
  49             croak "Your vendor has not defined Fuse macro $constname";
  50         }
  51     }
  52     {
  53         no strict 'refs';
  54         # Fixed between 5.005_53 and 5.005_61
  55         if ($] >= 5.00561) {
  56             *$AUTOLOAD = sub () { $val };
  57         }
  58         else {
  59             *$AUTOLOAD = sub { $val };
  60         }
  61     }
  62     goto &$AUTOLOAD;
  63 }
  64
  65 bootstrap Fuse $VERSION;
  66
  67 use constant FUSE_IOCTL_COMPAT          => (1 << 0);
  68 use constant FUSE_IOCTL_UNRESTRICTED    => (1 << 1);
  69 use constant FUSE_IOCTL_RETRY           => (1 << 2);
  70 use constant FUSE_IOCTL_MAX_IOV         => 256;
  71
  72 sub main {
  73         my @names = qw(getattr readlink getdir mknod mkdir unlink rmdir symlink
  74                         rename link chmod chown truncate utime open read write statfs
  75                         flush release fsync setxattr getxattr listxattr removexattr);
  76         my $fuse_version = fuse_version();
  77         if ($fuse_version >= 2.3) {
  78                 push(@names, qw/opendir readdir releasedir fsyncdir init destroy/);
  79         }
  80         if ($fuse_version >= 2.5) {
  81                 push(@names, qw/access create ftruncate fgetattr/);
  82         }
  83         if ($fuse_version >= 2.6) {
  84                 push(@names, qw/lock utimens bmap/);
  85         }
  86         if ($fuse_version >= 2.8) {
  87                 # junk doesn't contain a function pointer, and hopefully
  88                 # never will; it's a "dead" zone in the struct
  89                 # fuse_operations where a flag bit is declared. we don't
  90                 # need to concern ourselves with it, and it appears any
  91                 # arch with a 64 bit pointer will align everything to
  92                 # 8 bytes, making the question of pointer alignment for
  93                 # the last 2 wrapper functions no big thing.
  94                 push(@names, qw/junk ioctl poll/);
  95         }
  96         my @subs = map {undef} @names;
  97         my $tmp = 0;
  98         my %mapping = map { $_ => $tmp++ } @names;
  99         my @otherargs = qw(debug threaded mountpoint mountopts nullpath_ok);
 100         my %otherargs = (
 101                           debug         => 0,
 102                           threaded      => 0,
 103                           mountpoint    => "",
 104                           mountopts     => "",
 105                           nullpath_ok   => 0,
 106                         );
 107         while(my $name = shift) {
 108                 my ($subref) = shift;
 109                 if(exists($otherargs{$name})) {
 110                         $otherargs{$name} = $subref;
 111                 } else {
 112                         croak "There is no function $name" unless exists($mapping{$name});
 113                         croak "Usage: Fuse::main(getattr => \"main::my_getattr\", ...)" unless $subref;
 114                         $subs[$mapping{$name}] = $subref;
 115                 }
 116         }
 117         if($otherargs{threaded}) {
 118                 # make sure threads are both available, and loaded.
 119                 if($Config{useithreads}) {
 120                         if(exists($threads::{VERSION})) {
 121                                 if(exists($threads::shared::{VERSION})) {
 122                                         # threads will work.
 123                                 } else {
 124                                         carp("Thread support requires you to use threads::shared.\nThreads are disabled.\n");
 125                                         $otherargs{threaded} = 0;
 126                                 }
 127                         } else {
 128                                 carp("Thread support requires you to use threads and threads::shared.\nThreads are disabled.\n");
 129                                 $otherargs{threaded} = 0;
 130                         }
 131                 } else {
 132                         carp("Thread support was not compiled into this build of perl.\nThreads are disabled.\n");
 133                         $otherargs{threaded} = 0;
 134                 }
 135         }
 136         perl_fuse_main(@otherargs{@otherargs},@subs);
 137 }
 138
 139 # Autoload methods go after =cut, and are processed by the autosplit program.
 140
 141 1;
 142 __END__
 143
 144 =head1 NAME
 145
 146 Fuse - write filesystems in Perl using FUSE
 147
 148 =head1 SYNOPSIS
 149
 150   use Fuse;
 151   my ($mountpoint) = "";
 152   $mountpoint = shift(@ARGV) if @ARGV;
 153   Fuse::main(mountpoint=>$mountpoint, getattr=>"main::my_getattr", getdir=>"main::my_getdir", ...);
 154
 155 =head1 DESCRIPTION
 156
 157 This lets you implement filesystems in perl, through the FUSE
 158 (Filesystem in USErspace) kernel/lib interface.
 159
 160 FUSE expects you to implement callbacks for the various functions.
 161
 162 In the following definitions, "errno" can be 0 (for a success),
 163 -EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really.
 164
 165 You can import standard error constants by saying something like
 166 "use POSIX qw(EDOTDOT ENOANO);".
 167
 168 Every constant you need (file types, open() flags, error values,
 169 etc) can be imported either from POSIX or from Fcntl, often both.
 170 See their respective documentations, for more information.
 171
 172 =head2 EXPORTED SYMBOLS
 173
 174 None by default.
 175
 176 You can request all exportable symbols by using the tag ":all".
 177
 178 You can request the extended attribute symbols by using the tag ":xattr".
 179 This will export XATTR_CREATE and XATTR_REPLACE.
 180
 181 =head2 FUNCTIONS
 182
 183 =head3 Fuse::main
 184
 185 Takes arguments in the form of hash key=>value pairs.  There are
 186 many valid keys.  Most of them correspond with names of callback
 187 functions, as described in section 'FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT'.
 188 A few special keys also exist:
 189
 190 =over 1
 191
 192 =item debug => boolean
 193
 194 This turns FUSE call tracing on and off.  Default is 0 (which means off).
 195
 196 =item mountpoint => string
 197
 198 The point at which to mount this filesystem.  There is no default, you must
 199 specify this.  An example would be '/mnt'.
 200
 201 =item mountopts => string
 202
 203 This is a comma separated list of mount options to pass to the FUSE kernel
 204 module.
 205
 206 At present, it allows the specification of the allow_other
 207 argument when mounting the new FUSE filesystem. To use this, you will also
 208 need 'user_allow_other' in /etc/fuse.conf as per the FUSE documention
 209
 210   mountopts => "allow_other" or
 211   mountopts => ""
 212
 213 =item threaded => boolean
 214
 215 This turns FUSE multithreading on and off.  The default is 0, meaning your FUSE
 216 script will run in single-threaded mode.  Note that single-threaded mode also
 217 means that you will not have to worry about reentrancy, though you will have to
 218 worry about recursive lookups.  In single-threaded mode, FUSE holds a global
 219 lock on your filesystem, and will wait for one callback to return before
 220 calling another.  This can lead to deadlocks, if your script makes any attempt
 221 to access files or directories in the filesystem it is providing.  (This
 222 includes calling stat() on the mount-point, statfs() calls from the 'df'
 223 command, and so on and so forth.)  It is worth paying a little attention and
 224 being careful about this.
 225
 226 Enabling multithreading will cause FUSE to make multiple simultaneous calls
 227 into the various callback functions of your perl script.  If you enable
 228 threaded mode, you can enjoy all the parallel execution and interactive
 229 response benefits of threads, and you get to enjoy all the benefits of race
 230 conditions and locking bugs, too.  Please also ensure any other perl modules
 231 you're using are also thread-safe.
 232
 233 (If enabled, this option will cause a warning if your perl interpreter was not
 234 built with USE_ITHREADS, or if you have failed to use threads or
 235 threads::shared.)
 236
 237 =item nullpath_ok => boolean
 238
 239 This flag tells Fuse to not pass paths for functions that operate on file
 240 or directory handles. This will yield empty path parameters for functions
 241 including read, write, flush, release, fsync, readdir, releasedir,
 242 fsyncdir, truncate, fgetattr and lock. If you use this, you must return
 243 file/directory handles from open, opendir and create. Default is 0 (off).
 244 Only effective on Fuse 2.8 and up; with earlier versions, this does nothing.
 245
 246 =back
 247
 248 =head3 Fuse::fuse_get_context
 249
 250  use Fuse "fuse_get_context";
 251  my $caller_uid = fuse_get_context()->{"uid"};
 252  my $caller_gid = fuse_get_context()->{"gid"};
 253  my $caller_pid = fuse_get_context()->{"pid"};
 254
 255 Access context information about the current Fuse operation.
 256
 257 =head3 Fuse::fuse_version
 258
 259 Indicates the Fuse version in use; more accurately, indicates the version
 260 of the Fuse API in use at build time. Returned as a decimal value; i.e.,
 261 for Fuse API v2.6, will return "2.6".
 262
 263 =head3 Fuse::notify_poll
 264
 265 Only available if the Fuse module is built against libfuse 2.8 or later.
 266 Use fuse_version() to determine if this is the case. Calling this function
 267 with a pollhandle argument (as provided to the C<poll> operation
 268 implementation) will send a notification to the caller poll()ing for
 269 I/O operation availability. If more than one pollhandle is provided for
 270 the same filehandle, only use the latest; you *can* send notifications
 271 to them all, but it is unnecessary and decreases performance.
 272
 273 ONLY supply poll handles fed to you through C<poll> to this function.
 274 Due to thread safety requirements, we can't currently package the pointer
 275 up in an object the way we'd like to to prevent this situation, but your
 276 filesystem server program may segfault, or worse, if you feed things to
 277 this function which it is not supposed to receive. If you do anyway, we
 278 take no responsibility for whatever Bad Things(tm) may happen.
 279
 280 =head3 Fuse::pollhandle_destroy
 281
 282 Only available if the Fuse module is built against libfuse 2.8 or later.
 283 Use fuse_version() to determine if this is the case. This function destroys
 284 a poll handle (fed to your program through C<poll>). When you are done
 285 with a poll handle, either because it has been replaced, or because a
 286 notification has been sent to it, pass it to this function to dispose of
 287 it safely.
 288
 289 ONLY supply poll handles fed to you through C<poll> to this function.
 290 Due to thread safety requirements, we can't currently package the pointer
 291 up in an object the way we'd like to to prevent this situation, but your
 292 filesystem server program may segfault, or worse, if you feed things to
 293 this function which it is not supposed to receive. If you do anyway, we
 294 take no responsibility for whatever Bad Things(tm) may happen.
 295
 296 =head2 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT
 297
 298 =head3 getattr
 299
 300 Arguments:  filename.
 301
 302 Returns a list, very similar to the 'stat' function (see
 303 perlfunc).  On error, simply return a single numeric scalar
 304 value (e.g. "return -ENOENT();").
 305
 306 FIXME: the "ino" field is currently ignored.  I tried setting it to 0
 307 in an example script, which consistently caused segfaults.
 308
 309 Fields (the following was stolen from perlfunc(1) with apologies):
 310
 311 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
 312         $atime,$mtime,$ctime,$blksize,$blocks)
 313                          = getattr($filename);
 314
 315 Here are the meaning of the fields:
 316
 317  0 dev      device number of filesystem
 318  1 ino      inode number
 319  2 mode     file mode  (type and permissions)
 320  3 nlink    number of (hard) links to the file
 321  4 uid      numeric user ID of file's owner
 322  5 gid      numeric group ID of file's owner
 323  6 rdev     the device identifier (special files only)
 324  7 size     total size of file, in bytes
 325  8 atime    last access time in seconds since the epoch
 326  9 mtime    last modify time in seconds since the epoch
 327 10 ctime    inode change time (NOT creation time!) in seconds
 328             since the epoch
 329 11 blksize  preferred block size for file system I/O
 330 12 blocks   actual number of blocks allocated
 331
 332 (The epoch was at 00:00 January 1, 1970 GMT.)
 333
 334 If you wish to provide sub-second precision timestamps, they may be
 335 passed either as the fractional part of a floating-point value, or as a
 336 two-element array, passed as an array ref, with the first element
 337 containing the number of seconds since the epoch, and the second
 338 containing the number of nanoseconds. This provides complete time
 339 precision, as a floating point number starts losing precision at about
 340 a tenth of a microsecond. So if you really care about that sort of thing...
 341
 342 =head3 readlink
 343
 344 Arguments:  link pathname.
 345
 346 Returns a scalar: either a numeric constant, or a text string.
 347
 348 This is called when dereferencing symbolic links, to learn the target.
 349
 350 example rv: return "/proc/self/fd/stdin";
 351
 352 =head3 getdir
 353
 354 Arguments:  Containing directory name.
 355
 356 Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0).
 357
 358 This is used to obtain directory listings.  It's opendir(), readdir(), filldir() and closedir() all in one call.
 359
 360 example rv: return ('.', 'a', 'b', 0);
 361
 362 =head3 mknod
 363
 364 Arguments:  Filename, numeric modes, numeric device
 365
 366 Returns an errno (0 upon success, as usual).
 367
 368 This function is called for all non-directory, non-symlink nodes,
 369 not just devices.
 370
 371 =head3 mkdir
 372
 373 Arguments:  New directory pathname, numeric modes.
 374
 375 Returns an errno.
 376
 377 Called to create a directory.
 378
 379 =head3 unlink
 380
 381 Arguments:  Filename.
 382
 383 Returns an errno.
 384
 385 Called to remove a file, device, or symlink.
 386
 387 =head3 rmdir
 388
 389 Arguments:  Pathname.
 390
 391 Returns an errno.
 392
 393 Called to remove a directory.
 394
 395 =head3 symlink
 396
 397 Arguments:  Existing filename, symlink name.
 398
 399 Returns an errno.
 400
 401 Called to create a symbolic link.
 402
 403 =head3 rename
 404
 405 Arguments:  old filename, new filename.
 406
 407 Returns an errno.
 408
 409 Called to rename a file, and/or move a file from one directory to another.
 410
 411 =head3 link
 412
 413 Arguments:  Existing filename, hardlink name.
 414
 415 Returns an errno.
 416
 417 Called to create hard links.
 418
 419 =head3 chmod
 420
 421 Arguments:  Pathname, numeric modes.
 422
 423 Returns an errno.
 424
 425 Called to change permissions on a file/directory/device/symlink.
 426
 427 =head3 chown
 428
 429 Arguments:  Pathname, numeric uid, numeric gid.
 430
 431 Returns an errno.
 432
 433 Called to change ownership of a file/directory/device/symlink.
 434
 435 =head3 truncate
 436
 437 Arguments:  Pathname, numeric offset.
 438
 439 Returns an errno.
 440
 441 Called to truncate a file, at the given offset.
 442
 443 =head3 utime
 444
 445 Arguments:  Pathname, numeric actime, numeric modtime.
 446
 447 Returns an errno.
 448
 449 Called to change access/modification times for a file/directory/device/symlink.
 450
 451 =head3 open
 452
 453 Arguments:  Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY
 454 and O_SYNC, constants you can import from POSIX), fileinfo hash reference.
 455
 456 Returns an errno, a file handle (optional).
 457
 458 No creation, or truncation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open().
 459 The fileinfo hash reference contains flags from the Fuse open call which may be modified by the module. The only fields presently supported are:
 460  direct_io (version 2.4 onwards)
 461  keep_cache (version 2.4 onwards)
 462  nonseekable (version 2.9 onwards)
 463 Your open() method needs only check if the operation is permitted for the given flags, and return 0 for success.
 464 Optionally a file handle may be returned, which will be passed to subsequent read, write, flush, fsync and release calls.
 465
 466 =head3 read
 467
 468 Arguments:  Pathname, numeric requested size, numeric offset, file handle
 469
 470 Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data.
 471
 472 Called in an attempt to fetch a portion of the file.
 473
 474 =head3 write
 475
 476 Arguments:  Pathname, scalar buffer, numeric offset, file handle.  You can use length($buffer) to
 477 find the buffersize.
 478 Returns length($buffer) if successful (number of bytes written).
 479
 480 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.
 481
 482 =head3 statfs
 483
 484 Arguments:  none
 485
 486 Returns any of the following:
 487
 488 -ENOANO()
 489
 490 or
 491
 492 $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
 493
 494 or
 495
 496 -ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
 497
 498 =head3 flush
 499
 500 Arguments: Pathname, file handle
 501
 502 Returns an errno or 0 on success.
 503
 504 Called to synchronise any cached data. This is called before the file
 505 is closed. It may be called multiple times before a file is closed.
 506
 507 =head3 release
 508
 509 Arguments: Pathname, numeric flags passed to open, file handle
 510 Returns an errno or 0 on success.
 511
 512 Called to indicate that there are no more references to the file. Called once
 513 for every file with the same pathname and flags as were passed to open.
 514
 515 =head3 fsync
 516
 517 Arguments: Pathname, numeric flags
 518
 519 Returns an errno or 0 on success.
 520
 521 Called to synchronise the file's contents. If flags is non-zero,
 522 only synchronise the user data. Otherwise synchronise the user and meta data.
 523
 524 =head3 setxattr
 525
 526 Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE
 527
 528 Returns an errno or 0 on success.
 529
 530 Called to set the value of the named extended attribute.
 531
 532 If you wish to reject setting of a particular form of extended attribute name
 533 (e.g.: regexps matching user\..* or security\..*), then return - EOPNOTSUPP.
 534
 535 If flags is set to XATTR_CREATE and the extended attribute already exists,
 536 this should fail with - EEXIST. If flags is set to XATTR_REPLACE
 537 and the extended attribute doesn't exist, this should fail with - ENOATTR.
 538
 539 XATTR_CREATE and XATTR_REPLACE are provided by this module, but not exported
 540 by default. To import them:
 541
 542     use Fuse ':xattr';
 543
 544 or:
 545
 546     use Fuse ':all';
 547
 548 =head3 getxattr
 549
 550 Arguments: Pathname, extended attribute's name
 551
 552 Returns an errno, 0 if there was no value, or the extended attribute's value.
 553
 554 Called to get the value of the named extended attribute.
 555
 556 =head3 listxattr
 557
 558 Arguments: Pathname
 559
 560 Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0).
 561
 562 =head3 removexattr
 563
 564 Arguments: Pathname, extended attribute's name
 565
 566 Returns an errno or 0 on success.
 567
 568 =head3 opendir
 569
 570 Arguments: Pathname of a directory
 571 Returns an errno, and a directory handle (optional)
 572
 573 Called when opening a directory for reading. If special handling is
 574 required to open a directory, this operation can be implemented to handle
 575 that.
 576
 577 =head3 readdir
 578
 579 Arguments: Pathname of a directory, numeric offset, (optional) directory handle
 580
 581 Returns a list of 0 or more entries, followed by a numeric errno (usually 0).
 582 The entries can be simple strings (filenames), or arrays containing an
 583 offset number, the filename, and optionally an array ref containing the
 584 stat values (as would be returned from getattr()).
 585
 586 This is used to read entries from a directory. It can be used to return just
 587 entry names like getdir(), or can get a segment of the available entries,
 588 which requires using array refs and the 2- or 3-item form, with offset values
 589 starting from 1. If you wish to return the parameters to fill each entry's
 590 struct stat, but do not wish to do partial entry lists/entry counting, set
 591 the first element of each array to 0 always.
 592
 593 Note that if this call is implemented, it overrides getdir() ALWAYS.
 594
 595 =head3 releasedir
 596
 597 Arguments: Pathname of a directory, (optional) directory handle
 598
 599 Returns an errno or 0 on success
 600
 601 Called when there are no more references to an opened directory. Called once
 602 for each pathname or handle passed to opendir(). Similar to release(), but
 603 for directories. Accepts a return value, but like release(), the response
 604 code will not propagate to any corresponding closedir() calls.
 605
 606 =head3 fsyncdir
 607
 608 Arguments: Pathname of a directory, numeric flags, (optional) directory handle
 609
 610 Returns an errno or 0 on success.
 611
 612 Called to synchronize any changes to a directory's contents. If flag is
 613 non-zero, only synchronize user data, otherwise synchronize user data and
 614 metadata.
 615
 616 =head3 init
 617
 618 Arguments: None.
 619
 620 Returns (optionally) an SV to be passed as private_data via fuse_get_context().
 621
 622 =head3 destroy
 623
 624 Arguments: (optional) private data SV returned from init(), if any.
 625
 626 Returns nothing.
 627
 628 =head3 access
 629
 630 Arguments: Pathname, access mode flags
 631
 632 Returns an errno or 0 on success.
 633
 634 Determine if the user attempting to access the indicated file has access to
 635 perform the requested actions. The user ID can be determined by calling
 636 fuse_get_context(). See access(2) for more information.
 637
 638 =head3 create
 639
 640 Arguments: Pathname, create mask, open mode flags
 641
 642 Returns errno or 0 on success, and (optional) file handle.
 643
 644 Create a file with the path indicated, then open a handle for reading and/or
 645 writing with the supplied mode flags. Can also return a file handle like
 646 open() as part of the call.
 647
 648 =head3 ftruncate
 649
 650 Arguments: Pathname, numeric offset, (optional) file handle
 651
 652 Returns errno or 0 on success
 653
 654 Like truncate(), but on an opened file.
 655
 656 =head3 fgetattr
 657
 658 Arguments: Pathname, (optional) file handle
 659
 660 Returns a list, very similar to the 'stat' function (see
 661 perlfunc).  On error, simply return a single numeric scalar
 662 value (e.g. "return -ENOENT();").
 663
 664 Like getattr(), but on an opened file.
 665
 666 =head3 lock
 667
 668 Arguments: Pathname, numeric command code, hashref containing lock parameters, (optional) file handle
 669
 670 Returns errno or 0 on success
 671
 672 Used to lock or unlock regions of a file. Locking is handled locally, but this
 673 allows (especially for networked file systems) for protocol-level locking
 674 semantics to also be employed, if any are available.
 675
 676 See the Fuse documentation for more explanation of lock(). The needed symbols
 677 for the lock constants can be obtained by importing Fcntl.
 678
 679 =head3 utimens
 680
 681 Arguments: Pathname, last accessed time, last modified time
 682
 683 Returns errno or 0 on success
 684
 685 Like utime(), but allows time resolution down to the nanosecond. Currently
 686 times are passed as "numeric" (internally I believe these are represented
 687 typically as "long double"), so the sub-second portion is represented as
 688 fractions of a second.
 689
 690 Note that if this call is implemented, it overrides utime() ALWAYS.
 691
 692 =head3 bmap
 693
 694 Arguments: Pathname, numeric blocksize, numeric block number
 695
 696 Returns errno or 0 on success, and physical block number if successful
 697
 698 Used to map a block number offset in a file to the physical block offset
 699 on the block device backing the file system. This is intended for
 700 filesystems that are stored on an actual block device, with the 'blkdev'
 701 option passed.
 702
 703 =head3 ioctl
 704
 705 Arguments: Pathname, (signed) ioctl command code, flags, data if ioctl op is a write, (optional) file handle
 706
 707 Returns errno or 0 on success, and data if ioctl op is a read
 708
 709 Used to handle ioctl() operations on files. See ioctl(2) for more
 710 information on the fine details of ioctl operation numbers. May need to
 711 h2ph system headers to get the necessary macros; keep in mind the macros
 712 are highly OS-dependent.
 713
 714 Keep in mind that read and write are from the client perspective, so
 715 read from our end means data is going *out*, and write means data is
 716 coming *in*. It can be slightly confusing.
 717
 718 =head3 poll
 719
 720 Arguments: Pathname, poll handle ID (or undef if none), event mask, (optional) file handle
 721
 722 Returns errno or 0 on success, and updated event mask on success
 723
 724 Used to handle poll() operations on files. See poll(2) to learn more about
 725 event polling. Use IO::Poll to get the POLLIN, POLLOUT, and other symbols
 726 to describe the events which can happen on the filehandle. Save the poll
 727 handle ID to be passed to C<notify_poll> and C<pollhandle_destroy>
 728 functions, if it is not undef. Threading will likely be necessary for this
 729 operation to work.
 730
 731 There is not an "out of band" data transfer channel provided as part of
 732 FUSE, so POLLPRI/POLLRDBAND/POLLWRBAND won't work.
 733
 734 Poll handle is currently a read-only scalar; we are investigating a way
 735 to make this an object instead.
 736
 737 =head1 AUTHOR
 738
 739 Mark Glines, E<lt>mark@glines.orgE<gt>
 740
 741 =head1 SEE ALSO
 742
 743 L<perl>, the FUSE documentation.
 744
 745 =cut