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