/[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

Annotation of /perl/trunk/Fuse.pm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 18 - (hide annotations)
Wed Dec 21 15:33:37 2005 UTC (16 years, 9 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 mszeredi 4 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 richdawe 14 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 mszeredi 4
28     our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
29    
30     our @EXPORT = qw(
31     FUSE_DEBUG
32     );
33 richdawe 14 our $VERSION = '0.06';
34 mszeredi 4
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 richdawe 14 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 mszeredi 4 bootstrap Fuse $VERSION;
78    
79     sub main {
80 richdawe 14 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 mszeredi 4 my (@names) = qw(getattr readlink getdir mknod mkdir unlink rmdir symlink
82 richdawe 14 rename link chmod chown truncate utime open read write statfs
83     flush release fsync setxattr getxattr listxattr removexattr);
84 dpavlin 16 my (@validOpts) = qw(allow_other);
85 mszeredi 4 my ($tmp) = 0;
86     my (%mapping) = map { $_ => $tmp++ } (@names);
87 dpavlin 16 my (%optmap) = map { $_ => 1 } (@validOpts);
88 dpavlin 18 my (%otherargs) = (debug=>0, threaded=>0, mountpoint=>"", mountopts=>"");
89 mszeredi 4 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 dpavlin 18 croak "Usage: Fuse::main(getattr => \"main::my_getattr\", ...)" unless $subref;
96 mszeredi 4 $subs[$mapping{$name}] = $subref;
97     }
98     }
99 dpavlin 16 foreach my $opt ( split(/,/,$otherargs{mountopts}) ) {
100     if ( ! exists($optmap{$opt}) ) {
101     croak "Use of an invalid mountopt argument";
102     }
103     }
104 dpavlin 18 perl_fuse_main($otherargs{debug},$otherargs{threaded},$otherargs{mountpoint},$otherargs{mountopts},@subs);
105 mszeredi 4 }
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 dpavlin 18 Fuse::main(mountpoint=>$mountpoint, getattr=>"main::my_getattr", getdir=>"main::my_getdir", ...);
122 mszeredi 4
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 richdawe 14 =head2 EXPORTED SYMBOLS
141 mszeredi 4
142 richdawe 14 FUSE_DEBUG by default.
143 mszeredi 4
144 richdawe 14 You can request all exportable symbols by using the tag ":all".
145 mszeredi 4
146 richdawe 14 You can request all debug symbols by using the tag ":debug".
147     This will export FUSE_DEBUG.
148 mszeredi 4
149 richdawe 14 You can request the extended attribute symbols by using the tag ":xattr".
150     This will export XATTR_CREATE and XATTR_REPLACE.
151    
152 mszeredi 4 =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 dpavlin 16 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 dpavlin 18 threaded => boolean
196 mszeredi 4
197     =over 1
198    
199 dpavlin 18 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 mszeredi 4
210 dpavlin 18 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 mszeredi 4
217 dpavlin 18 (If enabled, this option will cause a warning if your perl interpreter was not
218     built with USE_ITHREADS.)
219    
220 mszeredi 4 =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 richdawe 14 =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 mszeredi 4 =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