/[fuse.before_github]/perl/trunk/Fuse.pm
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Contents of /perl/trunk/Fuse.pm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 18 - (show annotations)
Wed Dec 21 15:33:37 2005 UTC (16 years, 11 months ago) by dpavlin
File size: 12792 byte(s)
Mark Glines changes to add ithreads support:
* Support threading
* Fix the DEBUGf stuff, it seems to segfault these days
* Update the docs
* scrub off some bitrot

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

  ViewVC Help
Powered by ViewVC 1.1.26