SYNOPSYS
import "clive/zx"
const KiB = 1024 ...
const All = -1
const Sstat Call = iota ...
const None ChgType = iota ...
var ErrNotExist = errors.New("no such file or directory") ...
var StdAttrOrder = [...]string{
"name",
"type",
"mode",
"size",
"mtime",
"uid",
"gid",
"wuid",
"path",
"addr",
"err",
}
func Elems(p string) []string
func EqualDirs(d1, d2 Dir) bool
func GetAll(fs Getter, p string) ([]byte, error)
func GetDir(fs Getter, p string) ([]Dir, error)
func HasPrefix(p, pref string) bool
func IsExists(e error) bool
func IsIOError(e error) bool
func IsNotEmpty(e error) bool
func IsNotExist(e error) bool
func IsPerm(e error) bool
func IsStd(attr string) bool
func IsTemp(name string) bool
func Path(elems ...string) string
func PathCmp(path0, path1 string) int
func PathPrefixMatch(p, exp string) bool
func PutAll(fs Putter, path string, data []byte, mode ...string) error
func SortDirs(ds []Dir)
func Suffix(p, pref string) string
func UnpackAddr(b []byte) ([]byte, Addr, error)
func UnpackDir(b []byte) ([]byte, Dir, error)
func UseAbsPath(s string) (string, error)
func ParseAddr(s string) Addr
func ParseDir(s string) (Dir, error)
func Stat(fs Fs, p string) (Dir, error)
func MakeRO(fs Fs) Getter
type Addr struct { ... }
func ParseAddr(s string) Addr
type Auther interface { ... }
type Call int
type Chg struct { ... }
type ChgType int
type Dir map[string]string
func ParseDir(s string) (Dir, error)
func Stat(fs Fs, p string) (Dir, error)
type FindGetter interface { ... }
type Finder interface { ... }
type Flags struct { ... }
type Fs interface { ... }
type FullFs interface { ... }
type Getter interface { ... }
func MakeRO(fs Fs) Getter
type Linker interface { ... }
type Mover interface { ... }
type Putter interface { ... }
type RWFs interface { ... }
type Remover interface { ... }
type Stats struct { ... }
type Syncer interface { ... }
type Wstater interface { ... }
DESCRIPTION
Clive ZX file system tools.
The service in ZX is split in two parts: finders are used to find directory
entries; trees are used to operate on them.
CONSTANTS
const (
KiB = 1024
MiB = 1024 * KiB
GiB = 1024 * MiB
TiB = 1024 * GiB
)
const All = -1
TYPES
type Addr struct {
Name string // file or resource name
Ln0, Ln1 int // line range or zero
P0, P1 int // point (rune) range or zero
}
File addresses as handled by some commands
func ParseAddr(s string) Addr
func (a Addr) String() string
func (a Addr) TypeId() uint16
func (a Addr) Unpack(b []byte) (interface{}, error)
func (a Addr) WriteTo(w io.Writer) (n int64, err error)
type Auther interface {
// returns a new view of the Fs authenticated for ai
Auth(ai *auth.Info) (Fs, error)
}
File systems that can authenticate a user
type Call int
Statistics
const (
Sstat Call = iota // calls to stat
Sget // calls to get
Sput // calls to put
Smove // calls to move
Slink // calls to link
Sremove // calls to remove/all
Swstat // calls to wstat
Sfind // calls to find
Scall // totals for all calls.
Nstats // number of stats.
)
type Chg struct {
Type ChgType
D Dir
Time time.Time
Err error
}
A change made to a tree wrt another tree
func (c Chg) String() string
type ChgType int
A type of change between two trees
const (
None ChgType = iota
Add // file was added
Data // file data was changed
Meta // file metadata was changed
Del // file was deleted
DirFile // dir replaced with file or file replaced with dir
Err // had an error while proceding the dir
)
func (ct ChgType) String() string
type Dir map[string]string
A Dir, or directory entry, identifices a file or a resource in the system.
It is a set of attribute/value pairs, including some conventional attributes
like "name", "size", etc.
Attributes starting with upper-case are considered as temporary and won't be
updated by any file system.
Directory entries are self-describing in many cases, and include the address
and resource path as known by the server as extra attributes. Thus, programs
can operate on streams of Dir entries and ask each entry to perform an
operation on the resource it described.
The purpose of very important interfaces in the system, like ns.Finder and
zx.Tree is to operate on Dirs.
func ParseDir(s string) (Dir, error)
Parse a string as produced by Dir.String() and return the dir
func Stat(fs Fs, p string) (Dir, error)
Do a Stat on fs and return the reply now
func (d Dir) Attrs() []string
Return the set of attributes with values, sorted in std order.
func (d Dir) Bytes() []byte
func (d Dir) Can(ai *auth.Info, what int) bool
To check with 0111 | 0222 | 0444.
func (d Dir) CanExec(ai *auth.Info) bool
can this auth info exec this file? If ai is nil, owner's role is assumed.
func (d Dir) CanGet(ai *auth.Info) bool
can this auth info get data from this file? If ai is nil, owner's role is
assumed.
func (d Dir) CanPut(ai *auth.Info) bool
can this auth info put data in this file? If ai is nil, owner's role is
assumed.
func (d Dir) CanWalk(ai *auth.Info) bool
can this auth info walk this file? If ai is nil, owner's role is assumed.
func (d Dir) CanWstat(ai *auth.Info, nd Dir) error
can this auth info do this wstat to this file? If ai is nil, owner's role is
assumed. path, addr, type, wuid, and name are never updated so they are
ignored. Only the owner can udpate the mode Updating the size is ok if
CanPut(), and it's ignored for directories. The owner can update the group
or the owner if it's a member of the target owner/group. The owner and group
members may update other attributes
func (d Dir) DbFmt() string
Print d in a format suitable for keeping a db of file metadata.
func (d Dir) Dup() Dir
Make a dup of the dir entry.
func (d Dir) Fmt() string
Print d in std format
func (d Dir) Inherit(parent uint64)
Adjust mode bits to inherit group bits cleared/set from the parent
func (d Dir) IsFinder() bool
Return true if this entry refers to a server supporting the finder protocol
func (d Dir) LongFmt() string
Print d in long std format
func (e Dir) Matches(d Dir) bool
Does e match the attributes in d? Attributes match if their values match.
The special value "*" matches any defined attribute value.
func (d Dir) Mode() uint64
Return mode bits (only 0777)
func (d Dir) Proto() string
Return the protocol to reach the resource, return "" if no address is set.
func (d Dir) SAddr() string
Return the address for the resource server, including the protocol. Returns
"" if no address is set.
func (d Dir) SPath() string
Return the server path for the resource Returns the path if there's no
server path
func (d Dir) SetMode(mode uint64)
Set a mode attribute (only bits 0777)
func (d Dir) SetSize(size int64)
Set the size attribute
func (d Dir) SetTime(name string, t time.Time)
Set a time attribute
func (d Dir) SetUint(name string, v uint64)
Set the int value cleanly formatted
func (d Dir) Size() int64
Get the size attribute
func (d Dir) String() string
Return a string that can be parsed later.
func (d Dir) SysDup() Dir
Make a dup of the dir entry w/o temporary attributes
func (d Dir) TestFmt() string
Print d in test format. All values are quoted, mtime is removed. u.Uid is
replaced with "elf" in all uids
func (d Dir) Time(attr string) time.Time
Get the (time) value for a time attribute at dir.
func (d Dir) TypeId() uint16
func (d Dir) Uint(attr string) uint64
Get the value for an integer attribute at dir. If the attribute is mode,
base 8 is used.
func (d Dir) Unpack(b []byte) (interface{}, error)
func (d Dir) WriteTo(w io.Writer) (n int64, err error)
type FindGetter interface {
// This is like Find(), but streams through the returned channel the file
// data after each matching Dir.
// errors during Get()s are also streamed.
FindGet(path, pred string, spref, dpref string, depth0 int) <-chan interface{}
}
File systems able to both find and get directory entries in a single RPC
type Finder interface {
// Navigate the tree starting at path to find files matching the predicate
// pred. Found entries are sent through the returned channel.
// Those with errors are decorated with an "err" attribute indicating the error,
// and they might not match the predicate given to find, if they convey just the error.
//
// The server must consider that the path for a file /a/b/c is actually /x/b/c if
// spref is /a and dpref is /y. That is, spref is replaced with dpref in paths
// before evaluating the predicate. This is used to evaluate paths as seen by the users
// without having to rewrite the predicates at each mount point.
//
// The depth for the path given, once walked, starts at depth0 (and not 0), again,
// to evaluate the pred in entries as seen by the user
//
Find(path, pred string, spref, dpref string, depth0 int) <-chan Dir
}
File systems able to find directory entries
type Flags struct {
// contains filtered or unexported fields
}
Flags for Fs implementors and to aid in Ctl requests.
func (t *Flags) Add(name string, vp interface{})
Add a user defined flag to the flag set. vp must be a pointer type. Known
flag types are *bool, *int, *string, and func(...string)error
func (t *Flags) AddRO(name string, vp interface{})
Add a read-only user defined flag to the flag set. vp must be a pointer
type. Known flag types are *bool, *int, and *string
func (t *Flags) Ctl(cmd string) error
Parse a string of the form and set the flag or return
an error. Only for user-defined flags. Add t.Dbg and t.NoPermCheck if you
want them here. For each boolean flag with name , the clts
[1|on|y|yes]
set the flag, and the ctls
no
[none of 1|on|y|yes]
clear the flag
func (t *Flags) Set(name string, v interface{}) error
Set the named flag to the given value
func (t *Flags) String() string
Return a string describing the flag values Only for user-defined flags. Add
t.Dbg and t.NoPermCheck if you want them here.
type Fs interface {
// Return the directory entry for the file at path.
Stat(p string) <-chan Dir
}
A zx file system. It must provide at least Stats.
type FullFs interface {
Getter
Putter
Wstater
Remover
Mover
Linker
Finder
FindGetter
}
Full file systems including find and link
type Getter interface {
Fs
// Retrieve the contents of the file at path.
// For directories, off and count refer to the number of
// directory entries, counting from 0.
// A count of -1 means "everything".
// Each directory entry is returned as a []byte with the format
// produced by Dir.Bytes(),
// The end of the file (or dir) is signaled with an empty message.
Get(path string, off, count int64) <-chan []byte
}
File systems able to get file contents
func MakeRO(fs Fs) Getter
Take a fs and make it read-only If fs supports get, find, findget, auth,
sync, close, then the corresponding methods are forwarded, otherwise they
exist but fail with errors.
type Linker interface {
// Link new to refer to old
Link(oldp, newp string) <-chan error
}
File systems able to link files
type Mover interface {
// Move file src to be at dst
// If from is to, the op is a nop.
// Otherwise, it is an error to mv to or from / and /Ctl.
Move(from, to string) <-chan error
}
File systems able to move files
type Putter interface {
// Update or create a file at the given path with the attributes
// found in d and the data sent through dc.
// If d is nil or d["type"] is not defined, the file is not
// created if it does not exist; otherwise it is used as it is.
// "-" is the type for files, and "d" for directories.
// If d["size"] is defined, the file is truncated to that size before
// writing the data.
// If extra attributes are included in d, they are also updated.
// If off is < 0 then the new data is appended to the file.
// Note off<0 makes sense even if d["mode"] is defined.
// The file mtime and size after the put, or the error is reported
// through the returned channel.
// If d["type"] is "d", then dc is ignored and a directory is created
// (unless it already exists, in which case it's ok)
// If d["type"] is "F", it means "-" but parent directories are
// created if they do not exist.
// If d["type"] is "D", it means "d" but parent directories are created
// if they do not exist.
Put(path string, d Dir, off int64, dc <-chan []byte) <-chan Dir
}
File systems able to put files
type RWFs interface {
Getter
Putter
Wstater
Remover
}
Typical file systems with usual read/write ops,
type Remover interface {
// Delete the file or empty directory found at path.
Remove(path string) <-chan error
// Delete the file or directory found at path.
RemoveAll(path string) <-chan error
}
File systems able to remove files Removing "/" always fails
type Stats struct {
sync.Mutex
Nb [Nstats]int64
}
Stats for FS implementors
func (s *Stats) Clear()
func (s *Stats) Count(what Call)
func (s *Stats) String() string
type Syncer interface {
Sync() error
}
File systems that need/have sync()
type Wstater interface {
// Update attributes for the file at path with those from d
// and return the resulting directory entry
Wstat(path string, d Dir) <-chan Dir
}
File systems able to wstat files
FUNCTIONS
func Elems(p string) []string
Return path elements, empty for /
func EqualDirs(d1, d2 Dir) bool
Return true if both directory entries have exactly the same attributes and
values. the addr attribute is ignored.
func GetAll(fs Getter, p string) ([]byte, error)
Get all contents for a file
func GetDir(fs Getter, p string) ([]Dir, error)
Get all dir entries
func HasPrefix(p, pref string) bool
Return true if pref is a prefix path of p (or the same path)
func IsExists(e error) bool
func IsIOError(e error) bool
func IsNotEmpty(e error) bool
func IsNotExist(e error) bool
func IsPerm(e error) bool
func IsStd(attr string) bool
func IsTemp(name string) bool
Is this the name of a temporary attribute (starts with upcase)
func Path(elems ...string) string
Make a path starting with / for elems
func PathCmp(path0, path1 string) int
returns -1,0, or 1 if the path a is found before, at or after b like string
compare but operates on one element at a time to compare.
func PathPrefixMatch(p, exp string) bool
Match expr against any element name if it's not /... or match it against any
prefix of p
func PutAll(fs Putter, path string, data []byte, mode ...string) error
Put all contents for a file, creating it.
func SortDirs(ds []Dir)
Sort dir entries by name
func Suffix(p, pref string) string
Return the suffix of p relative to base Both paths must be absolute or both
relative. Pref can be empty. If there's no such suffix, the empty string is
returned. The suffix starts with '/' and is "/" if b == p
func UnpackAddr(b []byte) ([]byte, Addr, error)
func UnpackDir(b []byte) ([]byte, Dir, error)
func UseAbsPath(s string) (string, error)
Make sure s is an absolute path and return it cleaned and never empty.
VARIABLES
var (
ErrNotExist = errors.New("no such file or directory")
ErrExists = errors.New("file already exists")
ErrIsDir = errors.New("file is a directory")
ErrNotDir = errors.New("not a directory")
ErrPerm = errors.New("permission denied")
ErrBug = errors.New("buggered or not implemented")
ErrNotEmpty = errors.New("directory not empty")
ErrRO = errors.New("resource is read-only")
ErrBadCtl = errors.New("bad ctl request")
ErrNotSuffix = errors.New("not an inner path")
ErrBadType = errors.New("bad file type")
ErrIO = ch.ErrIO
)
Popular errors
var (
// Preferred order for prints of std attributes
StdAttrOrder = [...]string{
"name",
"type",
"mode",
"size",
"mtime",
"uid",
"gid",
"wuid",
"path",
"addr",
"err",
}
)
Laboratorio de Sistemas // Systems Lab
Clive, 2nd ed. User's manual. Section 2
Copyright © LSUB 2014-2016
