README
¶
This package allows for writing and mounting user-space file systems from Go. Install it as follows:
go get -u github.com/jacobsa/fuse
Afterward, see the documentation for the following three packages:
-
Package fuse provides support for mounting a new file system and reading requests from the kernel.
-
Package fuseops enumerates the supported requests from the kernel, and provides documentation on their semantics.
-
Package fuseutil, in particular the
FileSysteminterface, provides a convenient way to create a file system type and export it to the kernel viafuse.Mount.
Make sure to also see the sub-packages of the samples package for examples and tests.
This package owes its inspiration and most of its kernel-related code to bazil.org/fuse.
Documentation
¶
Overview ¶
Package fuse enables writing and mounting user-space file systems.
The primary elements of interest are:
The fuseops package, which defines the operations that fuse might send to your userspace daemon.
The Server interface, which your daemon must implement.
fuseutil.NewFileSystemServer, which offers a convenient way to implement the Server interface.
Mount, a function that allows for mounting a Server as a file system.
Make sure to see the examples in the sub-packages of samples/, which double as tests for this package: http://godoc.org/github.com/jacobsa/fuse/samples
In order to use this package to mount file systems on OS X, the system must have FUSE for OS X installed (see http://osxfuse.github.io/). Do note that there are several OS X-specific oddities; grep through the documentation for more info.
Index ¶
Constants ¶
const ( // Errors corresponding to kernel error numbers. These may be treated // specially by Connection.Reply. EEXIST = syscall.EEXIST EINVAL = syscall.EINVAL EIO = syscall.EIO ENOATTR = syscall.ENODATA ENOENT = syscall.ENOENT ENOSYS = syscall.ENOSYS ENOTDIR = syscall.ENOTDIR ENOTEMPTY = syscall.ENOTEMPTY )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Connection ¶
type Connection struct {
// contains filtered or unexported fields
}
Connection represents a connection to the fuse kernel process. It is used to receive and reply to requests from the kernel.
func (*Connection) Init ¶
func (c *Connection) Init() error
Init performs the work necessary to cause the mount process to complete.
func (*Connection) ReadOp ¶
func (c *Connection) ReadOp() (_ context.Context, op interface{}, _ error)
ReadOp consumes the next op from the kernel process, returning the op and a context that should be used for work related to the op. It returns io.EOF if the kernel has closed the connection.
If err != nil, the user is responsible for later calling c.Reply with the returned context.
This function delivers ops in exactly the order they are received from /dev/fuse. It must not be called multiple times concurrently.
LOCKS_EXCLUDED(c.mu)
type MountConfig ¶
type MountConfig struct {
// The context from which every op read from the connetion by the sever
// should inherit. If nil, context.Background() will be used.
OpContext context.Context
// If non-empty, the name of the file system as displayed by e.g. `mount`.
// This is important because the `umount` command requires root privileges if
// it doesn't agree with /etc/fstab.
FSName string
// Mount the file system in read-only mode. File modes will appear as normal,
// but opening a file for writing and metadata operations like chmod,
// chtimes, etc. will fail.
ReadOnly bool
// A logger to use for logging errors. All errors are logged, with the
// exception of a few blacklisted errors that are expected. If nil, no error
// logging is performed.
ErrorLogger *log.Logger
// A logger to use for logging debug information. If nil, no debug logging is
// performed.
DebugLogger *log.Logger
// Linux only. OS X always behaves as if writeback caching is disabled.
//
// By default on Linux we allow the kernel to perform writeback caching
// (cf. http://goo.gl/LdZzo1):
//
// * When the user calls write(2), the kernel sticks the user's data into
// its page cache. Only later does it call through to the file system,
// potentially after coalescing multiple small user writes.
//
// * The file system may receive multiple write ops from the kernel
// concurrently if there is a lot of page cache data to flush.
//
// * Write performance may be significantly improved due to the user and
// the kernel not waiting for serial round trips to the file system. This
// is especially true if the user makes tiny writes.
//
// * close(2) (and anything else calling f_op->flush) causes all dirty
// pages to be written out before it proceeds to send a FlushFileOp
// (cf. https://goo.gl/TMrY6X).
//
// * Similarly, close(2) causes the kernel to send a setattr request
// filling in the mtime if any dirty pages were flushed, since the time
// at which the pages were written to the file system can't be trusted.
//
// * close(2) (and anything else calling f_op->flush) writes out all dirty
// pages, then sends a setattr request with an appropriate mtime for
// those writes if there were any, and only then proceeds to send a
// flush.
//
// Code walk:
//
// * (https://goo.gl/zTIZQ9) fuse_flush calls write_inode_now before
// calling the file system. The latter eventually calls into
// __writeback_single_inode.
//
// * (https://goo.gl/L7Z2w5) __writeback_single_inode calls
// do_writepages, which writes out any dirty pages.
//
// * (https://goo.gl/DOPgla) __writeback_single_inode later calls
// write_inode, which calls into the superblock op struct's write_inode
// member. For fuse, this is fuse_write_inode
// (cf. https://goo.gl/eDSKOX).
//
// * (https://goo.gl/PbkGA1) fuse_write_inode calls fuse_flush_times.
//
// * (https://goo.gl/ig8x9V) fuse_flush_times sends a setttr request
// for setting the inode's mtime.
//
// However, this brings along some caveats:
//
// * The file system must handle SetInodeAttributesOp or close(2) will fail,
// due to the call chain into fuse_flush_times listed above.
//
// * The kernel caches mtime and ctime regardless of whether the file
// system tells it to do so, disregarding the result of further getattr
// requests (cf. https://goo.gl/3ZZMUw, https://goo.gl/7WtQUp). It
// appears this may be true of the file size, too. Writeback caching may
// therefore not be suitable for file systems where these attributes can
// spontaneously change for reasons the kernel doesn't observe. See
// http://goo.gl/V5WQCN for more discussion.
//
// Setting DisableWritebackCaching disables this behavior. Instead the file
// system is called one or more times for each write(2), and the user's
// syscall doesn't return until the file system returns.
DisableWritebackCaching bool
// OS X only.
//
// Normally on OS X we mount with the novncache option
// (cf. http://goo.gl/1pTjuk), which disables entry caching in the kernel.
// This is because osxfuse does not honor the entry expiration values we
// return to it, instead caching potentially forever (cf.
// http://goo.gl/8yR0Ie), and it is probably better to fail to cache than to
// cache for too long, since the latter is more likely to hide consistency
// bugs that are difficult to detect and diagnose.
//
// This field disables the use of novncache, restoring entry caching. Beware:
// the value of ChildInodeEntry.EntryExpiration is ignored by the kernel, and
// entries will be cached for an arbitrarily long time.
EnableVnodeCaching bool
// Linux only.
//
// Linux 4.20 introduced caching symlink targets in the page cache:
// https://github.com/torvalds/linux/commit/5571f1e65486be025f73fa6aa30fb03725d362a2
//
// This is not enabled by default because the old behavior masked a bug:
// file systems could return any size in the inode attributes of
// symlinks. After enabling caching, the specified size caps the symlink
// target.
EnableSymlinkCaching bool
// Linux only.
//
// Tell the kernel to treat returning -ENOSYS on OpenFile as not needing
// OpenFile calls at all (Linux >= 3.16):
EnableNoOpenSupport bool
// Linux only.
//
// Tell the kernel to treat returning -ENOSYS on OpenDir as not needing
// OpenDir calls at all (Linux >= 5.1):
EnableNoOpendirSupport bool
// OS X only.
//
// The name of the mounted volume, as displayed in the Finder. If empty, a
// default name involving the string 'osxfuse' is used.
VolumeName string
// Additional key=value options to pass unadulterated to the underlying mount
// command. See `man 8 mount`, the fuse documentation, etc. for
// system-specific information.
//
// For expert use only! May invalidate other guarantees made in the
// documentation for this package.
Options map[string]string
// Sets the filesystem type (third field in /etc/mtab). /etc/mtab and
// /proc/mounts will show the filesystem type as fuse.<Subtype>.
// If not set, /proc/mounts will show the filesystem type as fuse/fuseblk.
Subtype string
}
Optional configuration accepted by Mount.
type MountedFileSystem ¶
type MountedFileSystem struct {
// contains filtered or unexported fields
}
MountedFileSystem represents the status of a mount operation, with a method that waits for unmounting.
func Mount ¶
func Mount( dir string, server Server, config *MountConfig) (*MountedFileSystem, error)
Mount attempts to mount a file system on the given directory, using the supplied Server to serve connection requests. It blocks until the file system is successfully mounted.
func (*MountedFileSystem) Dir ¶
func (mfs *MountedFileSystem) Dir() string
Dir returns the directory on which the file system is mounted (or where we attempted to mount it.)
func (*MountedFileSystem) Join ¶
func (mfs *MountedFileSystem) Join(ctx context.Context) error
Join blocks until a mounted file system has been unmounted. It does not return successfully until all ops read from the connection have been responded to (i.e. the file system server has finished processing all in-flight ops).
The return value will be non-nil if anything unexpected happened while serving. May be called multiple times.
type Server ¶
type Server interface {
// Read and serve ops from the supplied connection until EOF. Do not return
// until all operations have been responded to. Must not be called more than
// once.
ServeOps(*Connection)
}
Server is an interface for any type that knows how to serve ops read from a connection.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package fuseops contains ops that may be returned by fuse.Connection.ReadOp.
|
Package fuseops contains ops that may be returned by fuse.Connection.ReadOp. |
|
Types and functions that make it easier to work with package fuse.
|
Types and functions that make it easier to work with package fuse. |
|
internal
|
|
|
mount_sample
A simple tool for mounting sample file systems, used by the tests in samples/.
|
A simple tool for mounting sample file systems, used by the tests in samples/. |