1Fuse(3)               User Contributed Perl Documentation              Fuse(3)
2
3
4

NAME

6       Fuse - write filesystems in Perl using FUSE
7

SYNOPSIS

9         use Fuse;
10         my ($mountpoint) = "";
11         $mountpoint = shift(@ARGV) if @ARGV;
12         Fuse::main(mountpoint=>$mountpoint, getattr=>"main::my_getattr", getdir=>"main::my_getdir", ...);
13

DESCRIPTION

15       This lets you implement filesystems in perl, through the FUSE
16       (Filesystem in USErspace) kernel/lib interface.
17
18       FUSE expects you to implement callbacks for the various functions.
19
20       In the following definitions, "errno" can be 0 (for a success),
21       -EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really.
22
23       You can import standard error constants by saying something like "use
24       POSIX qw(EDOTDOT ENOANO);".
25
26       Every constant you need (file types, open() flags, error values, etc)
27       can be imported either from POSIX or from Fcntl, often both.  See their
28       respective documentations, for more information.
29
30   EXPORTED SYMBOLS
31       None by default.
32
33       You can request all exportable symbols by using the tag ":all".
34
35       You can request the extended attribute symbols by using the tag
36       ":xattr".  This will export XATTR_CREATE and XATTR_REPLACE.
37
38   FUNCTIONS
39       Fuse::main
40
41       Takes arguments in the form of hash key=>value pairs.  There are many
42       valid keys.  Most of them correspond with names of callback functions,
43       as described in section 'FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT'.  A
44       few special keys also exist:
45
46       debug => boolean
47        This turns FUSE call tracing on and off.  Default is 0 (which means
48        off).
49
50       mountpoint => string
51        The point at which to mount this filesystem.  There is no default, you
52        must specify this.  An example would be '/mnt'.
53
54       mountopts => string
55        This is a comma separated list of mount options to pass to the FUSE
56        kernel module.
57
58        At present, it allows the specification of the allow_other argument
59        when mounting the new FUSE filesystem. To use this, you will also need
60        'user_allow_other' in /etc/fuse.conf as per the FUSE documention
61
62          mountopts => "allow_other" or
63          mountopts => ""
64
65       threaded => boolean
66        This turns FUSE multithreading on and off.  The default is 0, meaning
67        your FUSE script will run in single-threaded mode.  Note that single-
68        threaded mode also means that you will not have to worry about
69        reentrancy, though you will have to worry about recursive lookups.  In
70        single-threaded mode, FUSE holds a global lock on your filesystem, and
71        will wait for one callback to return before calling another.  This can
72        lead to deadlocks, if your script makes any attempt to access files or
73        directories in the filesystem it is providing.  (This includes calling
74        stat() on the mount-point, statfs() calls from the 'df' command, and
75        so on and so forth.)  It is worth paying a little attention and being
76        careful about this.
77
78        Enabling multithreading will cause FUSE to make multiple simultaneous
79        calls into the various callback functions of your perl script.  If you
80        enable threaded mode, you can enjoy all the parallel execution and
81        interactive response benefits of threads, and you get to enjoy all the
82        benefits of race conditions and locking bugs, too.  Please also ensure
83        any other perl modules you're using are also thread-safe.
84
85        (If enabled, this option will cause a warning if your perl interpreter
86        was not built with USE_ITHREADS, or if you have failed to use threads
87        or threads::shared.)
88
89       nullpath_ok => boolean
90        This flag tells Fuse to not pass paths for functions that operate on
91        file or directory handles. This will yield empty path parameters for
92        functions including read, write, flush, release, fsync, readdir,
93        releasedir, fsyncdir, truncate, fgetattr and lock. If you use this,
94        you must return file/directory handles from open, opendir and create.
95        Default is 0 (off).  Only effective on Fuse 2.8 and up; with earlier
96        versions, this does nothing.
97
98       utimens_as_array => boolean
99        This flag causes timestamps passed via the utimens() call to be passed
100        as arrays containing the time in seconds, and a second value
101        containing the number of nanoseconds, instead of a floating point
102        value. This allows for more precise times, as the normal floating
103        point type used by Perl (double) loses accuracy starting at about
104        tenths of a microsecond.
105
106       nopath => boolean
107        Flag indicating that the path need not be calculated for the following
108        operations:
109
110        read, write, flush, release, fsync, readdir, releasedir, fsyncdir,
111        ftruncate, fgetattr, lock, ioctl and poll
112
113        Closely related to nullpath_ok, but if this flag is set then the path
114        will not be calculated even if the file wasn't unlinked. However the
115        path can still be defined if it needs to be calculated for some other
116        reason.
117
118        Only effective on Fuse 2.9 and up.
119
120       utime_omit_ok => boolean
121        Flag indicating that the filesystem accepts special UTIME_NOW and
122        UTIME_OMIT values in its "utimens" operation.
123
124        If you wish to use these constants, make sure to include the ':utime'
125        flag when including the Fuse module, or the ':all' flag.
126
127        Only effective on Fuse 2.9 and up.
128
129       Fuse::fuse_get_context
130
131        use Fuse "fuse_get_context";
132        my $caller_uid = fuse_get_context()->{"uid"};
133        my $caller_gid = fuse_get_context()->{"gid"};
134        my $caller_pid = fuse_get_context()->{"pid"};
135
136       Access context information about the current Fuse operation.
137
138       Fuse::fuse_version
139
140       Indicates the Fuse version in use; more accurately, indicates the
141       version of the Fuse API in use at build time. If called in scalar
142       context, the version will be returned as a decimal value; i.e., for
143       Fuse API v2.6, will return "2.6". If called in array context, an array
144       will be returned, containing the major, minor and micro version numbers
145       of the Fuse API it was built against.
146
147       Fuse::fuse_buf_size
148
149       Computes the total size of a buffer vector. Applicable for "read_buf"
150       and "write_buf" operations.
151
152       Fuse::fuse_buf_copy
153
154       Copies data from one buffer vector to another. Primarily useful if a
155       buffer vector contains multiple, fragmented chunks or if it contains an
156       FD buffer instead of a memory buffer. Applicable for "write_buf".
157
158       Fuse::notify_poll
159
160       Only available if the Fuse module is built against libfuse 2.8 or
161       later.  Use fuse_version() to determine if this is the case. Calling
162       this function with a pollhandle argument (as provided to the "poll"
163       operation implementation) will send a notification to the caller
164       poll()ing for I/O operation availability. If more than one pollhandle
165       is provided for the same filehandle, only use the latest; you *can*
166       send notifications to them all, but it is unnecessary and decreases
167       performance.
168
169       ONLY supply poll handles fed to you through "poll" to this function.
170       Due to thread safety requirements, we can't currently package the
171       pointer up in an object the way we'd like to to prevent this situation,
172       but your filesystem server program may segfault, or worse, if you feed
173       things to this function which it is not supposed to receive. If you do
174       anyway, we take no responsibility for whatever Bad Things(tm) may
175       happen.
176
177       Fuse::pollhandle_destroy
178
179       Only available if the Fuse module is built against libfuse 2.8 or
180       later.  Use fuse_version() to determine if this is the case. This
181       function destroys a poll handle (fed to your program through "poll").
182       When you are done with a poll handle, either because it has been
183       replaced, or because a notification has been sent to it, pass it to
184       this function to dispose of it safely.
185
186       ONLY supply poll handles fed to you through "poll" to this function.
187       Due to thread safety requirements, we can't currently package the
188       pointer up in an object the way we'd like to to prevent this situation,
189       but your filesystem server program may segfault, or worse, if you feed
190       things to this function which it is not supposed to receive. If you do
191       anyway, we take no responsibility for whatever Bad Things(tm) may
192       happen.
193
194   FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT
195       getattr
196
197       Arguments:  filename.
198
199       Returns a list, very similar to the 'stat' function (see perlfunc).  On
200       error, simply return a single numeric scalar value (e.g. "return
201       -ENOENT();").
202
203       FIXME: the "ino" field is currently ignored.  I tried setting it to 0
204       in an example script, which consistently caused segfaults.
205
206       Fields (the following was stolen from perlfunc(1) with apologies):
207
208       ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
209               $atime,$mtime,$ctime,$blksize,$blocks)
210                                = getattr($filename);
211
212       Here are the meaning of the fields:
213
214        0 dev      device number of filesystem
215        1 ino      inode number
216        2 mode     file mode  (type and permissions)
217        3 nlink    number of (hard) links to the file
218        4 uid      numeric user ID of file's owner
219        5 gid      numeric group ID of file's owner
220        6 rdev     the device identifier (special files only)
221        7 size     total size of file, in bytes
222        8 atime    last access time in seconds since the epoch
223        9 mtime    last modify time in seconds since the epoch
224       10 ctime    inode change time (NOT creation time!) in seconds
225                   since the epoch
226       11 blksize  preferred block size for file system I/O
227       12 blocks   actual number of blocks allocated
228
229       (The epoch was at 00:00 January 1, 1970 GMT.)
230
231       If you wish to provide sub-second precision timestamps, they may be
232       passed either as the fractional part of a floating-point value, or as a
233       two-element array, passed as an array ref, with the first element
234       containing the number of seconds since the epoch, and the second
235       containing the number of nanoseconds. This provides complete time
236       precision, as a floating point number starts losing precision at about
237       a tenth of a microsecond. So if you really care about that sort of
238       thing...
239
240       readlink
241
242       Arguments:  link pathname.
243
244       Returns a scalar: either a numeric constant, or a text string.
245
246       This is called when dereferencing symbolic links, to learn the target.
247
248       example rv: return "/proc/self/fd/stdin";
249
250       getdir
251
252       Arguments:  Containing directory name.
253
254       Returns a list: 0 or more text strings (the filenames), followed by a
255       numeric errno (usually 0).
256
257       This is used to obtain directory listings.  It's opendir(), readdir(),
258       filldir() and closedir() all in one call.
259
260       example rv: return ('.', 'a', 'b', 0);
261
262       mknod
263
264       Arguments:  Filename, numeric modes, numeric device
265
266       Returns an errno (0 upon success, as usual).
267
268       This function is called for all non-directory, non-symlink nodes, not
269       just devices.
270
271       mkdir
272
273       Arguments:  New directory pathname, numeric modes.
274
275       Returns an errno.
276
277       Called to create a directory.
278
279       unlink
280
281       Arguments:  Filename.
282
283       Returns an errno.
284
285       Called to remove a file, device, or symlink.
286
287       rmdir
288
289       Arguments:  Pathname.
290
291       Returns an errno.
292
293       Called to remove a directory.
294
295       symlink
296
297       Arguments:  Existing filename, symlink name.
298
299       Returns an errno.
300
301       Called to create a symbolic link.
302
303       rename
304
305       Arguments:  old filename, new filename.
306
307       Returns an errno.
308
309       Called to rename a file, and/or move a file from one directory to
310       another.
311
312       link
313
314       Arguments:  Existing filename, hardlink name.
315
316       Returns an errno.
317
318       Called to create hard links.
319
320       chmod
321
322       Arguments:  Pathname, numeric modes.
323
324       Returns an errno.
325
326       Called to change permissions on a file/directory/device/symlink.
327
328       chown
329
330       Arguments:  Pathname, numeric uid, numeric gid.
331
332       Returns an errno.
333
334       Called to change ownership of a file/directory/device/symlink.
335
336       truncate
337
338       Arguments:  Pathname, numeric offset.
339
340       Returns an errno.
341
342       Called to truncate a file, at the given offset.
343
344       utime
345
346       Arguments:  Pathname, numeric actime, numeric modtime.
347
348       Returns an errno.
349
350       Called to change access/modification times for a
351       file/directory/device/symlink.
352
353       open
354
355       Arguments:  Pathname, numeric flags (which is an OR-ing of stuff like
356       O_RDONLY and O_SYNC, constants you can import from POSIX), fileinfo
357       hash reference.
358
359       Returns an errno, a file handle (optional).
360
361       No creation, or truncation flags (O_CREAT, O_EXCL, O_TRUNC) will be
362       passed to open().  The fileinfo hash reference contains flags from the
363       Fuse open call which may be modified by the module. The only fields
364       presently supported are:
365        direct_io (version 2.4 onwards)
366        keep_cache (version 2.4 onwards)
367        nonseekable (version 2.8 onwards) Your open() method needs only check
368       if the operation is permitted for the given flags, and return 0 for
369       success.  Optionally a file handle may be returned, which will be
370       passed to subsequent read, write, flush, fsync and release calls.
371
372       read
373
374       Arguments:  Pathname, numeric requested size, numeric offset, file
375       handle
376
377       Returns a numeric errno, or a string scalar with up to $requestedsize
378       bytes of data.
379
380       Called in an attempt to fetch a portion of the file.
381
382       write
383
384       Arguments:  Pathname, scalar buffer, numeric offset, file handle.  You
385       can use length($buffer) to find the buffersize.  Returns
386       length($buffer) if successful (number of bytes written).
387
388       Called in an attempt to write (or overwrite) a portion of the file.  Be
389       prepared because $buffer could contain random binary data with NULs and
390       all sorts of other wonderful stuff.
391
392       statfs
393
394       Arguments:  none
395
396       Returns any of the following:
397
398       -ENOANO()
399
400       or
401
402       $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
403
404       or
405
406       -ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail,
407       $blocksize
408
409       flush
410
411       Arguments: Pathname, file handle
412
413       Returns an errno or 0 on success.
414
415       Called to synchronise any cached data. This is called before the file
416       is closed. It may be called multiple times before a file is closed.
417
418       release
419
420       Arguments: Pathname, numeric flags passed to open, file handle,
421       flock_release flag (when built against FUSE 2.9 or later), lock owner
422       ID (when built against FUSE 2.9 or later)
423
424       Returns an errno or 0 on success.
425
426       Called to indicate that there are no more references to the file.
427       Called once for every file with the same pathname and flags as were
428       passed to open.
429
430       fsync
431
432       Arguments: Pathname, numeric flags
433
434       Returns an errno or 0 on success.
435
436       Called to synchronise the file's contents. If flags is non-zero, only
437       synchronise the user data. Otherwise synchronise the user and meta
438       data.
439
440       setxattr
441
442       Arguments: Pathname, extended attribute's name, extended attribute's
443       value, numeric flags (which is an OR-ing of XATTR_CREATE and
444       XATTR_REPLACE
445
446       Returns an errno or 0 on success.
447
448       Called to set the value of the named extended attribute.
449
450       If you wish to reject setting of a particular form of extended
451       attribute name (e.g.: regexps matching user\..* or security\..*), then
452       return - EOPNOTSUPP.
453
454       If flags is set to XATTR_CREATE and the extended attribute already
455       exists, this should fail with - EEXIST. If flags is set to
456       XATTR_REPLACE and the extended attribute doesn't exist, this should
457       fail with - ENOATTR.
458
459       XATTR_CREATE and XATTR_REPLACE are provided by this module, but not
460       exported by default. To import them:
461
462           use Fuse ':xattr';
463
464       or:
465
466           use Fuse ':all';
467
468       getxattr
469
470       Arguments: Pathname, extended attribute's name
471
472       Returns an errno, 0 if there was no value, or the extended attribute's
473       value.
474
475       Called to get the value of the named extended attribute.
476
477       listxattr
478
479       Arguments: Pathname
480
481       Returns a list: 0 or more text strings (the extended attribute names),
482       followed by a numeric errno (usually 0).
483
484       removexattr
485
486       Arguments: Pathname, extended attribute's name
487
488       Returns an errno or 0 on success.
489
490       Removes the named extended attribute (if present) from a file.
491
492       opendir
493
494       Arguments: Pathname of a directory Returns an errno, and a directory
495       handle (optional)
496
497       Called when opening a directory for reading. If special handling is
498       required to open a directory, this operation can be implemented to
499       handle that.
500
501       readdir
502
503       Arguments: Pathname of a directory, numeric offset, (optional)
504       directory handle
505
506       Returns a list of 0 or more entries, followed by a numeric errno
507       (usually 0).  The entries can be simple strings (filenames), or arrays
508       containing an offset number, the filename, and optionally an array ref
509       containing the stat values (as would be returned from getattr()).
510
511       This is used to read entries from a directory. It can be used to return
512       just entry names like getdir(), or can get a segment of the available
513       entries, which requires using array refs and the 2- or 3-item form,
514       with offset values starting from 1. If you wish to return the
515       parameters to fill each entry's struct stat, but do not wish to do
516       partial entry lists/entry counting, set the first element of each array
517       to 0 always.
518
519       Note that if this call is implemented, it overrides getdir() ALWAYS.
520
521       releasedir
522
523       Arguments: Pathname of a directory, (optional) directory handle
524
525       Returns an errno or 0 on success
526
527       Called when there are no more references to an opened directory. Called
528       once for each pathname or handle passed to opendir(). Similar to
529       release(), but for directories. Accepts a return value, but like
530       release(), the response code will not propagate to any corresponding
531       closedir() calls.
532
533       fsyncdir
534
535       Arguments: Pathname of a directory, numeric flags, (optional) directory
536       handle
537
538       Returns an errno or 0 on success.
539
540       Called to synchronize any changes to a directory's contents. If flag is
541       non-zero, only synchronize user data, otherwise synchronize user data
542       and metadata.
543
544       init
545
546       Arguments: None.
547
548       Returns (optionally) an SV to be passed as private_data via
549       fuse_get_context().
550
551       destroy
552
553       Arguments: (optional) private data SV returned from init(), if any.
554
555       Returns nothing.
556
557       access
558
559       Arguments: Pathname, access mode flags
560
561       Returns an errno or 0 on success.
562
563       Determine if the user attempting to access the indicated file has
564       access to perform the requested actions. The user ID can be determined
565       by calling fuse_get_context(). See access(2) for more information.
566
567       create
568
569       Arguments: Pathname, create mask, open mode flags
570
571       Returns errno or 0 on success, and (optional) file handle.
572
573       Create a file with the path indicated, then open a handle for reading
574       and/or writing with the supplied mode flags. Can also return a file
575       handle like open() as part of the call.
576
577       ftruncate
578
579       Arguments: Pathname, numeric offset, (optional) file handle
580
581       Returns errno or 0 on success
582
583       Like truncate(), but on an opened file.
584
585       fgetattr
586
587       Arguments: Pathname, (optional) file handle
588
589       Returns a list, very similar to the 'stat' function (see perlfunc).  On
590       error, simply return a single numeric scalar value (e.g. "return
591       -ENOENT();").
592
593       Like getattr(), but on an opened file.
594
595       lock
596
597       Arguments: Pathname, numeric command code, hashref containing lock
598       parameters, (optional) file handle
599
600       Returns errno or 0 on success
601
602       Used to lock or unlock regions of a file. Locking is handled locally,
603       but this allows (especially for networked file systems) for protocol-
604       level locking semantics to also be employed, if any are available.
605
606       See the Fuse documentation for more explanation of lock(). The needed
607       symbols for the lock constants can be obtained by importing Fcntl.
608
609       utimens
610
611       Arguments: Pathname, last accessed time, last modified time
612
613       Returns errno or 0 on success
614
615       Like utime(), but allows time resolution down to the nanosecond. By
616       default, times are passed as "numeric" (internally these are typically
617       represented as "double"), so the sub-second portion is represented as
618       fractions of a second. If you want times passed as arrays instead of
619       floating point values, for higher precision, you should pass the
620       "utimens_as_array" option to "Fuse::main".
621
622       Note that if this call is implemented, it overrides utime() ALWAYS.
623
624       bmap
625
626       Arguments: Pathname, numeric blocksize, numeric block number
627
628       Returns errno or 0 on success, and physical block number if successful
629
630       Used to map a block number offset in a file to the physical block
631       offset on the block device backing the file system. This is intended
632       for filesystems that are stored on an actual block device, with the
633       'blkdev' option passed.
634
635       ioctl
636
637       Arguments: Pathname, ioctl command code, flags, data if ioctl op is a
638       write, (optional) file handle
639
640       Returns errno or 0 on success, and data if ioctl op is a read
641
642       Used to handle ioctl() operations on files. See ioctl(2) for more
643       information on the fine details of ioctl operation numbers. May need to
644       h2ph system headers to get the necessary macros; keep in mind the
645       macros are highly OS-dependent.
646
647       Keep in mind that read and write are from the client perspective, so
648       read from our end means data is going *out*, and write means data is
649       coming *in*. It can be slightly confusing.
650
651       poll
652
653       Arguments: Pathname, poll handle ID (or undef if none), event mask,
654       (optional) file handle
655
656       Returns errno or 0 on success, and updated event mask on success
657
658       Used to handle poll() operations on files. See poll(2) to learn more
659       about event polling. Use IO::Poll to get the POLLIN, POLLOUT, and other
660       symbols to describe the events which can happen on the filehandle. Save
661       the poll handle ID to be passed to "notify_poll" and
662       "pollhandle_destroy" functions, if it is not undef. Threading will
663       likely be necessary for this operation to work.
664
665       There is not an "out of band" data transfer channel provided as part of
666       FUSE, so POLLPRI/POLLRDBAND/POLLWRBAND won't work.
667
668       Poll handle is currently a read-only scalar; we are investigating a way
669       to make this an object instead.
670
671       write_buf
672
673       Arguments: Pathname, offset, buffer vector, (optional) file handle.
674
675       Write contents of buffer to an open file.
676
677       Similar to the "write" method, but data is supplied in a generic
678       buffer.  Use fuse_buf_copy() to transfer data to the destination if
679       necessary.
680
681       read_buf
682
683       Arguments: Pathname, size, offset, buffer vector, (optional) file
684       handle.
685
686       Store data from an open file in a buffer.
687
688       Similar to the "read" method, but data is stored and returned in a
689       generic buffer.
690
691       No actual copying of data has to take place, the source file descriptor
692       may simply be placed in the 'fd' member of the buffer access hash (and
693       the 'flags' member OR'd with FUSE_BUF_IS_FD) for later retrieval.
694
695       Also, if the FUSE_BUF_FD_SEEK constant is OR'd with 'flags', the 'pos'
696       member should contain the offset (in bytes) to seek to in the file
697       descriptor.
698
699       If data is to be read, the read data should be placed in the 'mem'
700       member of the buffer access hash, and the 'size' member should be
701       updated if less data was read than requested.
702
703       flock
704
705       Arguments: pathname, (optional) file handle, unique lock owner ID,
706       operation ID
707
708       Perform BSD-style file locking operations.
709
710       Operation ID will be one of LOCK_SH, LOCK_EX or LOCK_UN. Non-blocking
711       lock requests will be indicated by having LOCK_NB OR'd into the value.
712
713       For more information, see the flock(2) manpage. For the lock symbols,
714       do:
715
716         use Fcntl qw(flock);
717
718       Locking is handled locally, but this allows (especially for networked
719       file systems) for protocol-level locking semantics to also be employed,
720       if any are available.
721
722       fallocate
723
724       Arguments: pathname, (optional) file handle, mode, offset, length
725
726       Allocates space for an open file.
727
728       This function ensures that required space is allocated for specified
729       file.  If this function returns success then any subsequent write
730       request to specified range is guaranteed not to fail because of lack of
731       space on the file system media.
732

EXAMPLES

734       There are a few example scripts in the examples/ subdirectory.  These
735       are:
736
737       example.pl
738
739               A simple "Hello world" type of script
740
741       loopback.pl
742
743               A filesystem loopback-device.  like fusexmp from the main FUSE dist,
744               it simply recurses file operations into the real filesystem.  Unlike
745               fusexmp, it only re-shares files under the /tmp/test directory.
746
747       rmount.pl
748
749               An NFS-workalike which tunnels through SSH. It requires an account
750               on some ssh server (obviously), with public-key authentication enabled.
751               (if you have to type in a password, you don't have this. man ssh_keygen.).
752               Copy rmount_remote.pl to your home directory on the remote machine
753               and make it executable. Then create a mountpoint subdir somewhere local,
754               and run the example script: ./rmount.pl host /remote/dir /local/dir
755
756       rmount_remote.pl
757
758               A ripoff of loopback.pl meant to be used as a backend for rmount.pl.
759

AUTHOR

761       Mark Glines, <mark@glines.org>
762

SEE ALSO

764       perl, the FUSE documentation.
765
766
767
768perl v5.36.0                      2023-01-20                           Fuse(3)
Impressum