fusefs

package
v0.31.0 Latest Latest
Warning

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

 Go to latest Published: Jun 19, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package fusefs provides a read-only filesystem interface over pxar archives, compatible with hanwen/go-fuse's InodeEmbedder and Inode interfaces.

This package does NOT import go-fuse. It defines compatible interfaces (FileSystem, Attr, DirEntry) so callers can wrap them into a go-fuse FileSystem without the library requiring the dependency.

Basic Usage

Open a pxar archive and create a Session: 

f, err := os.Open("backup.pxar")
defer f.Close()
fi, _ := f.Stat()

sess, err := fusefs.NewSession(f, fi.Size())
if err != nil {
    log.Fatal(err)
}
defer sess.Close()

Filesystem Operations

Session implements the FileSystem interface: 

// Look up a file in a directory
inode, attr, err := sess.Lookup(fusefs.RootInode, "example.txt")

// Read file data
sess.Open(inode, 0)
buf := make([]byte, attr.Size)
n, err := sess.Read(inode, buf, 0)

// List directory
entries, err := sess.Readdir(fusefs.RootInode, 0)

// Read symlink target
target, err := sess.Readlink(symlinkInode)

Inode Model

The root directory uses inode 1 (RootInode). Non-directory inodes have the NonDirBit (bit 63) set. Use IsDirInode to distinguish: 

fusefs.IsDirInode(inode) // true if directory

Nodes track entry ranges and optional content ranges for file data access. Reference counting is handled automatically via Ref/Unref/Forget.

Package fusefs provides a read-only filesystem interface over pxar archives, compatible with hanwen/go-fuse's InodeEmbedder and Inode interfaces.

This package does NOT import go-fuse — it defines compatible interfaces so callers can wrap them into a go-fuse FileSystem without the library needing the dependency.

Index

Constants

View Source 
const (
	// RootInode is the inode number for the root directory.
	RootInode = 1

	// NonDirBit is set in the high bit of inodes for non-directory entries.
	NonDirBit uint64 = 1 << 63
)

Variables

This section is empty.

Functions

func IsDirInode 

func IsDirInode(inode uint64) bool

IsDirInode returns true if the inode represents a directory.

Types

type Attr 

type Attr struct {
	Ino       uint64
	Size      uint64
	Blocks    uint64
	Atime     uint64
	Mtime     uint64
	Ctime     uint64
	Atimensec uint32
	Mtimensec uint32
	Ctimensec uint32
	Mode      uint32
	Nlink     uint32
	Uid       uint32
	Gid       uint32
	Rdev      uint32
	Blksize   uint32
}

Attr represents file metadata, compatible with go-fuse's fuse.Attr.

func StatToAttr 

func StatToAttr(inode uint64, stat format.Stat, fileSize uint64) Attr

StatToAttr converts pxar metadata to FUSE Attr.

type ContentRange 

type ContentRange struct {
	Offset uint64
	Size   uint64
}

ContentRange describes where file content lives in the archive.

type DirEntry 

type DirEntry struct {
	Name string
	Ino  uint64
	Mode uint32
}

DirEntry is a directory entry, compatible with go-fuse's fuse.DirEntry.

type DirEntryIndex 

type DirEntryIndex struct {
	DirEntry
	Offset uint64
}

DirEntryIndex adds an offset to DirEntry for readdir pagination.

type EntryRangeInfo 

type EntryRangeInfo struct {
	Start uint64
	End   uint64
}

EntryRangeInfo describes where an entry lives in the archive.

type FileSystem 

type FileSystem interface {
	// Lookup finds a child entry by name in the given parent directory inode.
	Lookup(parentInode uint64, name string) (inode uint64, attr Attr, err error)

	// Getattr returns the attributes for the given inode.
	Getattr(inode uint64) (Attr, error)

	// Readdir returns directory entries starting at the given offset.
	// Returns entries and the next offset. An empty slice signals end-of-directory.
	Readdir(inode uint64, offset uint64) ([]DirEntryIndex, error)

	// Open informs the kernel that the file is being opened.
	Open(inode uint64, flags uint32) error

	// Read reads data from a file inode at the given offset.
	// FUSE requires no short reads (except at EOF).
	Read(inode uint64, dest []byte, offset int64) (int, error)

	// Readlink returns the symlink target for the given inode.
	Readlink(inode uint64) (string, error)

	// ListXAttr returns all extended attribute names for the given inode.
	ListXAttr(inode uint64) ([]string, error)

	// GetXAttr returns the value of a specific extended attribute.
	GetXAttr(inode uint64, attr string) ([]byte, error)

	// Forget decrements the reference count for an inode.
	Forget(inode uint64, count uint64)

	// Statfs returns filesystem statistics.
	Statfs() (syscall.Statfs_t, error)

	// Access checks file accessibility.
	Access(inode uint64, mask uint32) error

	// Release is called when a file is closed.
	Release(inode uint64)
}

FileSystem is the interface that maps pxar archive entries to FUSE operations. It is compatible with hanwen/go-fuse's InodeEmbedder and RawFileSystem patterns.

type Node 

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

Node holds cached metadata for a filesystem entry.

func (*Node) Cache 

func (n *Node) Cache() (format.Stat, uint64, bool)

Cache returns cached stat metadata.

func (*Node) Content 

func (n *Node) Content() (offset, size uint64, ok bool)

Content returns the content offset and size.

func (*Node) EntryRange 

func (n *Node) EntryRange() (start, end uint64)

EntryRange returns the entry's byte range in the archive.

func (*Node) Inode 

func (n *Node) Inode() uint64

Inode returns the node's inode number.

func (*Node) Parent 

func (n *Node) Parent() uint64

Parent returns the parent inode.

func (*Node) Ref 

func (n *Node) Ref() bool

Ref increments the reference count. Returns false if the node is already dead.

func (*Node) SetCache 

func (n *Node) SetCache(stat format.Stat, fileSize uint64)

SetCache stores cached stat metadata.

func (*Node) SetContent 

func (n *Node) SetContent(offset, size uint64)

SetContent sets the file content location in the archive.

func (*Node) Unref 

func (n *Node) Unref(count uint64) bool

Unref decrements the reference count. Returns true if the node should be removed.

type Session 

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

Session implements FileSystem over a pxar archive, providing FUSE-compatible operations without importing go-fuse directly.

func NewSession 

func NewSession(r io.ReadSeeker, size int64) (*Session, error)

NewSession creates a new FUSE filesystem session over a pxar archive.

func (*Session) Access 

func (s *Session) Access(inode uint64, mask uint32) error

Access checks file accessibility (always allowed for read-only).

func (*Session) Close 

func (s *Session) Close() error

Close releases resources held by the session.

func (*Session) Forget 

func (s *Session) Forget(inode uint64, count uint64)

Forget decrements the reference count for an inode.

func (*Session) GetXAttr 

func (s *Session) GetXAttr(inode uint64, attr string) ([]byte, error)

GetXAttr returns the value of a specific extended attribute.

func (*Session) Getattr 

func (s *Session) Getattr(inode uint64) (Attr, error)

Getattr returns attributes for the given inode.

func (*Session) ListXAttr 

func (s *Session) ListXAttr(inode uint64) ([]string, error)

ListXAttr returns extended attribute names.

func (*Session) Lookup 

func (s *Session) Lookup(parentInode uint64, name string) (uint64, Attr, error)

Lookup finds a child entry by name in the given parent directory.

func (*Session) Open 

func (s *Session) Open(inode uint64, flags uint32) error

Open is a no-op for read-only archives.

func (*Session) Read 

func (s *Session) Read(inode uint64, dest []byte, offset int64) (int, error)

Read reads data from a file. FUSE requires no short reads except at EOF.

Fast path: when the underlying reader implements io.ReaderAt, Read snapshots the content range under s.mu and then calls ReadAt without holding the lock, allowing concurrent FUSE reads to proceed in parallel.

Slow path: for plain io.ReadSeeker, falls back to locked Seek+ReadFull.

func (*Session) Readdir 

func (s *Session) Readdir(inode uint64, offset uint64) ([]DirEntryIndex, error)

Readdir returns directory entries starting at the given offset. 

func (s *Session) Readlink(inode uint64) (string, error)

Readlink returns the symlink target.

func (*Session) Release 

func (s *Session) Release(inode uint64)

Release is a no-op.

func (*Session) Statfs 

func (s *Session) Statfs() (syscall.Statfs_t, error)

Statfs returns filesystem statistics.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.