pos

Documentation

Overview

Package parlos provides simplified functions for home-directory and hostname.

Index

• Constants
• func AppendToFile(filename string) (osFile *os.File, err error)
• func CloseRm(filename string, osFile *os.File, errp *error)
• func ExecDir() (dir string)
• func Exit(code int, err error)
• func Exit0()
• func Exit1(err error)
• func Exit1OneLine(err error)
• func HomeDir(relPaths string) (dir string)
• func Hostname() (host string, err error)
• func LogFile(filename string) (osFile *os.File, err error)
• func NewFile(filename string) (osFile *os.File, err error)
• func OsExit(code int)
• func ParentDir() (dir string)
• func RemoveFile(filename string) (err error)
• func ShortHostname() (host string)
• func UserHome() (homeDir string, err error)
• func UserHomeDir() (homeDir string)
• func WriteNewFile(filename string, data []byte) (err error)
• type AppDirectory
  • func NewAppDir(appName string) (appd *AppDirectory)
  • func (d *AppDirectory) Directory() (abs string)
  • func (d *AppDirectory) EnsureDir() (err error)
  • func (d *AppDirectory) Path() (abs string, isNotExist bool, err error)

Constants

const (
	// when created, output file permissions is user-read/write
	FilePermUrw os.FileMode = 0o600 // rw- --- ---

	FilePermUw os.FileMode = 0o200 // -w- --- ---
)

open flags: Linux man 2 open

const (
	StatusCodeErr   = 1
	StatusCodeUsage = 2
)

Functions

func AppendToFile

func AppendToFile(filename string) (osFile *os.File, err error)

AppendToFile is os.Open for a write-only file that is created or appended to

• use is an output file without data loss
• a created file has permissions urw
• if file is not on NFS, append is thread-safe
• other functions:
• — os.Open: opens an existing file for reading only
• — os.Create: opens or creates a file for reading and writing that is truncated if it exists
• — pos.NewFile: write-only file that must not exist
• — pos.LogFile: a created or appended to write-only file committing on every write

func CloseRm

func CloseRm(filename string, osFile *os.File, errp *error)

CloseRm closes osFile and deletes it if errp contains error

• deferrable

func ExecDir

func ExecDir() (dir string)

ExecDir gets abolute path to directory where executable is located

func Exit

func Exit(code int, err error)

Exit terminate the command echoing to stderr returning status code

func Exit0

func Exit0()

Exit0 terminates the process successfully

func Exit1

func Exit1(err error)

Exit1 terminate the command echoing a failure to stderr and returning status code 1

func Exit1OneLine

func Exit1OneLine(err error)

Exit1OneLine terminate the command echoing to stderr returning status code 1

func HomeDir

func HomeDir(relPaths string) (dir string)

HomeDir creates levels of directories in users’s home. if directories do not exist, they are created with permissions u=rwx. This should never fail, when it does, panic is thrown

func Hostname

func Hostname() (host string, err error)

hostname without domain part

func LogFile

func LogFile(filename string) (osFile *os.File, err error)

LogFile is os.Open for a write-only file that is created or appended to

• use is an output file without data loss
• a created file has permissions urw
• if file is not on NFS, append is thread-safe
• written data is committed on every write
• other functions:
• — os.Open: opens an existing file for reading only
• — os.Create: opens or creates a file for reading and writing that is truncated if it exists
• — pos.AppendToFile: write-only file that is created or appended to
• — pos.NewFile: write-only file that must not exist

func NewFile

func NewFile(filename string) (osFile *os.File, err error)

NewFile is os.Open for a write-only file that must not exist

• use is an output file without data loss
• a created file has permissions urw
• if file is not on NFS, append is thread-safe
• other functions:
• — os.Open: opens an existing file for reading only
• — os.Create: opens or creates a file for reading and writing that is truncated if it exists
• — pos.AppendToFile: write-only file that is created or appended to
• — pos.LogFile: a created or appended to write-only file committing on every write

func OsExit

func OsExit(code int)

OsExit does os.Exit

func ParentDir

func ParentDir() (dir string)

ParentDir gets absolute path of executable parent directory

func RemoveFile

func RemoveFile(filename string) (err error)

RemoveFile deletes a file after changing its permissions to ensure uw

func ShortHostname

func ShortHostname() (host string)

ShortHostname gets hostname without domain part This should never fail, when it does, panic is thrown

func UserHome

func UserHome() (homeDir string, err error)

UserHome obtains the absolute path to the process owning user’s home directory

• does not rely on environment

func UserHomeDir

func UserHomeDir() (homeDir string)

UserHomeDir obtains the absolute path to the process owning user’s home directory

• does not rely on environment
• should never fail. if it does, panic is thrown

func WriteNewFile

func WriteNewFile(filename string, data []byte) (err error)

WriteNewFile writes data to filename without overwriting anything

• similar to os.WriteFile but does not overwrite and removes on error
• filename: filename, default current directory
• if err is non-nil, the file was not created or was removed due to error
• file must not exist
• file is created with ur permissions

Types

type AppDirectory

type AppDirectory struct {
	// app name like “myapp”
	App string
	// contains filtered or unexported fields
}

AppDirectory manages a per-user writable app-specific directory

func NewAppDir

func NewAppDir(appName string) (appd *AppDirectory)

NewAppDir returns a writable directory object in the user’s home directory

• appName: application name like “myapp” Unicode letters and digits
• directory is “~/.local/share/[appName]”
• parent directory is based on the running process’ owner
• does not rely on environment variables

Usage:

var appDir = NewAppDir("myapp")
if err = appDir.EnsureDir(); err != nil {…
var knownToExistAbsCleanNoSymlinksNeverErrors = appDir.Directory()

func (*AppDirectory) Directory

func (d *AppDirectory) Directory() (abs string)

best-effort single-value absolute and clean path possibly symlink-free to directory

• returns an absolute path whether the directory exists or not
• if directory exists, absolute clean symlink-free, otherwise absolute clean
• Directory may panic from errors that are returned by AppDirectory.EnsureDir or AppDirectory.Path. To avoid panics, invoke those methods first.

Usage:

var dir = NewAppDir("myapp").Directory()

func (*AppDirectory) EnsureDir

func (d *AppDirectory) EnsureDir() (err error)

EnsureDir ensures the directory exists

func (*AppDirectory) Path

func (d *AppDirectory) Path() (abs string, isNotExist bool, err error)

Path returns best-effort absolute clean path

• if the app-directory exists, abs is also symlink-free
• outcomes:
• — err: nil: abs is absolute clean symlink-free, app directory exists
• — isNotExist: true, err: non-nil: app directory does not eixst. abs is absolute clean. err is errno ENOENT
• — err: non-nil, isNotExist: false: some error
• —
• macOS: “/Users/user/.local/share/myapp”
• Linux: “/home/user/.local/share/myapp”
• note: symlinks can only be evaled if a path exists