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 OS' 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	✅	✅	✅	✅	✅	✅‡

Key:
✅ 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).

* 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).

Other Functions

The table below lists the OS' support for other functions in this library:

OS	Chmod()*	Fstat()	Nice()/ Renice()	PartitionType()	Symlink()	Umask()
AIX	✅	❌	✅	✅*	✅	✅
Android	✅	✅	✅	✅	✅	✅
Dragonfly	✅	✖️	✅	✅	✅	✅
FreeBSD	✅	✖️	✅	✅‡	✅	✅
Illumos	✅	❌	✅	✅	✅	✅
iOS	✅	✅	☑️	✅	✅	✅
Js/ WASM	❌	❌	☑️	✅	❌	✅
Linux	✅	✅	✅	✅	✅	✅
macOS	✅	✅	✅	✅	✅	✅
NetBSD	✅	✖️	✅	✅‡	✅	✅
OpenBSD	✅	❌	✅	✅‡	✅	✅
Plan9	✅	✅	✅	✅	✅	❌
Solaris	✅	❌	✅	✅	✅	✅
Wasip1/ WASM	❌	❌	☑️	✅	❌	✅†
Windows	✅	✅	✅	✅	✅	✅

Key:
✅ fully supported.
☑️ Nice() always returns 0. Renice() does nothing.
✖️ not implemented (but if the OS supports it, so we could add support).
❌ not implemented (as it appears the OS doesn't support it).

* Support will depend on the underlying file system. See Comparison of file systems for details.
† Not supported if compiled using the Tinygo compiler.
‡ Not supported on openbsd/ppc64, netbsd/386, freebsd/riscv64, and aix/ppc64 (cgo only), due to compile issues.

Contributing

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

License

This project is MIT licensed.