mountinfo

Documentation

Overview

Package mountinfo provides a set of functions to retrieve information about OS mounts.

Currently it supports Linux. For historical reasons, there is also some support for FreeBSD and OpenBSD, and a shallow implementation for Windows, but in general this is Linux-only package, so the rest of the document only applies to Linux, unless explicitly specified otherwise.

In Linux, information about mounts seen by the current process is available from /proc/self/mountinfo. Note that due to mount namespaces, different processes can see different mounts. A per-process mountinfo table is available from /proc/<PID>/mountinfo, where <PID> is a numerical process identifier.

In general, /proc is not a very efficient interface, and mountinfo is not an exception. For example, there is no way to get information about a specific mount point (i.e. it is all-or-nothing). This package tries to hide the /proc ineffectiveness by using parse filters while reading mountinfo. A filter can skip some entries, or stop processing the rest of the file once the needed information is found.

For mountinfo filters that accept path as an argument, the path must be:

• absolute;
• having all symlinks resolved;
• being cleaned.

One way to achieve all of the above is to employ filepath.Abs followed by filepath.EvalSymlinks (the latter calls filepath.Clean on the result so there is no need to explicitly call filepath.Clean).

NOTE that in many cases there is no need to consult mountinfo at all. Here are some of the cases where mountinfo should not be parsed:

1. Before performing a mount. Usually, this is not needed, but if required (say to prevent over-mounts), to check whether a directory is mounted, call os.Lstat on it and its parent directory, and compare their st.Sys().(*syscall.Stat_t).Dev fields -- if they differ, then the directory is the mount point. NOTE this does not work for bind mounts. Optionally, the filesystem type can also be checked by calling unix.Statfs and checking the Type field (i.e. filesystem type).

2. After performing a mount. If there is no error returned, the mount succeeded; checking the mount table for a new mount is redundant and expensive.

3. Before performing an unmount. It is more efficient to do an unmount and ignore a specific error (EINVAL) which tells the directory is not mounted.

4. After performing an unmount. If there is no error returned, the unmount succeeded.

5. To find the mount point root of a specific directory. You can perform os.Stat() on the directory and traverse up until the Dev field of a parent directory differs.

Index

• func Mounted(path string) (bool, error)
• type FilterFunc
  • func FSTypeFilter(fstype ...string) FilterFunc
  • func ParentsFilter(path string) FilterFunc
  • func PrefixFilter(prefix string) FilterFunc
  • func SingleEntryFilter(mp string) FilterFunc
• type Info
  • func GetMounts(f FilterFunc) ([]*Info, error)
  • func GetMountsFromReader(r io.Reader, filter FilterFunc) ([]*Info, error)
  • func PidMountInfo(pid int) ([]*Info, error)

Functions

func Mounted

func Mounted(path string) (bool, error)

Mounted determines if a specified path is a mount point.

The argument must be an absolute path, with all symlinks resolved, and clean. One way to ensure it is to process the path using filepath.Abs followed by filepath.EvalSymlinks before calling this function.

Types

type FilterFunc

type FilterFunc func(*Info) (skip, stop bool)

FilterFunc is a type defining a callback function for GetMount(), used to filter out mountinfo entries we're not interested in, and/or stop further processing if we found what we wanted.

It takes a pointer to the Info struct (not fully populated, currently only Mountpoint, FSType, Source, and (on Linux) VFSOptions are filled in), and returns two booleans:

• skip: true if the entry should be skipped
• stop: true if parsing should be stopped after the entry

func FSTypeFilter

func FSTypeFilter(fstype ...string) FilterFunc

FSTypeFilter returns all entries that match provided fstype(s).

func ParentsFilter

func ParentsFilter(path string) FilterFunc

ParentsFilter returns all entries whose mount points can be parents of a path specified, discarding others.

For example, given `/var/lib/docker/something`, entries like `/var/lib/docker`, `/var` and `/` are returned.

func PrefixFilter

func PrefixFilter(prefix string) FilterFunc

PrefixFilter discards all entries whose mount points do not start with a specific prefix.

func SingleEntryFilter

func SingleEntryFilter(mp string) FilterFunc

SingleEntryFilter looks for a specific entry.

type Info

type Info struct {
	// ID is a unique identifier of the mount (may be reused after umount).
	ID int

	// Parent indicates the ID of the mount parent (or of self for the top of the
	// mount tree).
	Parent int

	// Major indicates one half of the device ID which identifies the device class.
	Major int

	// Minor indicates one half of the device ID which identifies a specific
	// instance of device.
	Minor int

	// Root of the mount within the filesystem.
	Root string

	// Mountpoint indicates the mount point relative to the process's root.
	Mountpoint string

	// Options represents mount-specific options.
	Options string

	// Optional represents optional fields.
	Optional string

	// FSType indicates the type of filesystem, such as EXT3.
	FSType string

	// Source indicates filesystem specific information or "none".
	Source string

	// VFSOptions represents per super block options.
	VFSOptions string
}

Info reveals information about a particular mounted filesystem. This struct is populated from the content in the /proc/<pid>/mountinfo file.

func GetMounts

func GetMounts(f FilterFunc) ([]*Info, error)

GetMounts retrieves a list of mounts for the current running process, with an optional filter applied (use nil for no filter).

func GetMountsFromReader

func GetMountsFromReader(r io.Reader, filter FilterFunc) ([]*Info, error)

GetMountsFromReader retrieves a list of mounts from the reader provided, with an optional filter applied (use nil for no filter). This can be useful in tests or benchmarks that provide a fake mountinfo data.

This function is Linux-specific.

func PidMountInfo

func PidMountInfo(pid int) ([]*Info, error)

PidMountInfo collects the mounts for a specific process ID. If the process ID is unknown, it is better to use `GetMounts` which will inspect "/proc/self/mountinfo" instead.