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