1Fuse(3) User Contributed Perl Documentation Fuse(3)
2
6 Fuse - write filesystems in Perl using FUSE
7
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
15 This lets you implement filesystems in perl, through the FUSE
16 (Filesystem in USErspace) kernel/lib interface.
17 FUSE expects you to implement callbacks for the various functions.
19 In the following definitions, "errno" can be 0 (for a success),
21 -EINVAL, -ENOENT, -EONFIRE, any integer less than 1 really.
22 You can import standard error constants by saying something like "use
24 POSIX qw(EDOTDOT ENOANO);".
25 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 EXPORTED SYMBOLS
31 None by default.
32 You can request all exportable symbols by using the tag ":all".
34 You can request the extended attribute symbols by using the tag
36 ":xattr". This will export XATTR_CREATE and XATTR_REPLACE.
37 FUNCTIONS
39 Fuse::main
40 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 debug => boolean
47 This turns FUSE call tracing on and off. Default is 0 (which means
48 off).
49 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 mountopts => string
55 This is a comma separated list of mount options to pass to the FUSE
56 kernel module.
57 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 mountopts => "allow_other" or
63 mountopts => ""
64 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 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 (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 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 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 nopath => boolean
107 Flag indicating that the path need not be calculated for the following
108 operations:
109 read, write, flush, release, fsync, readdir, releasedir, fsyncdir,
111 ftruncate, fgetattr, lock, ioctl and poll
112 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 Only effective on Fuse 2.9 and up.
119 utime_omit_ok => boolean
121 Flag indicating that the filesystem accepts special UTIME_NOW and
122 UTIME_OMIT values in its "utimens" operation.
123 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 Only effective on Fuse 2.9 and up.
128 Fuse::fuse_get_context
130 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 Access context information about the current Fuse operation.
137 Fuse::fuse_version
139 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 Fuse::fuse_buf_size
148 Computes the total size of a buffer vector. Applicable for "read_buf"
150 and "write_buf" operations.
151 Fuse::fuse_buf_copy
153 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 Fuse::notify_poll
159 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 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 Fuse::pollhandle_destroy
178 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 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 FUNCTIONS YOUR FILESYSTEM MAY IMPLEMENT
195 getattr
196 Arguments: filename.
198 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 FIXME: the "ino" field is currently ignored. I tried setting it to 0
204 in an example script, which consistently caused segfaults.
205 Fields (the following was stolen from perlfunc(1) with apologies):
207 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
209 $atime,$mtime,$ctime,$blksize,$blocks)
210 = getattr($filename);
211 Here are the meaning of the fields:
213 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 (The epoch was at 00:00 January 1, 1970 GMT.)
230 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 readlink
241 Arguments: link pathname.
243 Returns a scalar: either a numeric constant, or a text string.
245 This is called when dereferencing symbolic links, to learn the target.
247 example rv: return "/proc/self/fd/stdin";
249 getdir
251 Arguments: Containing directory name.
253 Returns a list: 0 or more text strings (the filenames), followed by a
255 numeric errno (usually 0).
256 This is used to obtain directory listings. It's opendir(), readdir(),
258 filldir() and closedir() all in one call.
259 example rv: return ('.', 'a', 'b', 0);
261 mknod
263 Arguments: Filename, numeric modes, numeric device
265 Returns an errno (0 upon success, as usual).
267 This function is called for all non-directory, non-symlink nodes, not
269 just devices.
270 mkdir
272 Arguments: New directory pathname, numeric modes.
274 Returns an errno.
276 Called to create a directory.
278 unlink
280 Arguments: Filename.
282 Returns an errno.
284 Called to remove a file, device, or symlink.
286 rmdir
288 Arguments: Pathname.
290 Returns an errno.
292 Called to remove a directory.
294 symlink
296 Arguments: Existing filename, symlink name.
298 Returns an errno.
300 Called to create a symbolic link.
302 rename
304 Arguments: old filename, new filename.
306 Returns an errno.
308 Called to rename a file, and/or move a file from one directory to
310 another.
311 link
313 Arguments: Existing filename, hardlink name.
315 Returns an errno.
317 Called to create hard links.
319 chmod
321 Arguments: Pathname, numeric modes.
323 Returns an errno.
325 Called to change permissions on a file/directory/device/symlink.
327 chown
329 Arguments: Pathname, numeric uid, numeric gid.
331 Returns an errno.
333 Called to change ownership of a file/directory/device/symlink.
335 truncate
337 Arguments: Pathname, numeric offset.
339 Returns an errno.
341 Called to truncate a file, at the given offset.
343 utime
345 Arguments: Pathname, numeric actime, numeric modtime.
347 Returns an errno.
349 Called to change access/modification times for a
351 file/directory/device/symlink.
352 open
354 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 Returns an errno, a file handle (optional).
360 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 read
373 Arguments: Pathname, numeric requested size, numeric offset, file
375 handle
376 Returns a numeric errno, or a string scalar with up to $requestedsize
378 bytes of data.
379 Called in an attempt to fetch a portion of the file.
381 write
383 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 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 statfs
393 Arguments: none
395 Returns any of the following:
397 -ENOANO()
399 or
401 $namelen, $files, $files_free, $blocks, $blocks_avail, $blocksize
403 or
405 -ENOANO(), $namelen, $files, $files_free, $blocks, $blocks_avail,
407 $blocksize
408 flush
410 Arguments: Pathname, file handle
412 Returns an errno or 0 on success.
414 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 release
419 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 Returns an errno or 0 on success.
425 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 fsync
431 Arguments: Pathname, numeric flags
433 Returns an errno or 0 on success.
435 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 setxattr
441 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 Returns an errno or 0 on success.
447 Called to set the value of the named extended attribute.
449 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 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 XATTR_CREATE and XATTR_REPLACE are provided by this module, but not
460 exported by default. To import them:
461 use Fuse ':xattr';
463 or:
465 use Fuse ':all';
467 getxattr
469 Arguments: Pathname, extended attribute's name
471 Returns an errno, 0 if there was no value, or the extended attribute's
473 value.
474 Called to get the value of the named extended attribute.
476 listxattr
478 Arguments: Pathname
480 Returns a list: 0 or more text strings (the extended attribute names),
482 followed by a numeric errno (usually 0).
483 removexattr
485 Arguments: Pathname, extended attribute's name
487 Returns an errno or 0 on success.
489 Removes the named extended attribute (if present) from a file.
491 opendir
493 Arguments: Pathname of a directory Returns an errno, and a directory
495 handle (optional)
496 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 readdir
502 Arguments: Pathname of a directory, numeric offset, (optional)
504 directory handle
505 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 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 Note that if this call is implemented, it overrides getdir() ALWAYS.
520 releasedir
522 Arguments: Pathname of a directory, (optional) directory handle
524 Returns an errno or 0 on success
526 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 fsyncdir
534 Arguments: Pathname of a directory, numeric flags, (optional) directory
536 handle
537 Returns an errno or 0 on success.
539 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 init
545 Arguments: None.
547 Returns (optionally) an SV to be passed as private_data via
549 fuse_get_context().
550 destroy
552 Arguments: (optional) private data SV returned from init(), if any.
554 Returns nothing.
556 access
558 Arguments: Pathname, access mode flags
560 Returns an errno or 0 on success.
562 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 create
568 Arguments: Pathname, create mask, open mode flags
570 Returns errno or 0 on success, and (optional) file handle.
572 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 ftruncate
578 Arguments: Pathname, numeric offset, (optional) file handle
580 Returns errno or 0 on success
582 Like truncate(), but on an opened file.
584 fgetattr
586 Arguments: Pathname, (optional) file handle
588 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 Like getattr(), but on an opened file.
594 lock
596 Arguments: Pathname, numeric command code, hashref containing lock
598 parameters, (optional) file handle
599 Returns errno or 0 on success
601 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 See the Fuse documentation for more explanation of lock(). The needed
607 symbols for the lock constants can be obtained by importing Fcntl.
608 utimens
610 Arguments: Pathname, last accessed time, last modified time
612 Returns errno or 0 on success
614 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 Note that if this call is implemented, it overrides utime() ALWAYS.
623 bmap
625 Arguments: Pathname, numeric blocksize, numeric block number
627 Returns errno or 0 on success, and physical block number if successful
629 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 ioctl
636 Arguments: Pathname, ioctl command code, flags, data if ioctl op is a
638 write, (optional) file handle
639 Returns errno or 0 on success, and data if ioctl op is a read
641 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 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 poll
652 Arguments: Pathname, poll handle ID (or undef if none), event mask,
654 (optional) file handle
655 Returns errno or 0 on success, and updated event mask on success
657 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 There is not an "out of band" data transfer channel provided as part of
666 FUSE, so POLLPRI/POLLRDBAND/POLLWRBAND won't work.
667 Poll handle is currently a read-only scalar; we are investigating a way
669 to make this an object instead.
670 write_buf
672 Arguments: Pathname, offset, buffer vector, (optional) file handle.
674 Write contents of buffer to an open file.
676 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 read_buf
682 Arguments: Pathname, size, offset, buffer vector, (optional) file
684 handle.
685 Store data from an open file in a buffer.
687 Similar to the "read" method, but data is stored and returned in a
689 generic buffer.
690 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 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 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 flock
704 Arguments: pathname, (optional) file handle, unique lock owner ID,
706 operation ID
707 Perform BSD-style file locking operations.
709 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 For more information, see the flock(2) manpage. For the lock symbols,
714 do:
715 use Fcntl qw(flock);
717 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 fallocate
723 Arguments: pathname, (optional) file handle, mode, offset, length
725 Allocates space for an open file.
727 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
734 There are a few example scripts in the examples/ subdirectory. These
735 are:
736 example.pl
738 A simple "Hello world" type of script
740 loopback.pl
742 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 rmount.pl
748 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 rmount_remote.pl
757 A ripoff of loopback.pl meant to be used as a backend for rmount.pl.
759
761 Mark Glines, <mark@glines.org>
762
764 perl, the FUSE documentation.
765perl v5.38.0 2023-07-20 Fuse(3)