compat

README

compat

• Overview
• Usage
• Stat
• Installing
• FileInfo Functions
• Other Functions
• Contributing
• License

Overview

compat is a pure-Go library providing unified access to file and device metadata, atomic file operations, process priority, etc. on all major operating systems, include Android, iOS, Linux, macOS, Windows, and many others.

Usage

The documentation is available at https://pkg.go.dev/github.com/rasa/compat

Stat

Here's an example of calling compat.Stat():

package main

import (
	"os"

	"github.com/rasa/compat"
)

const mode = os.FileMode(0o654)

func main() {
	_ := compat.WriteFile("hello.txt", []byte("Hello World"), mode)

  fi, _ := compat.Stat("hello.txt")

  print(fi.String())
}

which, on Linux, produces:

Name:   hello.txt
Size:   11
Mode:   0o654 (-rw-r-xr--)
ModTime:2025-08-14 09:25:27.190602462 -0700 PDT // last Modified
ATime:  2025-08-14 09:25:27.190602462 -0700 PDT // last Accessed
BTime:  2025-08-14 09:25:27.190602462 -0700 PDT // Birthed/created
CTime:  2025-08-14 09:25:27.190602462 -0700 PDT // metadata last Changed
IsDir:  false
Links:  1                                       // number of hard links
UID:    1000 (ross)                             // user ID
GID:    1000 (ross)                             // group ID
PartID: 64512                                   // unique partition (device) ID
FileID: 18756713                                // unique file ID on the partition

and on Windows, produces:

Name:   hello.txt
Size:   11
Mode:   0o654 (-rw-r-xr--)
ModTime:2025-08-14 09:28:50.4214934 -0700 PDT
ATime:  2025-08-14 09:28:50.4214934 -0700 PDT
BTime:  2025-08-14 09:28:50.4209614 -0700 PDT
CTime:  2025-08-14 09:28:50.4214934 -0700 PDT
IsDir:  false
Links:  1
UID:    197609 (domain\ross)
GID:    197121 (domain\None)
PartID: 8
FileID: 844424931319952

icacls shows:

icacls hello.txt

hello.txt domain\ross:(R,W,D)
          domain\None:(RX)
          Everyone:(R)

powershell shows:

powershell -command "Get-Acl hello.txt | Format-List"

Path   : Microsoft.PowerShell.Core\FileSystem::C:\path\to\hello.txt
Owner  : domain\ross
Group  : domain\None
Access : Everyone Allow  Read, Synchronize
         domain\None Allow  ReadAndExecute, Synchronize
         domain\ross Allow  Write, Delete, Read, Synchronize
Audit  :
Sddl   : O:S-1-5-21-2970224322-3395479738-1485484954-1001G:S-1-5-21-2970224322-3395479738-1485484954-513D:P(A;;FR;;;WD)(A;;0x1200a9;;;S-1-5-21-2970224322-3395479738-1485484954-5
         19f;;;S-1-5-21-2970224322-3395479738-1485484954-1001)

Cygwin's stat shows:

$ stat hello.txt
  File: hello.txt
  Size: 11              Blocks: 1          IO Block: 65536  regular file
Device: 0,8     Inode: 844424931319952  Links: 1
Access: (0754/-rwxr-xr--)  Uid: (197609/    ross)   Gid: (197121/    None)
Access: 2025-08-14 09:28:50.421493400 -0700
Modify: 2025-08-14 09:28:50.421493400 -0700
Change: 2025-08-14 09:28:50.421493400 -0700
 Birth: 2025-08-14 09:28:50.420961400 -0700

Git for Windows's stat shows:

$ stat hello.txt
  File: hello.txt
  Size: 11              Blocks: 1          IO Block: 65536  regular file
Device: 8h/8d   Inode: 844424931319952  Links: 1
Access: (0644/-rw-r--r--)  Uid: (197609/    ross)   Gid: (197121/ UNKNOWN)
Access: 2025-08-14 09:30:06.729683700 -0700
Modify: 2025-08-14 09:28:50.421493400 -0700
Change: 2025-08-14 09:28:50.421493400 -0700
 Birth: 2025-08-14 09:28:50.420961400 -0700

Installing

To install compat, use go get:

go get github.com/rasa/compat

FileInfo Functions

The Stat() and Lstat() functions return a FileInfo object. The table below lists the operating system support for each of the FileInfo functions:

OS	PartitionID()/ FileID()*	Links()*	ATime()* (last Accessed)	BTime()* (Birthed/ created)	CTime()* (metadata last Changed)	UID()/GID()
AIX	✅	✅	✅	❌	✅	✅
Android	✅	✅	✅	✅	✅	✅
Dragonfly	✅	✅	✅	✖️	✅	✅
FreeBSD	✅	✅	✅	✅	✅	✅
Illumos	✅	✅	✅	✖️	✅	✅
iOS	✅	✅	✅	✅	✅	✅
Js/ WASM	✅	✅	✅	❌	✅	✅
Linux	✅	✅	✅	✅	✅	✅
macOS	✅	✅	✅	✅	✅	✅
NetBSD	✅	✅	✅	✅	✅	✅
OpenBSD	✅	✅	✅	✖️	✅	✅
Plan9	✅	❌	✅	❌	❌	☑️
Solaris	✅	✅	✅	✖️	✅	✅
Wasip1/ WASM	✅	✅	✅†	❌	✅	✅
Windows	✅	✅	✅	✅	✅	✅‡

* Support will depend on the underlying file system. See Comparison of file systems for details.
† Not supported if compiled using the Tinygo compiler.
‡ Provides the same integer values as Cygwin/MSYS2/Git for Windows in mapping Windows SIDs (Security Identifiers).

✅ fully supported.
☑️ the UID() and GID() values are 32-bit hashes of the user and group names.
✖️ not implemented (but if the OS supports it, so we could add support).
❌ not implemented (as it appears the OS doesn't support it).

Other Functions

All other functions provided by this library are fully supported by all the above operating systems.

Contributing

Please feel free to submit issues, fork the repository and send pull requests!

License

This project is MIT licensed.

Documentation

Overview

package compat is a pure-Go library providing unified access to file and device metadata, atomic file operations, process priority, etc. on all major operating systems, include Windows, Linux, macOS, Android, iOS, and many others.

Index

• Constants
• Variables
• func BuildBits() int
• func CPUBits() (int, error)
• func Chmod(name string, mode os.FileMode, opts ...Option) error
• func Create(name string, opts ...Option) (*os.File, error)
• func CreateTemp(dir, pattern string, opts ...Option) (*os.File, error)
• func FormatDirEntry(dir DirEntry) string
• func GetUmask() int
• func Getegid() (int, error)
• func Geteuid() (int, error)
• func Getgid() (int, error)
• func Getuid() (int, error)
• func IsRoot() (bool, error)
• func IsWSL() bool
• func Mkdir(name string, perm os.FileMode) error
• func MkdirAll(path string, perm os.FileMode) error
• func MkdirTemp(dir, pattern string, opts ...Option) (string, error)
• func Nice() (int, error)
• func OpenFile(name string, flag int, perm os.FileMode, opts ...Option) (*os.File, error)
• func PartitionType(ctx context.Context, path string) (string, error)
• func Remove(name string) error
• func RemoveAll(path string) error
• func Rename(source, destination string) error
• func Renice(nice int) error
• func SameFile(fi1, fi2 FileInfo) bool
• func SameFiles(name1, name2 string) bool
• func SamePartition(fi1, fi2 FileInfo) bool
• func SamePartitions(name1, name2 string) bool
• func SupportsATime() bool
• func SupportsBTime() bool
• func SupportsCTime() bool
• func SupportsLinks() bool
• func SupportsSymlinks() bool
• func Symlink(oldname, newname string, opts ...Option) error
• func Umask(newMask int) int
• func UnderlyingGoVersion() string
• func WalkDir(fsys FS, root string, fn WalkDirFunc) error
• func WriteFile(name string, data []byte, perm os.FileMode, opts ...Option) error
• func WriteFileAtomic(filename string, data []byte, opts ...Option) (err error)
• func WriteReaderAtomic(filename string, r io.Reader, opts ...Option) (err error)
• type DirEntry
  • func FileInfoToDirEntry(info FileInfo, parent string) DirEntry
  • func ReadDir(name string) ([]DirEntry, error)
• type FS
• type FileInfo
  • func Lstat(name string) (FileInfo, error)
  • func Stat(name string) (FileInfo, error)
• type FileMode
• type FileOptions
• type InvalidNiceError
  • func (e *InvalidNiceError) Error() string
• type NiceError
  • func (e *NiceError) Error() string
• type Option
  • func WithDefaultFileMode(mode os.FileMode) Option
  • func WithFileMode(mode os.FileMode) Option
  • func WithFlags(flags int) Option
  • func WithKeepFileMode(keep bool) Option
  • func WithReadOnlyMode(mode ReadOnlyMode) Option
  • func WithSetSymlinkOwner(setSymlinkOwner bool) Option
• type Options
• type ReadOnlyMode
• type ReniceError
  • func (e *ReniceError) Error() string
• type SupportedType
• type UserIDSourceType
  • func UserIDSource() UserIDSourceType
• type WalkDirFunc

Constants

const (
	// Deprecated: Use SupportsLinks() instead. This may be removed in the future.
	Links = supportsLinks
	// Deprecated: Use SupportsATime() instead. This may be removed in the future.
	ATime = supportsATime
	// Deprecated: Use SupportsBTime() instead. This may be removed in the future.
	BTime = supportsBTime
	// Deprecated: Use SupportsCTime() instead. This may be removed in the future.
	CTime = supportsCTime
	// Deprecated: No longer used or needed. This may be removed in the future.
	UID = supportsUID
	// Deprecated: No longer used or needed. This may be removed in the future.
	GID = supportsGID
)

const (
	// CreatePerm is the FileMode used by os.Create() (and compat.Create()).
	CreatePerm os.FileMode = 0o666
	// CreateTempPerm is the FileMode used by os.CreateTemp() (and
	// compat.CreateTemp()).
	CreateTempPerm os.FileMode = 0o600
	// MkdirTempPerm is the FileMode used by os.MkdirTemp() (and
	// compat.MkdirTemp()).
	MkdirTempPerm os.FileMode = 0o700

	// DefaultAppleDirPerm is the FileMode returned for directories by
	// golang's os.Stat() function on Apple based systems
	// when the directory is on a filesystem that doesn't support
	// macOS/iOS permissions, such as exFAT, or FAT32.
	DefaultAppleDirPerm os.FileMode = 0o700
	// DefaultAppleFilePerm is the FileMode returned for files by
	// golang's os.Stat() function on Apple based systems
	// when the file is on a filesystem that doesn't support
	// macOS/iOS permissions, such as exFAT, or FAT32.
	DefaultAppleFilePerm os.FileMode = 0o700

	// DefaultUnixDirPerm is the FileMode returned for directories by
	// golang's os.Stat() function on non-Apple/non-Windows based systems
	// when the directory is on a filesystem that doesn't support
	// Unix permissions, such as exFAT, or FAT32.
	DefaultUnixDirPerm os.FileMode = 0o777
	// DefaultUnixFilePerm is the FileMode returned for files by
	// golang's os.Stat() function on non-Apple/non-Windows based systems
	// when the file is on a filesystem that doesn't support
	// Unix permissions, such as exFAT, or FAT32.
	DefaultUnixFilePerm os.FileMode = 0o777

	// DefaultWindowsDirPerm is the FileMode returned for directories by
	// golang's os.Stat() function on Windows based systems
	// when the directory is on a filesystem that doesn't support Windows'
	// Access Control Lists (ACLS), such as exFAT, or FAT32.
	DefaultWindowsDirPerm os.FileMode = 0o777
	// DefaultWindowsFilePerm is the FileMode returned for files by
	// golang's os.Stat() function on Windows based systems
	// when the file is on a filesystem that doesn't support Windows'
	// Access Control Lists (ACLS), such as exFAT, or FAT32.
	DefaultWindowsFilePerm os.FileMode = 0o666

	// O_DELETE deletes the file when closed.
	O_DELETE = 0x8000000
	// O_NOROATTR doesn't set a file's read-only attribute on Windows.
	O_NOROATTR = 0x4000000

	O_RDONLY = os.O_RDONLY // open the file read-only. //nolint:revive
	O_WRONLY = os.O_WRONLY // open the file write-only. //nolint:revive
	O_RDWR   = os.O_RDWR   // open the file read-write. //nolint:revive
	// The remaining values may be or'ed in to control behavior.
	O_APPEND = os.O_APPEND // append data to the file when writing.
	O_CREATE = os.O_CREATE // create a new file if none exists.
	O_EXCL   = os.O_EXCL   // used with O_CREATE, file must not exist.
	O_SYNC   = os.O_SYNC   // open for synchronous I/O.
	O_TRUNC  = os.O_TRUNC  // truncate regular writable file when opened.

	ModeDir        = fs.ModeDir        // d: is a directory
	ModeAppend     = fs.ModeAppend     // a: append-only
	ModeExclusive  = fs.ModeExclusive  // l: exclusive use
	ModeTemporary  = fs.ModeTemporary  // T: temporary file; Plan 9 only
	ModeSymlink    = fs.ModeSymlink    // L: symbolic link
	ModeDevice     = fs.ModeDevice     // D: device file
	ModeNamedPipe  = fs.ModeNamedPipe  // p: named pipe (FIFO)
	ModeSocket     = fs.ModeSocket     // S: Unix domain socket
	ModeSetuid     = fs.ModeSetuid     // u: setuid
	ModeSetgid     = fs.ModeSetgid     // g: setgid
	ModeCharDevice = fs.ModeCharDevice // c: Unix character device, when ModeDevice is set
	ModeSticky     = fs.ModeSticky     // t: sticky
	ModeIrregular  = fs.ModeIrregular  // ?: non-regular file; nothing else is known about this file

	// ModeType is a mask for the type bits. For regular files, none will be set.
	ModeType = fs.ModeType

	// ModePerm is a mask for the Unix permission bits, 0o777.
	ModePerm = fs.ModePerm
)

const (
	// MaxNice is the maximum value returned by Nice().
	MaxNice = 19
	// MinNice is the minimum value returned by Nice().
	MinNice = -20
)

const (
	IsAIX       = runtime.GOOS == "aix"
	IsAndroid   = runtime.GOOS == "android"
	IsDarwin    = runtime.GOOS == "darwin"
	IsDragonfly = runtime.GOOS == "dragonfly"
	IsFreeBSD   = runtime.GOOS == "freebsd"
	IsIllumos   = runtime.GOOS == "illumos"
	IsIOS       = runtime.GOOS == "ios"
	IsJS        = runtime.GOOS == "js"
	IsLinux     = runtime.GOOS == "linux"
	IsNetBSD    = runtime.GOOS == "netbsd"
	IsOpenBSD   = runtime.GOOS == "openbsd"
	IsPlan9     = runtime.GOOS == "plan9"
	IsSolaris   = runtime.GOOS == "solaris"
	IsWasip1    = runtime.GOOS == "wasip1"
	IsWindows   = runtime.GOOS == "windows"
)

const (
	IsApple   = IsDarwin || IsIOS
	IsBSD     = IsDragonfly || IsFreeBSD || IsNetBSD || IsOpenBSD
	IsBSDLike = IsApple || IsBSD
	IsSolaria = IsIllumos || IsSolaris
)

const (
	Is386      = runtime.GOARCH == "386"
	IsAmd64    = runtime.GOARCH == "amd64"
	IsArm      = runtime.GOARCH == "arm"
	IsArm64    = runtime.GOARCH == "arm64"
	IsLoong64  = runtime.GOARCH == "loong64"
	IsMips     = runtime.GOARCH == "mips"
	IsMips64   = runtime.GOARCH == "mips64"
	IsMips64le = runtime.GOARCH == "mips64le"
	IsMipsle   = runtime.GOARCH == "mipsle"
	IsPpc64    = runtime.GOARCH == "ppc64"
	IsPpc64le  = runtime.GOARCH == "ppc64le"
	IsRiscv64  = runtime.GOARCH == "riscv64"
	IsS390x    = runtime.GOARCH == "s390x"
	IsWasm     = runtime.GOARCH == "wasm"
)

const (
	IsX86CPU  = Is386 || IsAmd64
	IsArmCPU  = IsArm || IsArm64
	IsMipsCPU = IsMips || IsMips64 || IsMips64le || IsMipsle
	IsPpcCPU  = IsPpc64 || IsPpc64le
)

const IsTinygo = runtime.Compiler == "tinygo"

IsTinygo is true if the go compiler is tinygo.

const IsUnix = true

IsUnix is true if the unix build tag has been set. Currently, it's equivalent to: IsAIX || IsAndroid || IsApple || IsBSD || IsLinux || IsSolaria.

const UnknownID = int(-1)

UnknownID is returned when the UID or GID could not be determined.

const UserIDSourceIsNumeric = UserIDSourceIsInt

Deprecated: Use UserIDSourceIsInt instead. This may be removed in the future.

Variables

var CreateEx = createex

Deprecated: Use Create() instead, and pass perm and flag via Option array. This function may be removed in the future.

var CreateTempEx = createTempEx

Deprecated: Use CreateTemp() instead, and pass flag via Option array. This function may be removed in the future.

var DefaultFileMode = WithDefaultFileMode

Deprecated: Use WithDefaultFileMode() instead. This function may be removed in the future.

var Flag = WithFlags

Deprecated: Use WithFlags() instead. This function may be removed in the future.

var IsAct = os.Getenv("ACT") == "true"

IsAct is true when running github actions locally using the act command.

var IsAdmin = IsRoot

Deprecated: Use IsRoot() instead. This function may be removed in the future.

var KeepFileMode = WithKeepFileMode

Deprecated: Use WithKeepFileMode() instead. This function may be removed in the future.

var ReplaceFile = Rename

Deprecated: Use Rename() instead. This function may be removed in the future.

var SkipAll = fs.SkipAll

SkipAll is used as a return value from WalkDirFunc to indicate that all remaining files and directories are to be skipped. It is not returned as an error by any function.

var SkipDir = fs.SkipDir

SkipDir is used as a return value from WalkDirFunc to indicate that the directory named in the call is to be skipped. It is not returned as an error by any function.

var Supported = supported

Deprecated: Use SupportsLinks(), SupportsATime(), SupportsBTime() and SupportsCTime() functions instead. This function may be removed in the future.

var UseFileMode = WithFileMode

Deprecated: Use WithFileMode() instead. This function may be removed in the future.

var WriteFileEx = writeFileEx

Deprecated: Use WriteFile() instead, and pass flag via Option array. This function may be removed in the future.

Functions

func BuildBits

func BuildBits() int

BuildBits returns the number of CPU bits for the build target. For 386, arm, mips, and mipsle, it's 32. For all other targets, it's 64.

func CPUBits

func CPUBits() (int, error)

CPUBits returns the number of bits on the CPU. Currently, on plan9, and wasm, BuildBits() is returned.

func Chmod

func Chmod(name string, mode os.FileMode, opts ...Option) error

Chmod changes the mode of the named file to mode. If the file is a symbolic link, it changes the mode of the link's target. If there is an error, it will be of type [*PathError].

A different subset of the mode bits are used, depending on the operating system.

On Unix, the mode's permission bits, ModeSetuid, ModeSetgid, and ModeSticky are used.

On Windows, the mode's permission bits are used to set the appropriate ACL entries.

In addition, the 0o200 bit (owner writable) is used to control whether the file's read-only attribute is set or cleared. For compatibility with Go 1.12 and earlier, use a non-zero mode.

On Plan 9, the mode's permission bits, ModeAppend, ModeExclusive, and ModeTemporary are used.

func Create

func Create(name string, opts ...Option) (*os.File, error)

Create creates or truncates the named file. If the file already exists, it is truncated. If the file does not exist, it is created with mode 0o666 (before umask). If successful, methods on the returned File can be used for I/O; the associated file descriptor has mode O_RDWR. The directory containing the file must already exist. If there is an error, it will be of type [*PathError].

func CreateTemp

func CreateTemp(dir, pattern string, opts ...Option) (*os.File, error)

CreateTemp creates a new temporary file in the directory dir, opens the file for reading and writing, and returns the resulting file. The filename is generated by taking pattern and adding a random string to the end. If pattern includes a "*", the random string replaces the last "*". The file is created with mode 0o600 (before umask). If dir is the empty string, CreateTemp uses the default directory for temporary files, as returned by [TempDir]. Multiple programs or goroutines calling CreateTemp simultaneously will not choose the same file. The caller can use the file's Name method to find the pathname of the file. It is the caller's responsibility to remove the file when it is no longer needed.

func FormatDirEntry

func FormatDirEntry(dir DirEntry) string

FormatDirEntry returns a formatted version of dir for human readability. Implementations of DirEntry can call this from a String method. The outputs for a directory named subdir and a file named hello.go are:

d subdir/
- hello.go

func GetUmask

func GetUmask() int

GetUmask returns the current umask value. On Plan9 and Wasip1, the function always returns zero.

func Getegid

func Getegid() (int, error)

Getegid returns the effective default Group ID for the current user. On Windows, the user's primary group's SID is converted to its POSIX equivalent, which is compatible with Cygwin, Git for Windows, MSYS2, etc. On Plan9, Getegid returns a 32-bit hash of the user's group's name, as provided by golang's os/user package.

func Geteuid

func Geteuid() (int, error)

Geteuid returns the effective User ID for the current user. On Windows, the user's SID is converted to its POSIX equivalent, which is compatible with Cygwin, Git for Windows, MSYS2, etc. On Plan9, Geteuid returns a 32-bit hash of the user's name.

func Getgid

func Getgid() (int, error)

Getgid returns the default Group ID for the current user. On Windows, the user's primary group's SID is converted to its POSIX equivalent, which is compatible with Cygwin, Git for Windows, MSYS2, etc. On Plan9, Getgid returns a 32-bit hash of the user's group's name, as provided by golang's os/user package.

func Getuid

func Getuid() (int, error)

Getuid returns the User ID for the current user. On Windows, the user's SID is converted to its POSIX equivalent, which is compatible with Cygwin, Git for Windows, MSYS2, etc. On Plan9, Getuid returns a 32-bit hash of the user's name.

func IsRoot

func IsRoot() (bool, error)

IsRoot returns true if the user is (effectively) root on a non-Windows system, or is running with elevated privileges (administrator rights) on a Windows system.

func IsWSL

func IsWSL() bool

IsWSL returns true if run instead a Windows Subsystem for Linux (WSL) environment, otherwise false.

It's counter-intuitive that IsWSL() returns false in Windows, but here's why: WSL can run executables built to run on Linux, and those built to run on Windows. For example, executing `whoami` will run WSL's `/usr/bin/whoami`, but append a `.exe`, and execute `whoami.exe`, then WSL will instead run Windows' whoami, in `C:/Windows/System32/whoami.exe`. But it doesn't appear to me that executables built to run on Windows can't tell they were started from inside a WSL environment. For example, the program doesn't see the `WSL_DISTRO_NAME“ environment variable that other programs run inside WSL see. Hence, this function must return false.

func Mkdir

func Mkdir(name string, perm os.FileMode) error

Mkdir creates a new directory with the specified name and perm's permission bits (before umask). If there is an error, it will be of type [*PathError].

func MkdirAll

func MkdirAll(path string, perm os.FileMode) error

MkdirAll creates a directory named path, along with any necessary parents, and returns nil, or else returns an error. The perm's permission bits (before umask) are used for all directories that MkdirAll creates. If path is already a directory, MkdirAll does nothing and returns nil.

func MkdirTemp

func MkdirTemp(dir, pattern string, opts ...Option) (string, error)

MkdirTemp creates a new temporary directory in the directory dir and returns the pathname of the new directory. The new directory's name is generated by adding a random string to the end of pattern. If pattern includes a "*", the random string replaces the last "*" instead. The directory is created with mode 0o700 (before umask). If dir is the empty string, MkdirTemp uses the default directory for temporary files, as returned by TempDir. Multiple programs or goroutines calling MkdirTemp simultaneously will not choose the same directory. It is the caller's responsibility to remove the directory when it is no longer needed.

func Nice

func Nice() (int, error)

Nice gets the CPU process priority. The return value is in a range from -20 (least nice), to 19 (most nice), even on non-Unix systems such as Windows, plan9, etc. If not supported by the operating system, -1 is returned.

func OpenFile

func OpenFile(name string, flag int, perm os.FileMode, opts ...Option) (*os.File, error)

OpenFile is the generalized open call; most users will use Open or Create instead. It opens the named file with specified flag (O_RDONLY etc.). If the file does not exist, and the O_CREATE flag is passed, it is created with perm's permission bits (before umask); the containing directory must exist. If successful, methods on the returned File can be used for I/O. If there is an error, it will be of type [*PathError].

func PartitionType

func PartitionType(ctx context.Context, path string) (string, error)

PartitionType returns the filesystem type (e.g., "ext4", "NTFS", "FAT32", etc.) for the disk partition that contains path.

func Remove

func Remove(name string) error

Remove removes the named file or directory. If there is an error, it will be of type [*PathError].

func RemoveAll

func RemoveAll(path string) error

RemoveAll removes path and any children it contains. It removes everything it can but returns the first error it encounters. If the path does not exist, RemoveAll returns nil (no error). If there is an error, it will be of type [*PathError].

func Rename

func Rename(source, destination string) error

Rename atomically replaces the destination file or directory with the source. It is guaranteed to either replace the target file entirely, or not change either file.

func Renice

func Renice(nice int) error

Renice sets the CPU process priority. The nice parameter can range from -20 (least nice), to 19 (most nice), even on non-Unix systems such as Windows, plan9, etc.

func SameFile

func SameFile(fi1, fi2 FileInfo) bool

SameFile reports whether fi1 and fi2 describe the same file. For example, on Unix this means that the partition (device) and inode fields of the two underlying structures are identical; on other systems the decision may be based on the path names. SamePartition only applies to results returned by this package's Stat. It returns false in other cases.

func SameFiles

func SameFiles(name1, name2 string) bool

SameFiles reports whether name1 and name2 are the same file. The function follow symlinks.

func SamePartition

func SamePartition(fi1, fi2 FileInfo) bool

SamePartition reports whether fi1 and fi2 describe files on the same disk partition. For example, on Unix this means that the partition (device) fields of the two underlying structures are identical; on other systems the decision may be based on the path names. SamePartition only applies to results returned by this package's Stat. It returns false in other cases.

func SamePartitions

func SamePartitions(name1, name2 string) bool

SamePartitions reports whether name1 and name2 are files on the same disk partition. The function follow symlinks.

func SupportsATime

func SupportsATime() bool

SupportsATime returns true if FileInfo's ATime() function is supported by the OS.

func SupportsBTime

func SupportsBTime() bool

SupportsBTime returns true if FileInfo's BTime() function is supported by the OS.

func SupportsCTime

func SupportsCTime() bool

SupportsCTime returns true if FileInfo's CTime() function is supported by the OS.

func SupportsLinks

func SupportsLinks() bool

SupportsLinks returns true if FileInfo's Links() function is supported by the OS.

func SupportsSymlinks

func SupportsSymlinks() bool

SupportsSymlinks returns true if the os.Symlinks() function is supported by the OS.

func Symlink

func Symlink(oldname, newname string, opts ...Option) error

Symlink creates newname as a symbolic link to oldname. On Windows, a symlink to a non-existent oldname creates a file symlink; if oldname is later created as a directory the symlink will not work. If there is an error, it will be of type *LinkError.

func Umask

func Umask(newMask int) int

Umask sets the umask to umask, and returns the previous value. On Windows, the initial umask value is 022 octal, and can be changed by setting environmental variable UMASK, to an octal value. For example: `set UMASK=002`. Leading zeros and 'o's are allowed, and ignored. On Plan9 and Wasip1, the function does nothing, and always returns zero.

func UnderlyingGoVersion

func UnderlyingGoVersion() string

UnderlyingGoVersion returns the effective Go toolchain version string ("goX.Y") for the current environment. - On standard Go: returns runtime.Version() (already "go1.xx"). - On TinyGo: picks the highest Go version supported based on thresholds.

func WalkDir

func WalkDir(fsys FS, root string, fn WalkDirFunc) error

WalkDir walks the file tree rooted at root, calling fn for each file or directory in the tree, including root.

All errors that arise visiting files and directories are filtered by fn: see the fs.WalkDirFunc documentation for details.

The files are walked in lexical order, which makes the output deterministic but requires WalkDir to read an entire directory into memory before proceeding to walk that directory.

WalkDir does not follow symbolic links found in directories, but if root itself is a symbolic link, its target will be walked.

func WriteFile

func WriteFile(name string, data []byte, perm os.FileMode, opts ...Option) error

WriteFile writes data to the named file, creating it if necessary. If the file does not exist, WriteFile creates it using perm's permissions bits (before umask); otherwise WriteFile truncates it before writing, without changing permissions. Since WriteFile requires multiple system calls to complete, a failure mid-operation can leave the file in a partially written state. Use WriteFileAtomic() if this is a concern.

func WriteFileAtomic

func WriteFileAtomic(filename string, data []byte, opts ...Option) (err error)

WriteFileAtomic atomically writes the contents of data to the specified filename. The target file is guaranteed to be either fully written, or not written at all. WriteFileAtomic overwrites any file that exists at the location (but only if the write fully succeeds, otherwise the existing file is unmodified). Additional option arguments can be used to change the default configuration for the target file.

func WriteReaderAtomic

func WriteReaderAtomic(filename string, r io.Reader, opts ...Option) (err error)

WriteReaderAtomic atomically writes the contents of r to the specified filename. The target file is guaranteed to be either fully written, or not written at all. WriteReaderAtomic overwrites any file that exists at the location (but only if the write fully succeeds, otherwise the existing file is unmodified). Additional option arguments can be used to change the default configuration for the target file.

Types

type DirEntry

type DirEntry interface {
	// Name returns the name of the file (or subdirectory) described by the entry.
	// This name is only the final element of the path (the base name), not the entire path.
	// For example, Name would return "hello.go" not "home/gopher/hello.go".
	Name() string

	// IsDir reports whether the entry describes a directory.
	IsDir() bool

	// Type returns the type bits for the entry.
	// The type bits are a subset of the usual FileMode bits, those returned by the FileMode.Type method.
	Type() os.FileMode

	// Info returns the FileInfo for the file or subdirectory described by the entry.
	// The returned FileInfo may be from the time of the original directory read
	// or from the time of the call to Info. If the file has been removed or renamed
	// since the directory read, Info may return an error satisfying errors.Is(err, ErrNotExist).
	// If the entry denotes a symbolic link, Info reports the information about the link itself,
	// not the link's target.
	Info() (FileInfo, error)
}

A DirEntry is an entry read from a directory (using the ReadDir function or a [ReadDirFile]'s ReadDir method).

func FileInfoToDirEntry

func FileInfoToDirEntry(info FileInfo, parent string) DirEntry

FileInfoToDirEntry returns a DirEntry that returns information from info. If info is nil, FileInfoToDirEntry returns nil.

func ReadDir

func ReadDir(name string) ([]DirEntry, error)

ReadDir reads the named directory, returning all its directory entries sorted by filename. If an error occurs reading the directory, ReadDir returns the entries it was able to read before the error, along with the error.

type FS

type FS = fs.FS

type FileInfo

type FileInfo interface {
	Name() string       // base name of the file
	Size() int64        // length in bytes for regular files; system-dependent for others
	Mode() os.FileMode  // file mode bits
	ModTime() time.Time // last modified time
	IsDir() bool        // abbreviation for Mode().IsDir()
	Sys() any           // underlying data source
	// Added by compat library:
	ATime() time.Time    // last accessed time, or 0 if unsupported
	BTime() time.Time    // created (birthed) time, or 0 if unsupported
	CTime() time.Time    // status/metadata changed time, or 0 if unsupported
	MTime() time.Time    // last modified time (alias)
	Links() uint         // number of hard links, or 0 if unsupported
	UID() int            // user ID, or -1 if an error or unsupported
	GID() int            // group ID, or -1 if an error or unsupported
	User() string        // user name, or "" if an error or unsupported
	Group() string       // group name, or "" if an error or unsupported
	PartitionID() uint64 // unique disk partition ID
	FileID() uint64      // unique file ID (on a specific partition)
	Error() error        // error result of the last system call that failed
	String() string
	Info() (os.FileInfo, error)
}

A FileInfo describes a file and is returned by Stat. See https://github.com/golang/go/blob/ad7a6f81/src/io/fs/fs.go#L158

func Lstat

func Lstat(name string) (FileInfo, error)

Lstat returns a FileInfo describing the named file. If the file is a symbolic link, the returned FileInfo describes the symbolic link. Lstat makes no attempt to follow the link. If there is an error, it will be of type [*PathError].

On Windows, if the file is a reparse point that is a surrogate for another named entity (such as a symbolic link or mounted folder), the returned FileInfo describes the reparse point, and makes no attempt to resolve it.

func Stat

func Stat(name string) (FileInfo, error)

Stat returns a FileInfo describing the named file. If there is an error, it will be of type [*PathError].

type FileMode

type FileMode = os.FileMode

type FileOptions

type FileOptions = Options

Deprecated: Use Options instead. This may be removed in the future.

type InvalidNiceError

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

InvalidNiceError is returned when the niceness value passed by the user is invalid.

func (*InvalidNiceError) Error

func (e *InvalidNiceError) Error() string

type NiceError

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

NiceError is returned when the system call failed.

func (*NiceError) Error

func (e *NiceError) Error() string

type Option

type Option func(*Options)

Option functions modify Options.

func WithDefaultFileMode

func WithDefaultFileMode(mode os.FileMode) Option

WithDefaultFileMode sets the default file mode instead of using the `os.CreateTemp()` default of `0600`.

func WithFileMode

func WithFileMode(mode os.FileMode) Option

WithFileMode sets the file mode to the desired value and has precedence over all other options.

func WithFlags

func WithFlags(flags int) Option

WithFlags sets the flag option.

func WithKeepFileMode

func WithKeepFileMode(keep bool) Option

WithKeepFileMode preserves the file mode of an existing file instead of using the default value.

func WithReadOnlyMode

func WithReadOnlyMode(mode ReadOnlyMode) Option

WithReadOnlyMode is used to determine if/when to set a file's read-only (RO) attribute on Windows. The following values are supported: ReadOnlyModeIgnore do not set a file's RO attribute, and ignore if it's set. ReadOnlyMaskSet set a file's RO attribute if the file's FileMode has the

user writable bit set.

ReadOnlyMaskReset do not set a file's RO attribute, and if it's set, reset it.

func WithSetSymlinkOwner

func WithSetSymlinkOwner(setSymlinkOwner bool) Option

WithSetSymlinkOwner sets the symlink's owner to be the current user. Otherwise, the symlink will have a default owner assigned by the system, such as BUILTIN\Administrator.

type Options

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

Options define the behavior of `WriteReaderAtomic()`, etc.

type ReadOnlyMode

type ReadOnlyMode int

ReadOnlyMode defines how to handle a file's read-only attribute on Windows.

const (
	// ReadOnlyModeIgnore does not set a file's read-only attribute, and ignores
	// if it's set (Windows only).
	ReadOnlyModeIgnore ReadOnlyMode = 0 + iota
	// ReadOnlyMaskSet set a file's read-only attribute, if the specified
	// perm FileMode has the user writable bit (0o200) set. Otherwise, it will
	// resets (clears) it. (Windows only).
	ReadOnlyModeSet
	// ReadOnlyMaskReset does not set a file's read-only attribute, and if it's
	// set, it resets (clears) it. (Windows only).
	ReadOnlyModeReset
)

type ReniceError

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

ReniceError is returned when the system failed to set the OS's niceness level.

func (*ReniceError) Error

func (e *ReniceError) Error() string

type SupportedType

type SupportedType = supportsType

Deprecated: Use Supports*() functions instead. This may be removed in the future.

type UserIDSourceType

type UserIDSourceType uint

UserIDSourceType defines if the underlying source for the user's ID, is an int (UID() function), or a string (User() function).

const (
	// UserIDSourceIsInt defines if the OS uses an int to identify the user.
	UserIDSourceIsInt UserIDSourceType = 1 << iota
	// UserIDSourceIsString defines if the OS uses a string to identify the
	// user.
	UserIDSourceIsString
	// UserIDSourceIsSID defines if the OS uses a SID to identify the user.
	UserIDSourceIsSID
	// UserIDSourceIsNone defines if the OS does not provide user's IDs, so
	// we provide sane defaults instead.
	UserIDSourceIsNone
)

func UserIDSource

func UserIDSource() UserIDSourceType

UserIDSource returns the source of the user's ID: UserIDSourceIsInt, UserIDSourceIsString, or UserIDSourceIsNone.

type WalkDirFunc

type WalkDirFunc func(path string, d DirEntry, err error) error

WalkDirFunc is the type of the function called by WalkDir to visit each file or directory.

The path argument contains the argument to WalkDir as a prefix. That is, if WalkDir is called with root argument "dir" and finds a file named "a" in that directory, the walk function will be called with argument "dir/a".

The d argument is the DirEntry for the named path.

The error result returned by the function controls how WalkDir continues. If the function returns the special value SkipDir, WalkDir skips the current directory (path if d.IsDir() is true, otherwise path's parent directory). If the function returns the special value SkipAll, WalkDir skips all remaining files and directories. Otherwise, if the function returns a non-nil error, WalkDir stops entirely and returns that error.

The err argument reports an error related to path, signaling that WalkDir will not walk into that directory. The function can decide how to handle that error; as described earlier, returning the error will cause WalkDir to stop walking the entire tree.

WalkDir calls the function with a non-nil err argument in two cases.

First, if the initial Stat on the root directory fails, WalkDir calls the function with path set to root, d set to nil, and err set to the error from fs.Stat.

Second, if a directory's ReadDir method (see [ReadDirFile]) fails, WalkDir calls the function with path set to the directory's path, d set to an DirEntry describing the directory, and err set to the error from ReadDir. In this second case, the function is called twice with the path of the directory: the first call is before the directory read is attempted and has err set to nil, giving the function a chance to return SkipDir or SkipAll and avoid the ReadDir entirely. The second call is after a failed ReadDir and reports the error from ReadDir. (If ReadDir succeeds, there is no second call.)

The differences between WalkDirFunc compared to path/filepath.WalkFunc are:

• The second argument has type DirEntry instead of FileInfo.
• The function is called before reading a directory, to allow SkipDir or SkipAll to bypass the directory read entirely or skip all remaining files and directories respectively.
• If a directory read fails, the function is called a second time for that directory to report the error.