ninep

README

A client library for the 9p file system protocol, implementing the io/fs file system interface (see original Draft document).

Documentation for 9p can be found at http://man.cat-v.org/plan_9/5/.

Documentation

Overview

Package ninep implements the 9P protocol.

Index

• Constants
• func ModeString(mode uint32) string
• type AttachOpts
• type Authenticator
• type ClientConn
  • func Dial(service string, opts DialOpts) (dConn *ClientConn, dErr error)
  • func (c *ClientConn) Attach(ctx context.Context, fid uint32, afid uint32, uname string, aname string) (qid QID, err error)
  • func (c *ClientConn) Auth(ctx context.Context, afid uint32, uname, aname string) (qid QID, err error)
  • func (c *ClientConn) Close() error
  • func (c *ClientConn) Clunk(ctx context.Context, fid uint32) (err error)
  • func (c *ClientConn) Flush(oldtag uint16) (err error)
  • func (c *ClientConn) Open(ctx context.Context, fid uint32, mode uint8) (qid QID, iounit uint32, err error)
  • func (c *ClientConn) Read(ctx context.Context, fid uint32, offset uint64, buf []byte) (n uint32, err error)
  • func (c *ClientConn) Stat(ctx context.Context, fid uint32) (stat Stat, err error)
  • func (c *ClientConn) Walk(ctx context.Context, fid, newfid uint32, wname []string) (qids []QID, err error)
  • func (c *ClientConn) Write(ctx context.Context, fid uint32, offset uint64, data []byte) (n uint32, err error)
• type DialFSOpts
• type DialOpts
• type FS
  • func Attach(cc *ClientConn, opts AttachOpts) (fsys *FS, err error)
  • func DialFS(service string, opts DialFSOpts) (dFS *FS, dErr error)
  • func (f *FS) Close() error
  • func (f *FS) Open(name string) (filp fs.File, openErr error)
  • func (f *FS) OpenFile(name string, mode uint8) (filp fs.File, openErr error)
• type QID
  • func (q QID) IsDirectory() bool
  • func (q QID) String() string
• type Stat

Constants

const (
	ORead   = 0x0
	OWrite  = 0x1
	ORdWr   = 0x2
	OExec   = 0x3
	OTrunc  = 0x10 // truncate
	ORClose = 0x40 // delete on clunk
)

Modes for opening and creating files, as defined in open(9p).

const (
	Tversion = 100
	Rversion = 101
	Tauth    = 102
	Rauth    = 103
	Tattach  = 104
	Rattach  = 105
	/* There is no request for errors. */
	Rerror  = 107
	Tflush  = 108
	Rflush  = 109
	Twalk   = 110
	Rwalk   = 111
	Topen   = 112
	Ropen   = 113
	Tcreate = 114
	Rcreate = 115
	Tread   = 116
	Rread   = 117
	Twrite  = 118
	Rwrite  = 119
	Tclunk  = 120
	Rclunk  = 121
	Tremove = 122
	Rremove = 123
	Tstat   = 124
	Rstat   = 125
	Twstat  = 126
	Rwstat  = 127
	// Plan9 from User Space extensions
	Topenfd = 98
	Ropenfd = 99
)

Every 9P message has an associated type indicating its contents and wire format:

const (
	ModeDir    = 0x80000000
	ModeAppend = 0x40000000
	ModeExcl   = 0x20000000
	ModeMount  = 0x10000000
	ModeAuth   = 0x08000000
	ModeTmp    = 0x04000000
)

9p Stat mode flags for file meta-information.

const (
	ModeUnixDev   = 0x00800000
	ModeSymlink   = 0x00400000
	ModeNamedPipe = 0x00200000
	ModeSocket    = 0x00100000
)

9P2000.u extensions to 9p Stat mode flags.

const (
	ModeUserRead   = 0400
	ModeUserWrite  = 0200
	ModeUserExec   = 0100
	ModeGroupRead  = 0040
	ModeGroupWrite = 0020
	ModeGroupExec  = 0010
	ModeOtherRead  = 0004
	ModeOtherWrite = 0002
	ModeOtherExec  = 0001
)

The read, write and execute bits are stored in the three least significant octets of Stat.Mode, for user, group and others.

const (
	QTDIR    = 0x80 // type bit for directories
	QTAPPEND = 0x40 // type bit for append only files
	QTEXCL   = 0x20 // type bit for exclusive use files
	QTMOUNT  = 0x10 // type bit for mounted channel
	QTAUTH   = 0x08 // type bit for authentication file
	QTTMP    = 0x04 // type bit for not-backed-up file
	QTFILE   = 0x00 // plain file
)

bits in QID.Kind, from sys/include/libc.h

Functions

func ModeString

func ModeString(mode uint32) string

ModeString builds a "ls" style mode string for the given mode value. For example, ModeString(0744) == "-rwxr--r--".

Types

type AttachOpts

type AttachOpts struct {
	// Username to attach with
	Uname string

	// The remote file system to attach to
	Aname string

	// Authenticator
	Authenticator Authenticator
}

type Authenticator

type Authenticator func(io.ReadWriter) error

type ClientConn

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

ClientConn represents a connection to a 9p server.

func Dial

func Dial(service string, opts DialOpts) (dConn *ClientConn, dErr error)

Dial establishes a 9p client connection and returns it.

func (*ClientConn) Attach

func (c *ClientConn) Attach(ctx context.Context, fid uint32, afid uint32, uname string, aname string) (qid QID, err error)

func (*ClientConn) Auth

func (c *ClientConn) Auth(ctx context.Context, afid uint32, uname, aname string) (qid QID, err error)

func (*ClientConn) Close

func (c *ClientConn) Close() error

Close closes the 9p connection.

func (*ClientConn) Clunk

func (c *ClientConn) Clunk(ctx context.Context, fid uint32) (err error)

func (*ClientConn) Flush

func (c *ClientConn) Flush(oldtag uint16) (err error)

TODO: Do callers need to check the error?

func (*ClientConn) Open

func (c *ClientConn) Open(ctx context.Context, fid uint32, mode uint8) (qid QID, iounit uint32, err error)

func (*ClientConn) Read

func (c *ClientConn) Read(ctx context.Context, fid uint32, offset uint64, buf []byte) (n uint32, err error)

Read from an open fid.

offset indicates the offset into the file where to read. buf is the buffer to read into and may not be larger than the fid's iounit as returned by Open().

func (*ClientConn) Stat

func (c *ClientConn) Stat(ctx context.Context, fid uint32) (stat Stat, err error)

func (*ClientConn) Walk

func (c *ClientConn) Walk(ctx context.Context, fid, newfid uint32, wname []string) (qids []QID, err error)

func (*ClientConn) Write

func (c *ClientConn) Write(ctx context.Context, fid uint32, offset uint64, data []byte) (n uint32, err error)

type DialFSOpts

type DialFSOpts struct {
	DialOpts
	AttachOpts
}

type DialOpts

type DialOpts struct {
	Concurrency uint16
}

type FS

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

func Attach

func Attach(cc *ClientConn, opts AttachOpts) (fsys *FS, err error)

Attach opens a file system from an already-open client connection.

func DialFS

func DialFS(service string, opts DialFSOpts) (dFS *FS, dErr error)

DialFS dials a 9p client connection and directly attaches to it.

func (*FS) Close

func (f *FS) Close() error

Close closes the underlying file system connection. Closing the FS before discarding already opened files is an error.

func (*FS) Open

func (f *FS) Open(name string) (filp fs.File, openErr error)

Open opens a file for reading.

func (*FS) OpenFile

func (f *FS) OpenFile(name string, mode uint8) (filp fs.File, openErr error)

OpenFile is the generalized open call.

Remark: This is not part of io/fs.FS.

type QID

type QID struct {
	Kind uint8  // uchar (normally called "Type")
	Vers uint32 // ulong
	Path uint64 // uvlong
}

QID in Plan9 is defined in libc.h

func (QID) IsDirectory

func (q QID) IsDirectory() bool

func (QID) String

func (q QID) String() string

type Stat

type Stat struct {
	Type uint16 // for kernel use
	Dev  uint32 // for kernel use
	// The type of the file (directory etc.)  represented as a bit
	// vector corresponding to the high 8 bits of the file's mode
	// word.
	QID    QID
	Mode   uint32 // permissions and flags
	Atime  uint32 // last access time
	Mtime  uint32 // last modification time
	Length uint64 // length of file in bytes
	Name   string // file name; must be / if the file is the root
	UID    string // owner's name
	GID    string // group's name
	MUID   string // name of the user who last modified the file
}

Stat represents a directory entry in 9p.