mode

README

Mode

Mode is a Go package that provides a native Go implementation of BSD's setmode and getmode which can be used to modify the mode bits of an os.FileMode value based on a sumbolic value as described by the Unix chmod command.

Online package documentation is available via https://godoc.org/bitbucket.org/dchapes/mode.

To install:

	go get bitbucket.org/dchapes/mode

or go build any Go code that imports it:

	import "bitbucket.org/dchapes/mode"

Documentation

Overview

Package mode provides a native Go implementation of BSD's setmode and getmode which can be used to modify the mode bits of an os.FileMode value based on a symbolic value as described by the Unix chmod command.

For a full description of the mode string see chmod(1). Some examples include:

644		make a file readable by anyone and writable by the owner
		only.

go-w		deny write permission to group and others.

=rw,+X		set the read and write permissions to the usual defaults,
		but retain any execute permissions that are currently set.

+X		make a directory or file searchable/executable by everyone
		if it is already searchable/executable by anyone.

755
u=rwx,go=rx
u=rwx,go=u-w	make a file readable/executable by everyone and writable by
		the owner only.

go=		clear all mode bits for group and others.

go=u-w		set the group bits equal to the user bits, but clear the
		group write bit.

See Also:

setmode(3): https://www.freebsd.org/cgi/man.cgi?query=setmode&sektion=3
chmod(1):   https://www.freebsd.org/cgi/man.cgi?query=chmod&sektion=1

Index

• Variables
• func Apply(s string, perm os.FileMode, umask int) (os.FileMode, error)
• type Set
  • func Parse(s string) (Set, error)
  • func ParseWithUmask(s string, umask int) (Set, error)
  • func (s Set) Apply(perm os.FileMode) os.FileMode
  • func (s *Set) Chmod(name string) (old, new os.FileMode, err error)
  • func (s *Set) ChmodFile(f *os.File) (old, new os.FileMode, err error)
  • func (s Set) String() string

Variables

var ErrSyntax = errors.New("invalid syntax")

ErrSyntax indicates an argument does not represent a valid mode.

Functions

func Apply

func Apply(s string, perm os.FileMode, umask int) (os.FileMode, error)

Apply changes the provided os.FileMode based on the given umask and absolute or symbolic mode value.

Apply is a convience to calling ParseWithUmask followed by Apply. Since it needs to parse the mode value string on each call it should only be used when mode value string will not be reapplied.

Types

type Set

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

Set is a set of changes to apply to an os.FileMode. Changes include setting or clearing specific bits, copying bits from one user class to another (e.g. "u=go" sets the user permissions to a copy of the group and other permsissions), etc.

func Parse

func Parse(s string) (Set, error)

Parse takes an absolute (octal) or symbolic mode value, as described in chmod(1), as an argument and returns the set of bit operations representing the mode value that can be applied to specific os.FileMode values.

Because some of the symbolic values are relative to the file creation mask, Parse may call syscall.Umask. If this occurs, the file creation mask will be restored before Parse returns. If the calling program changes the value of its file creation mask after calling Parse, Parse must be called again if the the Set is to modify future file modes correctly.

The call to syscall.Umask can be avoided by using ParseWithUmask and providing the current process file creation mask.

func ParseWithUmask

func ParseWithUmask(s string, umask int) (Set, error)

ParseWithUmask is like Parse but uses the provided file creation mask instead of calling syscall.Umask.

func (Set) Apply

func (s Set) Apply(perm os.FileMode) os.FileMode

Apply returns the os.FileMode after applying the set of changes.

func (*Set) Chmod

func (s *Set) Chmod(name string) (old, new os.FileMode, err error)

Chmod is a convience routine that applies the changes in Set to the named file. To avoid some race conditions, it opens the file and uses os.File.Stat and os.File.Chmod rather than os.Stat and os.Chmod if possible.

func (*Set) ChmodFile

func (s *Set) ChmodFile(f *os.File) (old, new os.FileMode, err error)

ChmodFile is a convience routine that applies the changes in Set to the open file f.

func (Set) String

func (s Set) String() string

The String method will likely only be useful when testing.