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 use Data::Dumper;
  14 our @ISA = qw(Exporter DynaLoader);
  15
  16 # Items to export into callers namespace by default. Note: do not export
  17 # names by default without a very good reason. Use EXPORT_OK instead.
  18 # Do not simply export all your public functions/methods/constants.
  19
  20 # This allows declaration       use Fuse ':all';
  21 # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
  22 # will save memory.
  23 our %EXPORT_TAGS = (
  24                     'all' => [ qw(XATTR_CREATE XATTR_REPLACE fuse_get_context fuse_version) ],
  25                     'xattr' => [ qw(XATTR_CREATE XATTR_REPLACE) ]
  26                     );
  27
  28 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
  29
  30 our @EXPORT = ();
  31 our $VERSION = '0.11';
  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 sub XATTR_CREATE {
  66     # See <sys/xattr.h>.
  67     return 1;
  68 }
  69
  70 sub XATTR_REPLACE {
  71     # See <sys/xattr.h>.
  72     return 2;
  73 }
  74
  75 bootstrap Fuse $VERSION;
  76
  77 sub main {
  78         my @names = qw(getattr readlink getdir mknod mkdir unlink rmdir symlink
  79                         rename link chmod chown truncate utime open read write statfs
  80                         flush release fsync setxattr getxattr listxattr removexattr opendir readdir releasedir fsyncdir);
  81         my @subs = map {undef} @names;
  82         my $tmp = 0;
  83         my %mapping = map { $_ => $tmp++ } @names;
  84         my @otherargs = qw(debug threaded mountpoint mountopts);
  85         my %otherargs = (debug=>0, threaded=>0, mountpoint=>"", mountopts=>"");
  86         while(my $name = shift) {
  87                 my ($subref) = shift;
  88                 if(exists($otherargs{$name})) {
  89                         $otherargs{$name} = $subref;
  90                 } else {
  91                         croak "There is no function $name" unless exists($mapping{$name});
  92                         croak "Usage: Fuse::main(getattr => \"main::my_getattr\", ...)" unless $subref;
  93                         $subs[$mapping{$name}] = $subref;
  94                 }
  95         }
  96         if($otherargs{threaded}) {
  97                 # make sure threads are both available, and loaded.
  98                 if($Config{useithreads}) {
  99                         if(exists($threads::{VERSION})) {
 100                                 if(exists($threads::shared::{VERSION})) {
 101                                         # threads will work.
 102                                 } else {
 103                                         carp("Thread support requires you to use threads::shared.\nThreads are disabled.\n");
 104                                         $otherargs{threaded} = 0;
 105                                 }
 106                         } else {
 107                                 carp("Thread support requires you to use threads and threads::shared.\nThreads are disabled.\n");
 108                                 $otherargs{threaded} = 0;
 109                         }
 110                 } else {
 111                         carp("Thread support was not compiled into this build of perl.\nThreads are disabled.\n");
 112                         $otherargs{threaded} = 0;
 113                 }
 114         }
 115         perl_fuse_main(@otherargs{@otherargs},@subs);
 116 }
 117
 118 # Autoload methods go after =cut, and are processed by the autosplit program.
 119
 120 1;
 121 __END__
 122
 123 =head1 NAME
 124
 125 Fuse - write filesystems in Perl using FUSE
 126
 127 =head1 SYNOPSIS
 128
 129   use Fuse;
 130   my ($mountpoint) = "";
 131   $mountpoint = shift(@ARGV) if @ARGV;
 132   Fuse::main(mountpoint=>$mountpoint, getattr=>"main::my_getattr", getdir=>"main::my_getdir", ...);
 133
 134 =head1 DESCRIPTION
 135
 136 This lets you implement filesystems in perl, through the FUSE
 137 (Filesystem in USErspace) kernel/lib interface.
 138
 139 FUSE expects you to implement callbacks for the various functions.
 140
 141 In the following definitions, "errno" can be 0 (for a success),
 142 -EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really.
 143
 144 You can import standard error constants by saying something like
 145 "use POSIX qw(EDOTDOT ENOANO);".
 146
 147 Every constant you need (file types, open() flags, error values,
 148 etc) can be imported either from POSIX or from Fcntl, often both.
 149 See their respective documentations, for more information.
 150
 151 =head2 EXPORTED SYMBOLS
 152
 153 None by default.
 154
 155 You can request all exportable symbols by using the tag ":all".
 156
 157 You can request the extended attribute symbols by using the tag ":xattr".
 158 This will export XATTR_CREATE and XATTR_REPLACE.
 159
 160 =head2 FUNCTIONS
 161
 162 =head3 Fuse::main
 163
 164 Takes arguments in the form of hash key=>value pairs.  There are
 165 many valid keys.  Most of them correspond with names of callback
 166 functions, as described in section 'FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT'.
 167 A few special keys also exist:
 168
 169
 170 debug => boolean
 171
 172 =over 1
 173
 174 This turns FUSE call tracing on and off.  Default is 0 (which means off).
 175
 176 =back
 177
 178 mountpoint => string
 179
 180 =over 1
 181
 182 The point at which to mount this filesystem.  There is no default, you must
 183 specify this.  An example would be '/mnt'.
 184
 185 =back
 186
 187 mountopts => string
 188
 189 =over 1
 190
 191 This is a comma seperated list of mount options to pass to the FUSE kernel
 192 module.
 193
 194 At present, it allows the specification of the allow_other
 195 argument when mounting the new FUSE filesystem. To use this, you will also
 196 need 'user_allow_other' in /etc/fuse.conf as per the FUSE documention
 197
 198   mountopts => "allow_other" or
 199   mountopts => ""
 200
 201 =back
 202
 203 threaded => boolean
 204
 205 =over 1
 206
 207 This turns FUSE multithreading on and off.  The default is 0, meaning your FUSE
 208 script will run in single-threaded mode.  Note that single-threaded mode also
 209 means that you will not have to worry about reentrancy, though you will have to
 210 worry about recursive lookups.  In single-threaded mode, FUSE holds a global
 211 lock on your filesystem, and will wait for one callback to return before
 212 calling another.  This can lead to deadlocks, if your script makes any attempt
 213 to access files or directories in the filesystem it is providing.  (This
 214 includes calling stat() on the mount-point, statfs() calls from the 'df'
 215 command, and so on and so forth.)  It is worth paying a little attention and
 216 being careful about this.
 217
 218 Enabling multithreading will cause FUSE to make multiple simultaneous calls
 219 into the various callback functions of your perl script.  If you enable
 220 threaded mode, you can enjoy all the parallel execution and interactive
 221 response benefits of threads, and you get to enjoy all the benefits of race
 222 conditions and locking bugs, too.  Please also ensure any other perl modules
 223 you're using are also thread-safe.
 224
 225 (If enabled, this option will cause a warning if your perl interpreter was not
 226 built with USE_ITHREADS, or if you have failed to use threads or
 227 threads::shared.)
 228
 229 =back
 230
 231 =head3 Fuse::fuse_get_context
 232
 233  use Fuse "fuse_get_context";
 234  my $caller_uid = fuse_get_context()->{"uid"};
 235  my $caller_gid = fuse_get_context()->{"gid"};
 236  my $caller_pid = fuse_get_context()->{"pid"};
 237
 238 Access context information about the current Fuse operation.
 239
 240 =head3 Fuse::fuse_version
 241
 242 Indicates the Fuse version in use; more accurately, indicates the version
 243 of the Fuse API in use at build time. Returned as a decimal value; i.e.,
 244 for Fuse API v2.6, will return "2.6".
 245
 246 =head2 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT
 247
 248 =head3 getattr
 249
 250 Arguments:  filename.
 251 Returns a list, very similar to the 'stat' function (see
 252 perlfunc).  On error, simply return a single numeric scalar
 253 value (e.g. "return -ENOENT();").
 254
 255 FIXME: the "ino" field is currently ignored.  I tried setting it to 0
 256 in an example script, which consistently caused segfaults.
 257
 258 Fields (the following was stolen from perlfunc(1) with apologies):
 259
 260 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
 261         $atime,$mtime,$ctime,$blksize,$blocks)
 262                          = getattr($filename);
 263
 264 Here are the meaning of the fields:
 265
 266  0 dev      device number of filesystem
 267  1 ino      inode number
 268  2 mode     file mode  (type and permissions)
 269  3 nlink    number of (hard) links to the file
 270  4 uid      numeric user ID of file's owner
 271  5 gid      numeric group ID of file's owner
 272  6 rdev     the device identifier (special files only)
 273  7 size     total size of file, in bytes
 274  8 atime    last access time in seconds since the epoch
 275  9 mtime    last modify time in seconds since the epoch
 276 10 ctime    inode change time (NOT creation time!) in seconds
 277             since the epoch
 278 11 blksize  preferred block size for file system I/O
 279 12 blocks   actual number of blocks allocated
 280
 281 (The epoch was at 00:00 January 1, 1970 GMT.)
 282
 283 =head3 readlink
 284
 285 Arguments:  link pathname.
 286 Returns a scalar: either a numeric constant, or a text string.
 287
 288 This is called when dereferencing symbolic links, to learn the target.
 289
 290 example rv: return "/proc/self/fd/stdin";
 291
 292 =head3 getdir
 293
 294 Arguments:  Containing directory name.
 295 Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0).
 296
 297 This is used to obtain directory listings.  It's opendir(), readdir(), filldir() and closedir() all in one call.
 298
 299 example rv: return ('.', 'a', 'b', 0);
 300
 301 =head3 readdir
 302
 303 Arguments: Directory name, offset
 304 Returns: filename, offset to the next dirent, numeric errno 0 or -ENOENT()
 305
 306 =head3 mknod
 307
 308 Arguments:  Filename, numeric modes, numeric device
 309 Returns an errno (0 upon success, as usual).
 310
 311 This function is called for all non-directory, non-symlink nodes,
 312 not just devices.
 313
 314 =head3 mkdir
 315
 316 Arguments:  New directory pathname, numeric modes.
 317 Returns an errno.
 318
 319 Called to create a directory.
 320
 321 =head3 unlink
 322
 323 Arguments:  Filename.
 324 Returns an errno.
 325
 326 Called to remove a file, device, or symlink.
 327
 328 =head3 rmdir
 329
 330 Arguments:  Pathname.
 331 Returns an errno.
 332
 333 Called to remove a directory.
 334
 335 =head3 symlink
 336
 337 Arguments:  Existing filename, symlink name.
 338 Returns an errno.
 339
 340 Called to create a symbolic link.
 341
 342 =head3 rename
 343
 344 Arguments:  old filename, new filename.
 345 Returns an errno.
 346
 347 Called to rename a file, and/or move a file from one directory to another.
 348
 349 =head3 link
 350
 351 Arguments:  Existing filename, hardlink name.
 352 Returns an errno.
 353
 354 Called to create hard links.
 355
 356 =head3 chmod
 357
 358 Arguments:  Pathname, numeric modes.
 359 Returns an errno.
 360
 361 Called to change permissions on a file/directory/device/symlink.
 362
 363 =head3 chown
 364
 365 Arguments:  Pathname, numeric uid, numeric gid.
 366 Returns an errno.
 367
 368 Called to change ownership of a file/directory/device/symlink.
 369
 370 =head3 truncate
 371
 372 Arguments:  Pathname, numeric offset.
 373 Returns an errno.
 374
 375 Called to truncate a file, at the given offset.
 376
 377 =head3 utime
 378
 379 Arguments:  Pathname, numeric actime, numeric modtime.
 380 Returns an errno.
 381
 382 Called to change access/modification times for a file/directory/device/symlink.
 383
 384 =head3 open
 385
 386 Arguments:  Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY
 387 and O_SYNC, constants you can import from POSIX), fileinfo hash reference.
 388 Returns an errno, a file handle (optional).
 389
 390 No creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open().
 391 The fileinfo hash reference contains flags from the Fuse open call which may be modified by the module. The only fields presently supported are:
 392  direct_io (version 2.4 onwards)
 393  keep_cache (version 2.4 onwards)
 394  nonseekable (version 2.9 onwards)
 395 Your open() method needs only check if the operation is permitted for the given flags, and return 0 for success.
 396 Optionally a file handle may be returned, which will be passed to subsequent read, write, flush, fsync and release calls.
 397
 398 =head3 read
 399
 400 Arguments:  Pathname, numeric requested size, numeric offset, file handle
 401 Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data.
 402
 403 Called in an attempt to fetch a portion of the file.
 404
 405 =head3 write
 406
 407 Arguments:  Pathname, scalar buffer, numeric offset, file handle.  You can use length($buffer) to
 408 find the buffersize.
 409 Returns length($buffer) if successful (number of bytes written).
 410
 411 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.
 412
 413 =head3 statfs
 414
 415 Arguments:  none
 416 Returns any of the following:
 417
 418 -ENOANO()
 419
 420 or
 421
 422 $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
 423
 424 or
 425
 426 -ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
 427
 428 =head3 flush
 429
 430 Arguments: Pathname, file handle
 431 Returns an errno or 0 on success.
 432
 433 Called to synchronise any cached data. This is called before the file
 434 is closed. It may be called multiple times before a file is closed.
 435
 436 =head3 release
 437
 438 Arguments: Pathname, numeric flags passed to open, file handle
 439 Returns an errno or 0 on success.
 440
 441 Called to indicate that there are no more references to the file. Called once
 442 for every file with the same pathname and flags as were passed to open.
 443
 444 =head3 fsync
 445
 446 Arguments: Pathname, numeric flags
 447 Returns an errno or 0 on success.
 448
 449 Called to synchronise the file's contents. If flags is non-zero,
 450 only synchronise the user data. Otherwise synchronise the user and meta data.
 451
 452 =head3 setxattr
 453
 454 Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE
 455 Returns an errno or 0 on success.
 456
 457 Called to set the value of the named extended attribute.
 458
 459 If you wish to reject setting of a particular form of extended attribute name
 460 (e.g.: regexps matching user\..* or security\..*), then return - EOPNOTSUPP.
 461
 462 If flags is set to XATTR_CREATE and the extended attribute already exists,
 463 this should fail with - EEXIST. If flags is set to XATTR_REPLACE
 464 and the extended attribute doesn't exist, this should fail with - ENOATTR.
 465
 466 XATTR_CREATE and XATTR_REPLACE are provided by this module, but not exported
 467 by default. To import them:
 468
 469     use Fuse ':xattr';
 470
 471 or:
 472
 473     use Fuse ':all';
 474
 475 =head3 getxattr
 476
 477 Arguments: Pathname, extended attribute's name
 478 Returns an errno, 0 if there was no value, or the extended attribute's value.
 479
 480 Called to get the value of the named extended attribute.
 481
 482 =head3 listxattr
 483
 484 Arguments: Pathname
 485 Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0).
 486
 487 =head3 removexattr
 488
 489 Arguments: Pathname, extended attribute's name
 490 Returns an errno or 0 on success.
 491
 492 =head1 AUTHOR
 493
 494 Mark Glines, E<lt>mark@glines.orgE<gt>
 495
 496 =head1 SEE ALSO
 497
 498 L<perl>, the FUSE documentation.
 499
 500 =cut