os.Stat returns fs.FileInfo which is an interface with six methods:

type FileInfo interface {
	Name() string       // base name of the file
	Size() int64        // length in bytes for regular files; [..]
	Mode() FileMode     // file mode bits
	ModTime() time.Time // modification time
	IsDir() bool        // abbreviation for Mode().IsDir()
	Sys() any           // underlying data source (can return nil)
}

Time of last modification (mtime) is the only time reported by this interface, though. There is no time of last access (atime), creation (btime), nor status change (ctime).

Sys()

Did you notice that Sys() method there? Yeah, me neither. This poorly documented method returns raw data for that file, as returned by the operating system. That means the underlying type of the result will be different per-OS. In our case, it’s a software intended to run exclusively on linux, so let’s see what happens there.

Well, in Linux, it returns a pointer to syscall.Stat_t :

type Stat_t struct {
	Dev       uint64
	Ino       uint64
	Nlink     uint64
	Mode      uint32
	Uid       uint32
	Gid       uint32
	X__pad0   int32
	Rdev      uint64
	Size      int64
	Blksize   int64
	Blocks    int64
	Atim      Timespec
	Mtim      Timespec
	Ctim      Timespec
	X__unused [3]int64
}

Great, we have atime, mtime and ctime. We’ve almost declared a win, until realizing that ctime is not creation time. It’s the time of last status change, which means it records any change of file’s metadata. What we seek is creation time a.k.a. birth time. Yep, I’ve just used almost 300 words to tell you that with os.Stat you can NOT get the creation time of a file.

statx(2)

To be fair, you would not be able to get the creation time using stat in C, either. Not to mention that most of the filesystems do not keep record of it. That was surprising to me - fat32, ext2, ext3 nor reiserfs store when a file has been created. Naturally, no such information is exposed by stat(2). Modern filesystems do, though.

After years of planning a new system call is finally merged into the Linux kernel and released with 4.11 in 2017. That’s years after the first released version of Go and five after 1.0. That explains why the standard library does not provide a straightforward way to obtain btime.

golang.org/x/sys/unix

The standard library might be a bit conservative in adding new things (although things are starting to move now with the new math/rand/v2 ), but that does not mean the Go team is sleeping. The golang.org/x/ packages are outside the main Go tree and are under way looser constraints for backwards compatibility. One of these packages is golang.org/x/sys/unix . The sys part is described as “packages for making system calls”, so do not expect the easiest to use API you’ve ever seen.

Sure enough, there’s a wrapper function of the statx syscall:

func Statx(dirfd int, path string, flags int, mask int, stat *Statx_t) (err error)

As expected the API is pretty much the same as with the syscall it wraps:

int statx(int dirfd, const char *restrict pathname, int flags,
          unsigned int mask, struct statx *restrict statxbuf);

• dirfd is a file descriptor identifying the directory to search from if provided path is relative (if is AT_FDCWD the call operates on the current working directory).
• path is obviously the filename we’re querying. Unless when empty and AT_EMPTY_PATH is in mask, in that case file/directory pointed to by dirfd is what we’re querying.
• flags can be used to influence a pathname-based lookup and what sort of synchronization the kernel will do when querying. When in doubt, use AT_STATX_SYNC_AS_STAT.
• mask is used to tell which fields we are interested in, so that the kernel does not bother populating the rest. The one we care about to is STATX_BTIME. If it’s there (or STATX_ALL which pretty much includes everything), then the creation time will be there.
• stat is being populated be the syscall when the returned error is nil.

All of those SCREAMING_SNAKE_CASE flags listed above are exposed as constants in the same package.

unix.Statx_t is a fairly big struct (matching the statx struct obviously) that has all of the timestamps we seek:

type Statx_t struct {
	// ...
	Atime            StatxTimestamp
	Btime            StatxTimestamp
	Ctime            StatxTimestamp
	Mtime            StatxTimestamp
    //..
}

StatxTimestamp has Sec and Nsec fields which is enough to create a time.Time value using time.Unix(). So, the whole thing might look something like this:

var statx unix.Statx_t
err := unix.Statx(unix.AT_FDCWD, name, unix.AT_STATX_SYNC_AS_STAT, unix.STATX_BTIME, &statx)
if err != nil {
    log.Fatal(err)
}

btime := time.Unix(statx.Btime.Sec, int64(statx.Btime.Nsec))
fmt.Printf("%s is created at %v\n", name, btime)

Easy, right?

Don’t agree? Yeah, me neither. A saner person would just npm the problem and look for a package exposing file times in a proper, easy-to-use way. I found this, which looks legit (only checked for GOOS=linux): github.com/djherbis/times .

I mean it. A third-party package with a higher-level portable API is the way to go in the real world. It’s good to know what’s happening underneath, but please beware of NIH syndrome.

Achieving the same result in Python isn’t much easier. The result from os.stat might have a st_birthtime on some operating systems (e.g., FreeBSD or Windows), but not on Linux. Sometimes seemingly trivial problems are tedious to solve because of weird historical reasons. And sometimes, a deeper dive is necessary, but practical solutions are often just a package away.

❯ go doc context WithValue
package context // import "context"

func WithValue(parent Context, key, val any) Context
    WithValue returns a copy of parent in which the value associated with key is
    val.

    Use context Values only for request-scoped data that transits processes and
    APIs, not for passing optional parameters to functions.

    The provided key must be comparable and should not be of type string or any
    other built-in type to avoid collisions between packages using context.
    Users of WithValue should define their own types for keys. To avoid
    allocating when assigning to an interface{}, context keys often have
    concrete type struct{}. Alternatively, exported context key variables'
    static type should be a pointer or interface.

This whole article exists because of this:

Users of WithValue should define their own types for keys.

OK, but what would that type be? It should NOT be a string, but its underlying type could be one. In fact, over the years, I’ve used an internal string type with a value equal to the full package name:

// ctxt is a dummy type for storing context values.
//
// For more information see the documentation of context.WithValue.
type ctxt string

var ctxkey ctxt = "github.com/org/project/pkg"

Now &ctxkey is what we use as context key as suggested by the documentation in order to avoid useless allocations. Often I would introduce public functions to take or store their expected value, without dealing with keys, mostly for testing. Suppose all this package needs a ctx type for is to store values of type T:

// FromContext extracts a value of type T from the given context, returning its
// zero value if not present.
func FromContext(ctx context.Context) T {
	v, ok := ctx.Value(&ctxkey).(T)
	if !ok {
		v = NewT()
	}
	return v
}

// WithValue returns a copy of parent with stored T inside.
func WithValue(parent context.Context, t T) context.Context {
	return context.WithValue(parent, &ctxkey, t)
}

pkg.FromContext(ctx) takes a context and returns the pkg.T stored inside, if any, for instance.

The point to store the full package name is merely to ease debugging and/or tracing. This string is allocated only once, and we are using a pointer to it, in order not to allocate once per assigning that key to interface{}. If we want to get fanatical about that, the type of ctxt might be an empty struct:

// ctxkey is a dummy type for storing context values.
//
// For more information see the documentation of context.WithValue.
type ctxkey struct{}

Now we no longer need to use a pointer to ctxkey and just directly pass ctxkey{} instead, because a value of struct{} never allocates as its size is 0 anyways. When debugging you would still see the type of ctxkey, which (as with any type) contains the full path to it.

I have no memory which tool/use-case didn’t work well with struct{} so I’ve started using a string in the first place, but I’m back to using struct{} again these days.

What about generics?

Yes, of course. Go has generics now for quite some time, why not sprinkling some of it to solve that? We could. In fact, there is a proposal that is placed on hold (at the moment of writing this) in order to give the community time to play more with generics: https://github.com/golang/go/issues/49189

If you have tens of packages storing stuff in contexts and are pretty sure that this makes sense, might as well steal the proposed Key[T] from there.

Say we’re working on a system for publishing articles, allowing discussion below each article, with the following requirements:

• Moderators can edit all articles and comments
• Authors can create articles and edit only those created by themselves
• Users can read articles and post comments about them
• Any user-type can edit and delete their own profile

We could define different user-levels as a bit-mask and store that alongside user’s information (e.g. users table in the database):

const (
	user = 1 << iota    // 0001
	author              // 0010
	moderator           // 0100
	self                // 1000
)

Each of the actions listed above can now be expressed as a list of user types allowed to perform them, by using the bitwise OR operator, omitting actions allowed by everybody even without an account:

const (
	CreateArticle = author
	UpdateArticle = self | moderator
	DeleteArticle = self | moderator

	CreateComment = user | author | moderator
	UpdateComment = moderator
	DeleteComment = moderator

	UpdateUser = self
	DeleteUser = self
)

Each action has only the bits of every user type set to 1. For instance CreateArticle is 2 (0010), UpdateArticle is 12 (1100) and CreateComment is 7 (0111). We could now create a function which determines whether given action is allowed by simply checking if they share at least one bit set to 1, for which we’re going to utilize the bitwise AND operator.

self is a bit tricky here, because it must be populated differently per-entity. So we should make sure that both users, articles and comments have ID:

type User struct {
	ID   ID
	Role int
	Name string
	// ...
}

type Article struct {
	ID     ID
	Author ID
	Name   string
	// ...
}

type Comment struct {
	ID      ID
	Author  ID
	Article ID
	// ...
}

The ID type here can be anything comparable (e.g. int, string, UUID). Now the function in question is painfully obvious:

func Allowed(u User, action int, target ID) bool {
	if user.ID == target {
		u.Role |= self
	}

	return u.Role&action != 0
}

target is the ID of whatever is being acted upon or left with the zero value for that type when not applicable (e.g. on any Create… action). In order to check whether a user (u) can update given article (a) we call Allowed(u, UpdateArticle, a.Author) and handle (e.g. return error) when the result is false.

However…

You’ve probably already figured out that this mimics the way Unix operating systems encode filesystem access. I could think of a few pros to this approach:

• The check whether given action is allowed is trivial
• Adding new user type is a single line of code. Each new user adds exactly one bit to the mask, so until we go above 64, everything’s fine
• Permissions are obvious even to non-technical people
• Same is applicable to pretty much any programming language I can think of

However, this does not come without gotchas. Take that self which is not really a user type, but a made-up concept to allow everybody to edit some of their own creations. We had to add it, because it’s not a desired capability for all entities. Comments for instance can NOT be edited, once posted. Not only that, we had to add a new argument and logic to our little pure function.

One could think of a few new requirements that would seem simple, yet require more arguments, more checks and eventually a complete overhaul of this whole idea. Technically speaking, even the Unix permissions turned out to be not enough and modern Unix-like operating systems implement more complex ACLs stored in the extended file attributes on top of it.