Skip to content

Commit 9a98556

Browse files
author
Jamie Hannaford
committed
Add documentation for exported functions and types
Signed-off-by: Jamie Hannaford <jamie.hannaford@rackspace.com>
1 parent 98cfa2a commit 9a98556

File tree

8 files changed

+164
-38
lines changed

8 files changed

+164
-38
lines changed

‎pkg/mount/flags_freebsd.go‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,25 @@ package mount
88
import "C"
99

1010
const (
11-
RDONLY = C.MNT_RDONLY
12-
NOSUID = C.MNT_NOSUID
13-
NOEXEC = C.MNT_NOEXEC
11+
// RDONLY will mount the filesystem as read-only.
12+
RDONLY = C.MNT_RDONLY
13+
14+
// NOSUID will not allow set-user-identifier or set-group-identifier bits to
15+
// take effect.
16+
NOSUID = C.MNT_NOSUID
17+
18+
// NOEXEC will not allow execution of any binaries on the mounted file system.
19+
NOEXEC = C.MNT_NOEXEC
20+
21+
// SYNCHRONOUS will allow any I/O to the file system to be done synchronously.
1422
SYNCHRONOUS = C.MNT_SYNCHRONOUS
15-
NOATIME = C.MNT_NOATIME
1623

24+
// NOATIME will not update the file access time when reading from a file.
25+
NOATIME = C.MNT_NOATIME
26+
)
27+
28+
// These flags are unsupported.
29+
const (
1730
BIND = 0
1831
DIRSYNC = 0
1932
MANDLOCK = 0

‎pkg/mount/flags_linux.go‎

Lines changed: 74 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,26 +5,81 @@ import (
55
)
66

77
const (
8-
RDONLY = syscall.MS_RDONLY
9-
NOSUID = syscall.MS_NOSUID
10-
NODEV = syscall.MS_NODEV
11-
NOEXEC = syscall.MS_NOEXEC
8+
// RDONLY will mount the file system read-only.
9+
RDONLY = syscall.MS_RDONLY
10+
11+
// NOSUID will not allow set-user-identifier or set-group-identifier bits to
12+
// take effect.
13+
NOSUID = syscall.MS_NOSUID
14+
15+
// NODEV will not interpret character or block special devices on the file
16+
// system.
17+
NODEV = syscall.MS_NODEV
18+
19+
// NOEXEC will not allow execution of any binaries on the mounted file system.
20+
NOEXEC = syscall.MS_NOEXEC
21+
22+
// SYNCHRONOUS will allow I/O to the file system to be done synchronously.
1223
SYNCHRONOUS = syscall.MS_SYNCHRONOUS
13-
DIRSYNC = syscall.MS_DIRSYNC
14-
REMOUNT = syscall.MS_REMOUNT
15-
MANDLOCK = syscall.MS_MANDLOCK
16-
NOATIME = syscall.MS_NOATIME
17-
NODIRATIME = syscall.MS_NODIRATIME
18-
BIND = syscall.MS_BIND
19-
RBIND = syscall.MS_BIND | syscall.MS_REC
20-
UNBINDABLE = syscall.MS_UNBINDABLE
24+
25+
// DIRSYNC will force all directory updates within the file system to be done
26+
// synchronously. This affects the following system calls: creat, link,
27+
// unlink, symlink, mkdir, rmdir, mknod and rename.
28+
DIRSYNC = syscall.MS_DIRSYNC
29+
30+
// REMOUNT will attempt to remount an already-mounted file system. This is
31+
// commonly used to change the mount flags for a file system, especially to
32+
// make a readonly file system writeable. It does not change device or mount
33+
// point.
34+
REMOUNT = syscall.MS_REMOUNT
35+
36+
// MANDLOCK will force mandatory locks on a filesystem.
37+
MANDLOCK = syscall.MS_MANDLOCK
38+
39+
// NOATIME will not update the file access time when reading from a file.
40+
NOATIME = syscall.MS_NOATIME
41+
42+
// NODIRATIME will not update the directory access time.
43+
NODIRATIME = syscall.MS_NODIRATIME
44+
45+
// BIND remounts a subtree somewhere else.
46+
BIND = syscall.MS_BIND
47+
48+
// RBIND remounts a subtree and all possible submounts somewhere else.
49+
RBIND = syscall.MS_BIND | syscall.MS_REC
50+
51+
// UNBINDABLE creates a mount which cannot be cloned through a bind operation.
52+
UNBINDABLE = syscall.MS_UNBINDABLE
53+
54+
// RUNBINDABLE marks the entire mount tree as UNBINDABLE.
2155
RUNBINDABLE = syscall.MS_UNBINDABLE | syscall.MS_REC
22-
PRIVATE = syscall.MS_PRIVATE
23-
RPRIVATE = syscall.MS_PRIVATE | syscall.MS_REC
24-
SLAVE = syscall.MS_SLAVE
25-
RSLAVE = syscall.MS_SLAVE | syscall.MS_REC
26-
SHARED = syscall.MS_SHARED
27-
RSHARED = syscall.MS_SHARED | syscall.MS_REC
28-
RELATIME = syscall.MS_RELATIME
56+
57+
// PRIVATE creates a mount which carries no propagation abilities.
58+
PRIVATE = syscall.MS_PRIVATE
59+
60+
// RPRIVATE marks the entire mount tree as PRIVATE.
61+
RPRIVATE = syscall.MS_PRIVATE | syscall.MS_REC
62+
63+
// SLAVE creates a mount which receives propagation from its master, but not
64+
// vice versa.
65+
SLAVE = syscall.MS_SLAVE
66+
67+
// RSLAVE marks the entire mount tree as SLAVE.
68+
RSLAVE = syscall.MS_SLAVE | syscall.MS_REC
69+
70+
// SHARED creates a mount which provides the ability to create mirrors of
71+
// that mount such that mounts and unmounts within any of the mirrors
72+
// propagate to the other mirrors.
73+
SHARED = syscall.MS_SHARED
74+
75+
// RSHARED marks the entire mount tree as SHARED.
76+
RSHARED = syscall.MS_SHARED | syscall.MS_REC
77+
78+
// RELATIME updates inode access times relative to modify or change time.
79+
RELATIME = syscall.MS_RELATIME
80+
81+
// STRICTATIME allows to explicitly request full atime updates. This makes
82+
// it possible for the kernel to default to relatime or noatime but still
83+
// allow userspace to override it.
2984
STRICTATIME = syscall.MS_STRICTATIME
3085
)

‎pkg/mount/flags_unsupported.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
package mount
44

5+
// These flags are unsupported.
56
const (
67
BIND = 0
78
DIRSYNC = 0

‎pkg/mount/mount.go‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,12 @@ import (
44
"time"
55
)
66

7+
// GetMounts retrieves a list of mounts for the current running process.
78
func GetMounts() ([]*MountInfo, error) {
89
return parseMountTable()
910
}
1011

11-
// Looks at /proc/self/mountinfo to determine of the specified
12+
// Mounted looks at /proc/self/mountinfo to determine of the specified
1213
// mountpoint has been mounted
1314
func Mounted(mountpoint string) (bool, error) {
1415
entries, err := parseMountTable()
@@ -25,9 +26,10 @@ func Mounted(mountpoint string) (bool, error) {
2526
return false, nil
2627
}
2728

28-
// Mount the specified options at the target path only if
29-
// the target is not mounted
30-
// Options must be specified as fstab style
29+
// Mount will mount filesystem according to the specified configuration, on the
30+
// condition that the target path is *not* already mounted. Options must be
31+
// specified like the mount or fstab unix commands: "opt1=val1,opt2=val2". See
32+
// flags.go for supported option flags.
3133
func Mount(device, target, mType, options string) error {
3234
flag, _ := parseOptions(options)
3335
if flag&REMOUNT != REMOUNT {
@@ -38,9 +40,10 @@ func Mount(device, target, mType, options string) error {
3840
return ForceMount(device, target, mType, options)
3941
}
4042

41-
// Mount the specified options at the target path
42-
// reguardless if the target is mounted or not
43-
// Options must be specified as fstab style
43+
// ForceMount will mount a filesystem according to the specified configuration,
44+
// *regardless* if the target path is not already mounted. Options must be
45+
// specified like the mount or fstab unix commands: "opt1=val1,opt2=val2". See
46+
// flags.go for supported option flags.
4447
func ForceMount(device, target, mType, options string) error {
4548
flag, data := parseOptions(options)
4649
if err := mount(device, target, mType, uintptr(flag), data); err != nil {
@@ -49,15 +52,16 @@ func ForceMount(device, target, mType, options string) error {
4952
return nil
5053
}
5154

52-
// Unmount the target only if it is mounted
55+
// Unmount will unmount the target filesystem, so long as it is mounted.
5356
func Unmount(target string) error {
5457
if mounted, err := Mounted(target); err != nil || !mounted {
5558
return err
5659
}
5760
return ForceUnmount(target)
5861
}
5962

60-
// Unmount the target reguardless if it is mounted or not
63+
// ForceUnmount will force an unmount of the target filesystem, regardless if
64+
// it is mounted or not.
6165
func ForceUnmount(target string) (err error) {
6266
// Simple retry logic for unmount
6367
for i := 0; i < 10; i++ {

‎pkg/mount/mountinfo.go‎

Lines changed: 36 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,40 @@
11
package mount
22

3+
// MountInfo reveals information about a particular mounted filesystem. This
4+
// struct is populated from the content in the /proc/<pid>/mountinfo file.
35
type MountInfo struct {
4-
Id, Parent, Major, Minor int
5-
Root, Mountpoint, Opts, Optional string
6-
Fstype, Source, VfsOpts string
6+
// Id is a unique identifier of the mount (may be reused after umount).
7+
Id int
8+
9+
// Parent indicates the ID of the mount parent (or of self for the top of the
10+
// mount tree).
11+
Parent int
12+
13+
// Major indicates one half of the device ID which identifies the device class.
14+
Major int
15+
16+
// Minor indicates one half of the device ID which identifies a specific
17+
// instance of device.
18+
Minor int
19+
20+
// Root of the mount within the filesystem.
21+
Root string
22+
23+
// Mountpoint indicates the mount point relative to the process's root.
24+
Mountpoint string
25+
26+
// Opts represents mount-specific options.
27+
Opts string
28+
29+
// Optional represents optional fields.
30+
Optional string
31+
32+
// Fstype indicates the type of filesystem, such as EXT3.
33+
Fstype string
34+
35+
// Source indicates filesystem specific information or "none".
36+
Source string
37+
38+
// VfsOpts represents per super block options.
39+
VfsOpts string
740
}

‎pkg/mount/mountinfo_freebsd.go‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ import (
1313
"unsafe"
1414
)
1515

16-
// Parse /proc/self/mountinfo because comparing Dev and ino does not work from bind mounts
16+
// Parse /proc/self/mountinfo because comparing Dev and ino does not work from
17+
// bind mounts.
1718
func parseMountTable() ([]*MountInfo, error) {
1819
var rawEntries *C.struct_statfs
1920

‎pkg/mount/mountinfo_linux.go‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,8 @@ const (
2828
mountinfoFormat = "%d %d %d:%d %s %s %s %s"
2929
)
3030

31-
// Parse /proc/self/mountinfo because comparing Dev and ino does not work from bind mounts
31+
// Parse /proc/self/mountinfo because comparing Dev and ino does not work from
32+
// bind mounts
3233
func parseMountTable() ([]*MountInfo, error) {
3334
f, err := os.Open("/proc/self/mountinfo")
3435
if err != nil {
@@ -80,7 +81,9 @@ func parseInfoFile(r io.Reader) ([]*MountInfo, error) {
8081
return out, nil
8182
}
8283

83-
// PidMountInfo collects the mounts for a specific Pid
84+
// PidMountInfo collects the mounts for a specific process ID. If the process
85+
// ID is unknown, it is better to use `GetMounts` which will inspect
86+
// "/proc/self/mountinfo" instead.
8487
func PidMountInfo(pid int) ([]*MountInfo, error) {
8588
f, err := os.Open(fmt.Sprintf("/proc/%d/mountinfo", pid))
8689
if err != nil {

‎pkg/mount/sharedsubtree_linux.go‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,34 +2,50 @@
22

33
package mount
44

5+
// MakeShared ensures a mounted filesystem has the SHARED mount option enabled.
6+
// See the supported options in flags.go for further reference.
57
func MakeShared(mountPoint string) error {
68
return ensureMountedAs(mountPoint, "shared")
79
}
810

11+
// MakeRShared ensures a mounted filesystem has the RSHARED mount option enabled.
12+
// See the supported options in flags.go for further reference.
913
func MakeRShared(mountPoint string) error {
1014
return ensureMountedAs(mountPoint, "rshared")
1115
}
1216

17+
// MakePrivate ensures a mounted filesystem has the PRIVATE mount option enabled.
18+
// See the supported options in flags.go for further reference.
1319
func MakePrivate(mountPoint string) error {
1420
return ensureMountedAs(mountPoint, "private")
1521
}
1622

23+
// MakeRPrivate ensures a mounted filesystem has the RPRIVATE mount option
24+
// enabled. See the supported options in flags.go for further reference.
1725
func MakeRPrivate(mountPoint string) error {
1826
return ensureMountedAs(mountPoint, "rprivate")
1927
}
2028

29+
// MakeSlave ensures a mounted filesystem has the SLAVE mount option enabled.
30+
// See the supported options in flags.go for further reference.
2131
func MakeSlave(mountPoint string) error {
2232
return ensureMountedAs(mountPoint, "slave")
2333
}
2434

35+
// MakeRSlave ensures a mounted filesystem has the RSLAVE mount option enabled.
36+
// See the supported options in flags.go for further reference.
2537
func MakeRSlave(mountPoint string) error {
2638
return ensureMountedAs(mountPoint, "rslave")
2739
}
2840

41+
// MakeUnbindable ensures a mounted filesystem has the UNBINDABLE mount option
42+
// enabled. See the supported options in flags.go for further reference.
2943
func MakeUnbindable(mountPoint string) error {
3044
return ensureMountedAs(mountPoint, "unbindable")
3145
}
3246

47+
// MakeRUnbindable ensures a mounted filesystem has the RUNBINDABLE mount
48+
// option enabled. See the supported options in flags.go for further reference.
3349
func MakeRUnbindable(mountPoint string) error {
3450
return ensureMountedAs(mountPoint, "runbindable")
3551
}

0 commit comments

Comments
 (0)