/[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 14 - (hide annotations)
Sun Apr 10 13:30:11 2005 UTC (18 years, 11 months ago) by richdawe
File size: 11902 byte(s)
Add support for operations supported by FUSE 2.2.1 (flush, release, fsync, extended attributes); bump version to 0.06.

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 mszeredi 4 my ($tmp) = 0;
85     my (%mapping) = map { $_ => $tmp++ } (@names);
86     my (%otherargs) = (debug=>0, mountpoint=>"");
87     while(my $name = shift) {
88     my ($subref) = shift;
89     if(exists($otherargs{$name})) {
90     $otherargs{$name} = $subref;
91     } else {
92     croak "There is no function $name" unless exists($mapping{$name});
93     croak "Usage: Fuse::main(getattr => &my_getattr, ...)" unless $subref;
94     croak "Usage: Fuse::main(getattr => &my_getattr, ...)" unless ref($subref);
95     croak "Usage: Fuse::main(getattr => &my_getattr, ...)" unless ref($subref) eq "CODE";
96     $subs[$mapping{$name}] = $subref;
97     }
98     }
99     perl_fuse_main($otherargs{debug},$otherargs{mountpoint},@subs);
100     }
101    
102     # Autoload methods go after =cut, and are processed by the autosplit program.
103    
104     1;
105     __END__
106    
107     =head1 NAME
108    
109     Fuse - write filesystems in Perl using FUSE
110    
111     =head1 SYNOPSIS
112    
113     use Fuse;
114     my ($mountpoint) = "";
115     $mountpoint = shift(@ARGV) if @ARGV;
116     Fuse::main(mountpoint=>$mountpoint, getattr=>\&my_getattr, getdir=>\&my_getdir, ...);
117    
118     =head1 DESCRIPTION
119    
120     This lets you implement filesystems in perl, through the FUSE
121     (Filesystem in USErspace) kernel/lib interface.
122    
123     FUSE expects you to implement callbacks for the various functions.
124    
125     NOTE: I have only tested the things implemented in example.pl!
126     It should work, but some things may not.
127    
128     In the following definitions, "errno" can be 0 (for a success),
129     -EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really.
130    
131     You can import standard error constants by saying something like
132     "use POSIX qw(EDOTDOT ENOANO);".
133    
134     Every constant you need (file types, open() flags, error values,
135     etc) can be imported either from POSIX or from Fcntl, often both.
136     See their respective documentations, for more information.
137    
138 richdawe 14 =head2 EXPORTED SYMBOLS
139 mszeredi 4
140 richdawe 14 FUSE_DEBUG by default.
141 mszeredi 4
142 richdawe 14 You can request all exportable symbols by using the tag ":all".
143 mszeredi 4
144 richdawe 14 You can request all debug symbols by using the tag ":debug".
145     This will export FUSE_DEBUG.
146 mszeredi 4
147 richdawe 14 You can request the extended attribute symbols by using the tag ":xattr".
148     This will export XATTR_CREATE and XATTR_REPLACE.
149    
150 mszeredi 4 =head2 FUNCTIONS
151    
152     =head3 Fuse::main
153    
154     Takes arguments in the form of hash key=>value pairs. There are
155     many valid keys. Most of them correspond with names of callback
156     functions, as described in section 'FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT'.
157     A few special keys also exist:
158    
159    
160     debug => boolean
161    
162     =over 1
163    
164     This turns FUSE call tracing on and off. Default is 0 (which means off).
165    
166     =back
167    
168     mountpoint => string
169    
170     =over 1
171    
172     The point at which to mount this filesystem. There is no default, you must
173     specify this. An example would be '/mnt'.
174    
175     =back
176    
177     unthreaded => boolean
178    
179     =over 1
180    
181     This turns FUSE multithreading off and on. NOTE: This perlmodule does not
182     currently work properly in multithreaded mode! The author is unfortunately
183     not familiar enough with perl-threads internals, and according to the
184     documentation available at time of writing (2002-03-08), those internals are
185     subject to changing anyway. Note that singlethreaded mode also means that
186     you will not have to worry about reentrancy, though you will have to worry
187     about recursive lookups (since the kernel holds a global lock on your
188     filesystem and blocks waiting for one callback to complete before calling
189     another).
190    
191     I hope to add full multithreading functionality later, but for now, I
192     recommend you leave this option at the default, 1 (which means
193     unthreaded, no threads will be used and no reentrancy is needed).
194    
195     =back
196    
197     =head2 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT
198    
199     =head3 getattr
200    
201     Arguments: filename.
202     Returns a list, very similar to the 'stat' function (see
203     perlfunc). On error, simply return a single numeric scalar
204     value (e.g. "return -ENOENT();").
205    
206     FIXME: the "ino" field is currently ignored. I tried setting it to 0
207     in an example script, which consistently caused segfaults.
208    
209     Fields (the following was stolen from perlfunc(1) with apologies):
210    
211     ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
212     $atime,$mtime,$ctime,$blksize,$blocks)
213     = getattr($filename);
214    
215     Here are the meaning of the fields:
216    
217     0 dev device number of filesystem
218     1 ino inode number
219     2 mode file mode (type and permissions)
220     3 nlink number of (hard) links to the file
221     4 uid numeric user ID of file's owner
222     5 gid numeric group ID of file's owner
223     6 rdev the device identifier (special files only)
224     7 size total size of file, in bytes
225     8 atime last access time in seconds since the epoch
226     9 mtime last modify time in seconds since the epoch
227     10 ctime inode change time (NOT creation time!) in seconds
228     since the epoch
229     11 blksize preferred block size for file system I/O
230     12 blocks actual number of blocks allocated
231    
232     (The epoch was at 00:00 January 1, 1970 GMT.)
233    
234     =head3 readlink
235    
236     Arguments: link pathname.
237     Returns a scalar: either a numeric constant, or a text string.
238    
239     This is called when dereferencing symbolic links, to learn the target.
240    
241     example rv: return "/proc/self/fd/stdin";
242    
243     =head3 getdir
244    
245     Arguments: Containing directory name.
246     Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0).
247    
248     This is used to obtain directory listings. Its opendir(), readdir(), filldir() and closedir() all in one call.
249    
250     example rv: return ('.', 'a', 'b', 0);
251    
252     =head3 mknod
253    
254     Arguments: Filename, numeric modes, numeric device
255     Returns an errno (0 upon success, as usual).
256    
257     This function is called for all non-directory, non-symlink nodes,
258     not just devices.
259    
260     =head3 mkdir
261    
262     Arguments: New directory pathname, numeric modes.
263     Returns an errno.
264    
265     Called to create a directory.
266    
267     =head3 unlink
268    
269     Arguments: Filename.
270     Returns an errno.
271    
272     Called to remove a file, device, or symlink.
273    
274     =head3 rmdir
275    
276     Arguments: Pathname.
277     Returns an errno.
278    
279     Called to remove a directory.
280    
281     =head3 symlink
282    
283     Arguments: Existing filename, symlink name.
284     Returns an errno.
285    
286     Called to create a symbolic link.
287    
288     =head3 rename
289    
290     Arguments: old filename, new filename.
291     Returns an errno.
292    
293     Called to rename a file, and/or move a file from one directory to another.
294    
295     =head3 link
296    
297     Arguments: Existing filename, hardlink name.
298     Returns an errno.
299    
300     Called to create hard links.
301    
302     =head3 chmod
303    
304     Arguments: Pathname, numeric modes.
305     Returns an errno.
306    
307     Called to change permissions on a file/directory/device/symlink.
308    
309     =head3 chown
310    
311     Arguments: Pathname, numeric uid, numeric gid.
312     Returns an errno.
313    
314     Called to change ownership of a file/directory/device/symlink.
315    
316     =head3 truncate
317    
318     Arguments: Pathname, numeric offset.
319     Returns an errno.
320    
321     Called to truncate a file, at the given offset.
322    
323     =head3 utime
324    
325     Arguments: Pathname, numeric actime, numeric modtime.
326     Returns an errno.
327    
328     Called to change access/modification times for a file/directory/device/symlink.
329    
330     =head3 open
331    
332     Arguments: Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY
333     and O_SYNC, constants you can import from POSIX).
334     Returns an errno.
335    
336     No creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open().
337     Your open() method needs only check if the operation is permitted for the given flags, and return 0 for success.
338    
339     =head3 read
340    
341     Arguments: Pathname, numeric requestedsize, numeric offset.
342     Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data.
343    
344     Called in an attempt to fetch a portion of the file.
345    
346     =head3 write
347    
348     Arguments: Pathname, scalar buffer, numeric offset. You can use length($buffer) to
349     find the buffersize.
350     Returns an errno.
351    
352     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.
353    
354     =head3 statfs
355    
356     Arguments: none
357     Returns any of the following:
358    
359     -ENOANO()
360    
361     or
362    
363     $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
364    
365     or
366    
367     -ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
368    
369 richdawe 14 =head3 flush
370    
371     Arguments: Pathname
372     Returns an errno or 0 on success.
373    
374     Called to synchronise any cached data. This is called before the file
375     is closed. It may be called multiple times before a file is closed.
376    
377     =head3 release
378    
379     Arguments: Pathname, numeric flags passed to open
380     Returns an errno or 0 on success.
381    
382     Called to indicate that there are no more references to the file. Called once
383     for every file with the same pathname and flags as were passed to open.
384    
385     =head3 fsync
386    
387     Arguments: Pathname, numeric flags
388     Returns an errno or 0 on success.
389    
390     Called to synchronise the file's contents. If flags is non-zero,
391     only synchronise the user data. Otherwise synchronise the user and meta data.
392    
393     =head3 setxattr
394    
395     Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE
396     Returns an errno or 0 on success.
397    
398     Called to set the value of the named extended attribute.
399    
400     If you wish to reject setting of a particular form of extended attribute name
401     (e.g.: regexps matching user\..* or security\..*), then return - EOPNOTSUPP.
402    
403     If flags is set to XATTR_CREATE and the extended attribute already exists,
404     this should fail with - EEXIST. If flags is set to XATTR_REPLACE
405     and the extended attribute doesn't exist, this should fail with - ENOATTR.
406    
407     XATTR_CREATE and XATTR_REPLACE are provided by this module, but not exported
408     by default. To import them:
409    
410     use Fuse ':xattr';
411    
412     or:
413    
414     use Fuse ':all';
415    
416     =head3 getxattr
417    
418     Arguments: Pathname, extended attribute's name
419     Returns an errno, 0 if there was no value, or the extended attribute's value.
420    
421     Called to get the value of the named extended attribute.
422    
423     =head3 listxattr
424    
425     Arguments: Pathname
426     Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0).
427    
428     =head3 removexattr
429    
430     Arguments: Pathname, extended attribute's name
431     Returns an errno or 0 on success.
432    
433 mszeredi 4 =head1 AUTHOR
434    
435     Mark Glines, E<lt>mark@glines.orgE<gt>
436    
437     =head1 SEE ALSO
438    
439     L<perl>, the FUSE documentation.
440    
441     =cut

  ViewVC Help
Powered by ViewVC 1.1.26