fsys

README

go-fsys

fsys provides an alternative means of accessing regular (for now...) files on a unix filesystem.

it is easier than using syscall.___(), but much simpler than os.File{} in implementation. the latter where possible provides I/O over the netpoll system built-in to the runtime, which is a little overkill if you're just writing a little utility binary. it also provides protection for concurrent access, which again is a little overkill in some situations.

don't use this unless you know what you're doing, or unless you're stupid / reckless and willing to ride life by the seat of your jorts like me.

Documentation

Index

• Variables
• func IsExistErr(err error) bool
• func IsNotFoundErr(err error) bool
• func IsPermissionErr(err error) bool
• func OpenDir(path string, mode int, perm uint32) (dir *Dir, stat Stat, err error)
• func OpenFile(path string, mode int, perm uint32) (file *File, stat Stat, err error)
• type Dir
  • func NewDir(fd int, filepath string) *Dir
  • func (f *Dir) Chdir() (err error)
  • func (f *Dir) Chmod(mode uint32) (err error)
  • func (f *Dir) Chown(uid, gid int) (err error)
  • func (d *Dir) IterDirents(buf []byte, fn func(*Dirent) error) (err error)
  • func (f *Dir) Path() string
  • func (d *Dir) ReadDirents(buf []byte) (ents []Dirent, err error)
  • func (f *Dir) Stat() (stat Stat, err error)
• type Dirent
  • func (d *Dirent) IsCurDir() bool
  • func (d *Dirent) IsPrevDir() bool
  • func (d *Dirent) Name_() string
• type File
  • func NewFile(fd int, filepath string) *File
  • func Stderr() *File
  • func Stdin() *File
  • func Stdout() *File
  • func (f *File) Chdir() (err error)
  • func (f *File) Chmod(mode uint32) (err error)
  • func (f *File) Chown(uid, gid int) (err error)
  • func (f *File) Fallocate(mode uint32, off int64, len int64) error
  • func (f *File) Path() string
  • func (f *File) Read(b []byte) (nn int, err error)
  • func (f *File) Seek(offset int64, whence int) (off int64, err error)
  • func (f *File) Stat() (stat Stat, err error)
  • func (f *File) Sync() error
  • func (f *File) Write(b []byte) (nn int, err error)
  • func (f *File) WriteString(s string) (int, error)
• type Stat

Variables

var (
	// ErrUnsupported is returned on attempt to open a directory as File{}, or non-directory as Dir{}.
	ErrUnsupported = errors.New("unsupported file mode")

	// ErrAlreadyClosed is returned on use of a closed (also, I guess, unopened) file.
	ErrAlreadyClosed = errors.New("use of closed file")

	// StopIterator is a flag error used to signify early return in iterator functions. It will never be returned.
	StopIterator = errors.New("[BUG]: ErrStopIter should never be returned")
)

Functions

func IsExistErr

func IsExistErr(err error) bool

func IsNotFoundErr

func IsNotFoundErr(err error) bool

func IsPermissionErr

func IsPermissionErr(err error) bool

func OpenDir

func OpenDir(path string, mode int, perm uint32) (dir *Dir, stat Stat, err error)

OpenDir will open file descriptor at path with mode and permissions (must be directory).

func OpenFile

func OpenFile(path string, mode int, perm uint32) (file *File, stat Stat, err error)

OpenFile will open file descriptor at path with mode and permissions (must be regular file / symlink to).

Types

type Dir

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

Dir represents a (directory) file descriptor, providing syscall helper methods. Note that it skips a lot of the nuances offered by os.File{} for other file types, and provides no form of protection for concurrent use.

func NewDir

func NewDir(fd int, filepath string) *Dir

NewDir returns a new Dir instance from given file descriptor and path.

func (*Dir) Chdir

func (f *Dir) Chdir() (err error)

Chdir will call fchdir on file descriptor.

func (*Dir) Chmod

func (f *Dir) Chmod(mode uint32) (err error)

Chmod will call fchmod() on file descriptor.

func (*Dir) Chown

func (f *Dir) Chown(uid, gid int) (err error)

Chown will call fchown() on file descriptor.

func (*Dir) IterDirents

func (d *Dir) IterDirents(buf []byte, fn func(*Dirent) error) (err error)

IterDirents calls getdents() on file descriptor, using given buffer. Entries are passed to fn.

func (*Dir) Path

func (f *Dir) Path() string

Path returns the filesystem path associated with this file.

func (*Dir) ReadDirents

func (d *Dir) ReadDirents(buf []byte) (ents []Dirent, err error)

ReadDirents calls getdents() on file descriptor, using given buffer.

func (*Dir) Stat

func (f *Dir) Stat() (stat Stat, err error)

Stat will call fstat() on file descriptor and return the results.

type Dirent

type Dirent unix.Dirent

Dirent is a type alias to unix.Dirent.

func (*Dirent) IsCurDir

func (d *Dirent) IsCurDir() bool

IsCurDir returns whether Dirent represents ".".

func (*Dirent) IsPrevDir

func (d *Dirent) IsPrevDir() bool

IsPrevDir returns whether Dirent represents "..".

func (*Dirent) Name_

func (d *Dirent) Name_() string

Name_ returns the Dirent name as usable Go string.

type File

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

File represents a (non-dir) file descriptor, providing syscall helper methods. Note that it skips a lot of the nuances offered by os.File{} for other file types, and provides no form of protection for concurrent use.

func NewFile

func NewFile(fd int, filepath string) *File

NewFile returns a new File instance from given file descriptor and path.

func Stderr

func Stderr() *File

func Stdin

func Stdin() *File

Stdin, Stdout, and Stderr return File structures pointing to standard input, standard output and standard error. These are returned as new objects each time due to the lack of concurrency protection within the File structure itself.

func Stdout

func Stdout() *File

func (*File) Chdir

func (f *File) Chdir() (err error)

Chdir will call fchdir on file descriptor.

func (*File) Chmod

func (f *File) Chmod(mode uint32) (err error)

Chmod will call fchmod() on file descriptor.

func (*File) Chown

func (f *File) Chown(uid, gid int) (err error)

Chown will call fchown() on file descriptor.

func (*File) Fallocate

func (f *File) Fallocate(mode uint32, off int64, len int64) error

Fallocate will call fallocate() with given mode, offset and legnth on file descriptor.

func (*File) Path

func (f *File) Path() string

Path returns the filesystem path associated with this file.

func (*File) Read

func (f *File) Read(b []byte) (nn int, err error)

Read will read bytes into given buffer from file descriptor.

func (*File) Seek

func (f *File) Seek(offset int64, whence int) (off int64, err error)

Seek will call seek() on file descriptor with given offset and return new offset.

func (*File) Stat

func (f *File) Stat() (stat Stat, err error)

Stat will call fstat() on file descriptor and return the results.

func (*File) Sync

func (f *File) Sync() error

Sync will call fsync() on file descriptor.

func (*File) Write

func (f *File) Write(b []byte) (nn int, err error)

Write will write given bytes to file descriptor, using as many write() calls as necessary.

func (*File) WriteString

func (f *File) WriteString(s string) (int, error)

WriteString calls .Write() after converting string to byte slice.

type Stat

type Stat unix.Stat_t

Stat is a type alias to unix.Stat_t.