fuse

package module
v0.0.0-...-8a08dd8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 15, 2013 License: BSD-3-Clause Imports: 13 Imported by: 0

Documentation

Overview

Package fuse enables writing FUSE file systems on FreeBSD, Linux, and OS X.

On OS X, it requires OSXFUSE (http://osxfuse.github.com/).

There are two approaches to writing a FUSE file system. The first is to speak the low-level message protocol, reading from a Conn using ReadRequest and writing using the various Respond methods. This approach is closest to the actual interaction with the kernel and can be the simplest one in contexts such as protocol translators.

Servers of synthesized file systems tend to share common bookkeeping abstracted away by the second approach, which is to call the Conn's Serve method to serve the FUSE protocol using an implementation of the service methods in the interfaces FS (file system), Node (file or directory), and Handle (opened file or directory). There are a daunting number of such methods that can be written, but few are required. The specific methods are described in the documentation for those interfaces.

The hellofs subdirectory contains a simple illustration of the ServeFS approach.

Service Methods

The required and optional methods for the FS, Node, and Handle interfaces have the general form

Op(req *OpRequest, resp *OpResponse, intr Intr) Error

where Op is the name of a FUSE operation. Op reads request parameters from req and writes results to resp. An operation whose only result is the error result omits the resp parameter. Multiple goroutines may call service methods simultaneously; the methods being called are responsible for appropriate synchronization.

Interrupted Operations

In some file systems, some operations may take an undetermined amount of time. For example, a Read waiting for a network message or a matching Write might wait indefinitely. If the request is cancelled and no longer needed, the package will close intr, a chan struct{}. Blocking operations should select on a receive from intr and attempt to abort the operation early if the receive succeeds (meaning the channel is closed). To indicate that the operation failed because it was aborted, return fuse.EINTR.

If an operation does not block for an indefinite amount of time, the intr parameter can be ignored.

Authentication

All requests types embed a Header, meaning that the method can inspect req.Pid, req.Uid, and req.Gid as necessary to implement permission checking. Alternately, XXX.

Mount Options

XXX

Index

Constants

View Source
const (
	// ENOSYS indicates that the call is not supported.
	ENOSYS = Errno(syscall.ENOSYS)

	// ESTALE is used by Serve to respond to violations of the FUSE protocol.
	ESTALE = Errno(syscall.ESTALE)

	ENOENT = Errno(syscall.ENOENT)
	EIO    = Errno(syscall.EIO)
	EPERM  = Errno(syscall.EPERM)

	// EINTR indicates request was interrupted by an InterruptRequest.
	// See also fs.Intr.
	EINTR = Errno(syscall.EINTR)
)
View Source
const Version = "7.8"

Version is the FUSE version implemented by the package.

Variables

View Source
var Debugf = nop

Functions

func AppendDirent

func AppendDirent(data []byte, dir Dirent) []byte

AppendDirent appends the encoded form of a directory entry to data and returns the resulting slice.

Types

type AccessRequest

type AccessRequest struct {
	Header
	Mask uint32
}

An AccessRequest asks whether the file can be accessed for the purpose specified by the mask.

func (*AccessRequest) Respond

func (r *AccessRequest) Respond()

Respond replies to the request indicating that access is allowed. To deny access, use RespondError.

func (*AccessRequest) String

func (r *AccessRequest) String() string

type Attr

type Attr struct {
	Inode  uint64      // inode number
	Size   uint64      // size in bytes
	Blocks uint64      // size in blocks
	Atime  time.Time   // time of last access
	Mtime  time.Time   // time of last modification
	Ctime  time.Time   // time of last inode change
	Crtime time.Time   // time of creation (OS X only)
	Mode   os.FileMode // file mode
	Nlink  uint32      // number of links
	Uid    uint32      // owner uid
	Gid    uint32      // group gid
	Rdev   uint32      // device numbers
	Flags  uint32      // chflags(2) flags (OS X only)
}

An Attr is the metadata for a single file or directory.

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

A Conn represents a connection to a mounted FUSE file system.

func Mount

func Mount(dir string) (*Conn, error)

Mount mounts a new FUSE connection on the named directory and returns a connection for reading and writing FUSE messages.

func (*Conn) ReadRequest

func (c *Conn) ReadRequest() (Request, error)

type CreateRequest

type CreateRequest struct {
	Header
	Name  string
	Flags uint32
	Mode  os.FileMode
}

A CreateRequest asks to create and open a file (not a directory).

func (*CreateRequest) Respond

func (r *CreateRequest) Respond(resp *CreateResponse)

Respond replies to the request with the given response.

func (*CreateRequest) String

func (r *CreateRequest) String() string

type CreateResponse

type CreateResponse struct {
	LookupResponse
	OpenResponse
}

A CreateResponse is the response to a CreateRequest. It describes the created node and opened handle.

func (*CreateResponse) String

func (r *CreateResponse) String() string

type DestroyRequest

type DestroyRequest struct {
	Header
}

A DestroyRequest is sent by the kernel when unmounting the file system. No more requests will be received after this one, but it should still be responded to.

func (*DestroyRequest) Respond

func (r *DestroyRequest) Respond()

Respond replies to the request.

func (*DestroyRequest) String

func (r *DestroyRequest) String() string

type Dirent

type Dirent struct {
	// Inode this entry names.
	Inode uint64

	// Type of the entry, for example DT_File.
	//
	// Setting this is optional. The zero value (DT_Unknown) means
	// callers will just need to do a Getattr when the type is
	// needed. Providing a type can speed up operations
	// significantly.
	Type DirentType

	// Name of the entry
	Name string
}

A Dirent represents a single directory entry.

type DirentType

type DirentType uint32

Type of an entry in a directory listing.

const (
	DT_Unknown DirentType = 0
	DT_Socket  DirentType = syscall.S_IFSOCK >> 12
	DT_Link    DirentType = syscall.S_IFLNK >> 12
	DT_File    DirentType = syscall.S_IFREG >> 12
	DT_Block   DirentType = syscall.S_IFBLK >> 12
	DT_Dir     DirentType = syscall.S_IFDIR >> 12
	DT_Char    DirentType = syscall.S_IFCHR >> 12
	DT_FIFO    DirentType = syscall.S_IFIFO >> 12
)

func (DirentType) String

func (t DirentType) String() string

type Errno

type Errno syscall.Errno

Errno implements Error using a syscall.Errno.

func (Errno) String

func (e Errno) String() string

type Error

type Error interface {
	// contains filtered or unexported methods
}

An Error is a FUSE error.

type FlushRequest

type FlushRequest struct {
	Header
	Handle    HandleID
	Flags     uint32
	LockOwner uint64
}

A FlushRequest asks for the current state of an open file to be flushed to storage, as when a file descriptor is being closed. A single opened Handle may receive multiple FlushRequests over its lifetime.

func (*FlushRequest) Respond

func (r *FlushRequest) Respond()

Respond replies to the request, indicating that the flush succeeded.

func (*FlushRequest) String

func (r *FlushRequest) String() string

type ForgetRequest

type ForgetRequest struct {
	Header
	N uint64
}

A ForgetRequest is sent by the kernel when forgetting about r.Node as returned by r.N lookup requests.

func (*ForgetRequest) Respond

func (r *ForgetRequest) Respond()

Respond replies to the request, indicating that the forgetfulness has been recorded.

func (*ForgetRequest) String

func (r *ForgetRequest) String() string

type FsyncRequest

type FsyncRequest struct {
	Header
	Handle HandleID
	Flags  uint32
}

func (*FsyncRequest) Respond

func (r *FsyncRequest) Respond()

func (*FsyncRequest) String

func (r *FsyncRequest) String() string

type GetattrRequest

type GetattrRequest struct {
	Header
}

A GetattrRequest asks for the metadata for the file denoted by r.Node.

func (*GetattrRequest) Respond

func (r *GetattrRequest) Respond(resp *GetattrResponse)

Respond replies to the request with the given response.

func (*GetattrRequest) String

func (r *GetattrRequest) String() string

type GetattrResponse

type GetattrResponse struct {
	AttrValid time.Duration // how long Attr can be cached
	Attr      Attr          // file attributes
}

A GetattrResponse is the response to a GetattrRequest.

func (*GetattrResponse) String

func (r *GetattrResponse) String() string

type GetxattrRequest

type GetxattrRequest struct {
	Header
	Size     uint32 // maximum size to return
	Position uint32 // offset within extended attributes
}

A GetxattrRequest asks for the extended attributes associated with r.Node.

func (*GetxattrRequest) Respond

func (r *GetxattrRequest) Respond(resp *GetxattrResponse)

Respond replies to the request with the given response.

func (*GetxattrRequest) String

func (r *GetxattrRequest) String() string

type GetxattrResponse

type GetxattrResponse struct {
	Xattr []byte
}

A GetxattrResponse is the response to a GetxattrRequest.

func (*GetxattrResponse) String

func (r *GetxattrResponse) String() string

type HandleID

type HandleID uint64

A HandleID is a number identifying an open directory or file. It only needs to be unique while the directory or file is open.

type Header struct {
	Conn *Conn     // connection this request was received on
	ID   RequestID // unique ID for request
	Node NodeID    // file or directory the request is about
	Uid  uint32    // user ID of process making request
	Gid  uint32    // group ID of process making request
	Pid  uint32    // process ID of process making request
}

A Header describes the basic information sent in every request.

func (*Header) Hdr

func (h *Header) Hdr() *Header

func (*Header) RespondError

func (h *Header) RespondError(err Error)

func (*Header) String

func (h *Header) String() string

type InitFlags

type InitFlags uint32

The InitFlags are used in the Init exchange.

const (
	InitAsyncRead  InitFlags = 1 << 0
	InitPosixLocks InitFlags = 1 << 1

	InitCaseSensitive InitFlags = 1 << 29 // OS X only
	InitVolRename     InitFlags = 1 << 30 // OS X only
	InitXtimes        InitFlags = 1 << 31 // OS X only
)

func (InitFlags) String

func (fl InitFlags) String() string

type InitRequest

type InitRequest struct {
	Header
	Major        uint32
	Minor        uint32
	MaxReadahead uint32
	Flags        InitFlags
}

An InitRequest is the first request sent on a FUSE file system.

func (*InitRequest) Respond

func (r *InitRequest) Respond(resp *InitResponse)

Respond replies to the request with the given response.

func (*InitRequest) String

func (r *InitRequest) String() string

type InitResponse

type InitResponse struct {
	MaxReadahead uint32
	Flags        InitFlags
	MaxWrite     uint32
}

An InitResponse is the response to an InitRequest.

func (*InitResponse) String

func (r *InitResponse) String() string

type InterruptRequest

type InterruptRequest struct {
	Header
	IntrID RequestID // ID of the request to be interrupt.
}

An InterruptRequest is a request to interrupt another pending request. The response to that request should return an error status of EINTR.

func (*InterruptRequest) Respond

func (r *InterruptRequest) Respond()

func (*InterruptRequest) String

func (r *InterruptRequest) String() string

type LinkRequest

type LinkRequest struct {
	Header
	OldNode NodeID
	NewName string
}

A LinkRequest is a request to create a hard link.

func (*LinkRequest) Respond

func (r *LinkRequest) Respond(resp *LookupResponse)

type ListxattrRequest

type ListxattrRequest struct {
	Header
	Size     uint32 // maximum size to return
	Position uint32 // offset within attribute list
}

A ListxattrRequest asks to list the extended attributes associated with r.Node.

func (*ListxattrRequest) Respond

func (r *ListxattrRequest) Respond(resp *ListxattrResponse)

Respond replies to the request with the given response.

func (*ListxattrRequest) String

func (r *ListxattrRequest) String() string

type ListxattrResponse

type ListxattrResponse struct {
	Xattr []byte
}

A ListxattrResponse is the response to a ListxattrRequest.

func (*ListxattrResponse) String

func (r *ListxattrResponse) String() string

type LookupRequest

type LookupRequest struct {
	Header
	Name string
}

A LookupRequest asks to look up the given name in the directory named by r.Node.

func (*LookupRequest) Respond

func (r *LookupRequest) Respond(resp *LookupResponse)

Respond replies to the request with the given response.

func (*LookupRequest) String

func (r *LookupRequest) String() string

type LookupResponse

type LookupResponse struct {
	Node       NodeID
	Generation uint64
	EntryValid time.Duration
	AttrValid  time.Duration
	Attr       Attr
}

A LookupResponse is the response to a LookupRequest.

func (*LookupResponse) String

func (r *LookupResponse) String() string

type MkdirRequest

type MkdirRequest struct {
	Header
	Name string
	Mode os.FileMode
}

A MkdirRequest asks to create (but not open) a directory.

func (*MkdirRequest) Respond

func (r *MkdirRequest) Respond(resp *MkdirResponse)

Respond replies to the request with the given response.

func (*MkdirRequest) String

func (r *MkdirRequest) String() string

type MkdirResponse

type MkdirResponse struct {
	LookupResponse
}

A MkdirResponse is the response to a MkdirRequest.

func (*MkdirResponse) String

func (r *MkdirResponse) String() string

type MknodRequest

type MknodRequest struct {
	Header
	Name string
	Mode os.FileMode
	Rdev uint32
}

func (*MknodRequest) Respond

func (r *MknodRequest) Respond(resp *LookupResponse)

func (*MknodRequest) String

func (r *MknodRequest) String() string

type NodeID

type NodeID uint64

A NodeID is a number identifying a directory or file. It must be unique among IDs returned in LookupResponses that have not yet been forgotten by ForgetRequests.

const RootID NodeID = rootID

The RootID identifies the root directory of a FUSE file system.

type OpenFlags

type OpenFlags uint32

The OpenFlags are returned in the OpenResponse.

const (
	OpenDirectIO    OpenFlags = 1 << 0 // bypass page cache for this open file
	OpenKeepCache   OpenFlags = 1 << 1 // don't invalidate the data cache on open
	OpenNonSeekable OpenFlags = 1 << 2 // (Linux?)

	OpenPurgeAttr OpenFlags = 1 << 30 // OS X
	OpenPurgeUBC  OpenFlags = 1 << 31 // OS X
)

func (OpenFlags) String

func (fl OpenFlags) String() string

type OpenRequest

type OpenRequest struct {
	Header
	Dir   bool // is this Opendir?
	Flags uint32
	Mode  os.FileMode
}

An OpenRequest asks to open a file or directory

func (*OpenRequest) Respond

func (r *OpenRequest) Respond(resp *OpenResponse)

Respond replies to the request with the given response.

func (*OpenRequest) String

func (r *OpenRequest) String() string

type OpenResponse

type OpenResponse struct {
	Handle HandleID
	Flags  OpenFlags
}

A OpenResponse is the response to a OpenRequest.

func (*OpenResponse) String

func (r *OpenResponse) String() string

type ReadRequest

type ReadRequest struct {
	Header
	Dir    bool // is this Readdir?
	Handle HandleID
	Offset int64
	Size   int
}

A ReadRequest asks to read from an open file.

func (*ReadRequest) Respond

func (r *ReadRequest) Respond(resp *ReadResponse)

Respond replies to the request with the given response.

func (*ReadRequest) String

func (r *ReadRequest) String() string

type ReadResponse

type ReadResponse struct {
	Data []byte
}

A ReadResponse is the response to a ReadRequest.

func (*ReadResponse) String

func (r *ReadResponse) String() string

type ReadlinkRequest

type ReadlinkRequest struct {
	Header
}

A ReadlinkRequest is a request to read a symlink's target.

func (*ReadlinkRequest) Respond

func (r *ReadlinkRequest) Respond(target string)

func (*ReadlinkRequest) String

func (r *ReadlinkRequest) String() string

type ReleaseFlags

type ReleaseFlags uint32

The ReleaseFlags are used in the Release exchange.

const (
	ReleaseFlush ReleaseFlags = 1 << 0
)

func (ReleaseFlags) String

func (fl ReleaseFlags) String() string

type ReleaseRequest

type ReleaseRequest struct {
	Header
	Dir          bool // is this Releasedir?
	Handle       HandleID
	Flags        uint32 // flags from OpenRequest
	ReleaseFlags ReleaseFlags
	LockOwner    uint32
}

A ReleaseRequest asks to release (close) an open file handle.

func (*ReleaseRequest) Respond

func (r *ReleaseRequest) Respond()

Respond replies to the request, indicating that the handle has been released.

func (*ReleaseRequest) String

func (r *ReleaseRequest) String() string

type RemoveRequest

type RemoveRequest struct {
	Header
	Name string // name of extended attribute
	Dir  bool   // is this rmdir?
}

A RemoveRequest asks to remove a file or directory.

func (*RemoveRequest) Respond

func (r *RemoveRequest) Respond()

Respond replies to the request, indicating that the file was removed.

func (*RemoveRequest) String

func (r *RemoveRequest) String() string

type RemovexattrRequest

type RemovexattrRequest struct {
	Header
	Name string // name of extended attribute
}

A RemovexattrRequest asks to remove an extended attribute associated with r.Node.

func (*RemovexattrRequest) Respond

func (r *RemovexattrRequest) Respond()

Respond replies to the request, indicating that the attribute was removed.

func (*RemovexattrRequest) String

func (r *RemovexattrRequest) String() string

type RenameRequest

type RenameRequest struct {
	Header
	NewDir           NodeID
	OldName, NewName string
}

A RenameRequest is a request to rename a file.

func (*RenameRequest) Respond

func (r *RenameRequest) Respond()

func (*RenameRequest) String

func (r *RenameRequest) String() string

type Request

type Request interface {
	// Hdr returns the Header associated with this request.
	Hdr() *Header

	// RespondError responds to the request with the given error.
	RespondError(Error)

	String() string
}

A Request represents a single FUSE request received from the kernel. Use a type switch to determine the specific kind. A request of unrecognized type will have concrete type *Header.

type RequestID

type RequestID uint64

A RequestID identifies an active FUSE request.

type SetattrRequest

type SetattrRequest struct {
	Header
	Valid  SetattrValid
	Handle HandleID
	Size   uint64
	Atime  time.Time
	Mtime  time.Time
	Mode   os.FileMode
	Uid    uint32
	Gid    uint32

	// OS X only
	Bkuptime time.Time
	Chgtime  time.Time
	Crtime   time.Time
	Flags    uint32 // see chflags(2)
}

A SetattrRequest asks to change one or more attributes associated with a file, as indicated by Valid.

func (*SetattrRequest) Respond

func (r *SetattrRequest) Respond(resp *SetattrResponse)

Respond replies to the request with the given response, giving the updated attributes.

func (*SetattrRequest) String

func (r *SetattrRequest) String() string

type SetattrResponse

type SetattrResponse struct {
	AttrValid time.Duration // how long Attr can be cached
	Attr      Attr          // file attributes
}

A SetattrResponse is the response to a SetattrRequest.

func (*SetattrResponse) String

func (r *SetattrResponse) String() string

type SetattrValid

type SetattrValid uint32

The SetattrValid are bit flags describing which fields in the SetattrRequest are included in the change.

const (
	SetattrMode   SetattrValid = 1 << 0
	SetattrUid    SetattrValid = 1 << 1
	SetattrGid    SetattrValid = 1 << 2
	SetattrSize   SetattrValid = 1 << 3
	SetattrAtime  SetattrValid = 1 << 4
	SetattrMtime  SetattrValid = 1 << 5
	SetattrHandle SetattrValid = 1 << 6

	// Linux only(?)
	SetattrAtimeNow  SetattrValid = 1 << 7
	SetattrMtimeNow  SetattrValid = 1 << 8
	SetattrLockOwner SetattrValid = 1 << 9 // http://www.mail-archive.com/git-commits-head@vger.kernel.org/msg27852.html

	// OS X only
	SetattrCrtime   SetattrValid = 1 << 28
	SetattrChgtime  SetattrValid = 1 << 29
	SetattrBkuptime SetattrValid = 1 << 30
	SetattrFlags    SetattrValid = 1 << 31
)

func (SetattrValid) Atime

func (fl SetattrValid) Atime() bool

func (SetattrValid) AtimeNow

func (fl SetattrValid) AtimeNow() bool

func (SetattrValid) Bkuptime

func (fl SetattrValid) Bkuptime() bool

func (SetattrValid) Chgtime

func (fl SetattrValid) Chgtime() bool

func (SetattrValid) Crtime

func (fl SetattrValid) Crtime() bool

func (SetattrValid) Flags

func (fl SetattrValid) Flags() bool

func (SetattrValid) Gid

func (fl SetattrValid) Gid() bool

func (SetattrValid) Handle

func (fl SetattrValid) Handle() bool

func (SetattrValid) LockOwner

func (fl SetattrValid) LockOwner() bool

func (SetattrValid) Mode

func (fl SetattrValid) Mode() bool

func (SetattrValid) Mtime

func (fl SetattrValid) Mtime() bool

func (SetattrValid) MtimeNow

func (fl SetattrValid) MtimeNow() bool

func (SetattrValid) Size

func (fl SetattrValid) Size() bool

func (SetattrValid) String

func (fl SetattrValid) String() string

func (SetattrValid) Uid

func (fl SetattrValid) Uid() bool

type SetxattrRequest

type SetxattrRequest struct {
	Header
	Flags    uint32
	Position uint32 // OS X only
	Name     string
	Xattr    []byte
}

A SetxattrRequest asks to set an extended attribute associated with a file.

func (*SetxattrRequest) Respond

func (r *SetxattrRequest) Respond()

Respond replies to the request, indicating that the extended attribute was set.

func (*SetxattrRequest) String

func (r *SetxattrRequest) String() string

type StatfsRequest

type StatfsRequest struct {
	Header
}

A StatfsRequest requests information about the mounted file system.

func (*StatfsRequest) Respond

func (r *StatfsRequest) Respond(resp *StatfsResponse)

Respond replies to the request with the given response.

func (*StatfsRequest) String

func (r *StatfsRequest) String() string

type StatfsResponse

type StatfsResponse struct {
	Blocks  uint64 // Total data blocks in file system.
	Bfree   uint64 // Free blocks in file system.
	Bavail  uint64 // Free blocks in file system if you're not root.
	Files   uint64 // Total files in file system.
	Ffree   uint64 // Free files in file system.
	Bsize   uint32 // Block size
	Namelen uint32 // Maximum file name length?
	Frsize  uint32 // ?
}

A StatfsResponse is the response to a StatfsRequest.

func (*StatfsResponse) String

func (r *StatfsResponse) String() string

type SymlinkRequest

type SymlinkRequest struct {
	Header
	NewName, Target string
}

A SymlinkRequest is a request to create a symlink making NewName point to Target.

func (*SymlinkRequest) Respond

func (r *SymlinkRequest) Respond(resp *SymlinkResponse)

Respond replies to the request, indicating that the symlink was created.

func (*SymlinkRequest) String

func (r *SymlinkRequest) String() string

type SymlinkResponse

type SymlinkResponse struct {
	LookupResponse
}

A SymlinkResponse is the response to a SymlinkRequest.

type WriteFlags

type WriteFlags uint32

The WriteFlags are returned in the WriteResponse.

func (WriteFlags) String

func (fl WriteFlags) String() string

type WriteRequest

type WriteRequest struct {
	Header
	Handle HandleID
	Offset int64
	Data   []byte
	Flags  WriteFlags
}

A WriteRequest asks to write to an open file.

func (*WriteRequest) Respond

func (r *WriteRequest) Respond(resp *WriteResponse)

Respond replies to the request with the given response.

func (*WriteRequest) String

func (r *WriteRequest) String() string

type WriteResponse

type WriteResponse struct {
	Size int
}

A WriteResponse replies to a write indicating how many bytes were written.

func (*WriteResponse) String

func (r *WriteResponse) String() string

Notes

Bugs

  • The mount code for FreeBSD has not been written yet.

Directories

Path Synopsis
Hellofs implements a simple "hello world" file system.
Hellofs implements a simple "hello world" file system.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL