posixperm

README

posixperm

A POSIX file permission type designed for marshaling.

Documentation

Overview

This package provides a Perm type that is assignable to/from an fs.FileMode and survives marshaling into and out of text. It supports a variety of conventional POSIX file permission notations for unmarshaling:

`rwx` -- assign read/write/execute across all users (including owner and group members)
`rw-` / `r-x` -- as above, dropping execute or write
`644` -- implied octal form, specifying read/write for owner, read-only for group/other
`0644` -- as above, but explicit octal form
`0o644` -- as above, but explicit octal form satisfying YAML 1.2 etc
`a=r` -- symbolic form assigning read permission to all
`a=rwx o-w` -- symbolic form assigning r/w/x to all but removing write from other
`ug=rx u+w` -- symbolic form granting read/execute to owner/group, adding write to owner
`ug=rxu+w` -- symbolic form as above but without space separator

It's also possible to use long form permission styles:

`rwxr-xr-x` -- 'ls' style r/w/x for owner, and r/x for group/other
`-rwxr-xr-x` -- as above, but using the full 10+ byte syntax used by fs.FileMode
`ur-xr-x---` -- fs.FileMode syntax with owner/group read/execute plus setuid flag

Index

• type Perm
  • func FromFileMode(m fs.FileMode) (r Perm, err error)
  • func FromString(p string) (r Perm, err error)
  • func (p Perm) FileMode() fs.FileMode
  • func (p Perm) MarshalText() ([]byte, error)
  • func (p Perm) String() string
  • func (p *Perm) UnmarshalText(b []byte) error

Types

type Perm

type Perm fs.FileMode

Perm represents an unsigned 32-bit integer that is comparable and assignable to fs.FileMode. It is intended to be embedded in structs that will be marshaled or unmarshaled, especially if reading human-edited files, as it allows a human to specify file permissions in a more conventional format than either a base-10 decimal rendering of the otherwise traditionally base-8 octal permissions, or an alternative like slices of flags.

func FromFileMode

func FromFileMode(m fs.FileMode) (r Perm, err error)

FromFileMode returns a new Perm copied from m. It never returns an error.

func FromString

func FromString(p string) (r Perm, err error)

FromString parses the string p following the same rules as UnmarshalText, returning a new Perm. An error is returned if the string cannot be parsed as a Perm value.

func (Perm) FileMode

func (p Perm) FileMode() fs.FileMode

FileMode returns the fs.FileMode typed value of a Perm.

func (Perm) MarshalText

func (p Perm) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler for this type. It returns the String() representation of fs.FileMode, which encodes each of the meaningful bits of the uint32 as a single byte; a dynamic set of mode, type, and behavior bits, or a dash if none are set, followed by 9 permission bits. MarshalText may return a format different than the format parsed if this type was unmarshaled as it always uses the full representation that is unambiguous and supports extended mode bits.

func (Perm) String

func (p Perm) String() string

String returns the canonical fs.FileMode string representation of a Perm.

func (*Perm) UnmarshalText

func (p *Perm) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler for this type. It checks for several conventional formats for basic file permissions, and also understands the full format returned by fs.FileMode's String() method.