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, and being cleaned (i.e. no extra slashes or dots). 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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Mounted ¶
Mounted determines if a specified path is a mount point. In case of any error, false (and an error) is returned.
If a non-existent path is specified, an appropriate error is returned. In case the caller is not interested in this particular error, it should be handled separately using e.g. errors.Is(err, fs.ErrNotExist).
func MountedFast ¶ added in v0.6.0
MountedFast is a method of detecting a mount point without reading mountinfo from procfs. A caller can only trust the result if no error and sure == true are returned. Otherwise, other methods (e.g. parsing /proc/mounts) have to be used. If unsure, use Mounted instead (which uses MountedFast, but falls back to parsing mountinfo if needed).
If a non-existent path is specified, an appropriate error is returned. In case the caller is not interested in this particular error, it should be handled separately using e.g. errors.Is(err, fs.ErrNotExist).
This function is only available on Linux. When available (since kernel v5.6), openat2(2) syscall is used to reliably detect all mounts. Otherwise, the implementation falls back to using stat(2), which can reliably detect normal (but not bind) mounts.
Types ¶
type FilterFunc ¶
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 (fully populated with all available fields on the GOOS platform), and returns two booleans:
skip: true if the entry should be skipped;
stop: true if parsing should be stopped after the entry.
func FSTypeFilter ¶ added in v0.3.1
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, or are equal to the path specified in prefix. The prefix path must be absolute, have all symlinks resolved, and cleaned (i.e. no extra slashes or dots).
PrefixFilter treats prefix as a path, not a partial prefix, which means that given "/foo", "/foo/bar" and "/foobar" entries, PrefixFilter("/foo") returns "/foo" and "/foo/bar", and discards "/foobar".
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 is the ID of the parent mount (or of self for the root
// of this mount namespace's mount tree).
Parent int
// Major and Minor are the major and the minor components of the Dev
// field of unix.Stat_t structure returned by unix.*Stat calls for
// files on this filesystem.
Major, Minor int
// Root is the pathname of the directory in the filesystem which forms
// the root of this mount.
Root string
// Mountpoint is the pathname of the mount point relative to the
// process's root directory.
Mountpoint string
// Options is a comma-separated list of mount options.
Options string
// Optional are zero or more fields of the form "tag[:value]",
// separated by a space. Currently, the possible optional fields are
// "shared", "master", "propagate_from", and "unbindable". For more
// information, see mount_namespaces(7) Linux man page.
Optional string
// FSType is the filesystem type in the form "type[.subtype]".
FSType string
// Source is filesystem-specific information, or "none".
Source string
// VFSOptions is a comma-separated list of superblock 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 ¶ added in v0.1.2
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 fake mountinfo data, or when a source other than /proc/thread-self/mountinfo needs to be read from.
This function is Linux-specific.
func PidMountInfo
deprecated
PidMountInfo retrieves the list of mounts from a given process' mount namespace. Unless there is a need to get mounts from a mount namespace different from that of a calling process, use GetMounts.
This function is Linux-specific.
Deprecated: this will be removed before v1; use GetMountsFromReader with opened /proc/<pid>/mountinfo as an argument instead.
Source Files