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