mountpoint(1): new utility, implemented as a stat(1) hardlink using SFBSD_MNTPOINT

[sobomax]

Summary

Add mountpoint(1), which reports whether a directory is a mount point. This revision reworks it following kib's review. Git branch: https://github.com/sobomax/freebsd/tree/mountpoint

The first version compared realpath(3) of the argument with realpath(3) of statfs(2)'s f_mntonname. As kib pointed out, that cannot work for deep enough hierarchies, and it is unreliable after chroot(2) or inside a jail. D59910 (now in main as 0d5d8872931c) makes stat(2) set SFBSD_MNTPOINT in st_bsdflags when the vnode is the root of a mounted file system. With that, the answer comes from the kernel with a single stat(2), so mountpoint(1) becomes a hardlink to stat(1), the same way readlink(1) is.

• stat.c: when invoked as mountpoint, main() hands off to mountpoint_main(). It calls stat(2) on the argument (symbolic links are followed), requires a directory, and checks SFBSD_MNTPOINT. The interface is mountpoint [-q] directory. It prints <dir> is a mount point or <dir> is not a mount point, and -q suppresses that line but not error messages. Exit status is 0 for a mount point, 1 for not a mount point, and 2 on error, including usage errors.
• stat/Makefile: mountpoint is added to LINKS and MLINKS, next to readlink, so man mountpoint opens stat(1).
• stat.1: mountpoint is documented in NAME, SYNOPSIS, DESCRIPTION, the -q entry (whose meaning differs for mountpoint), EXIT STATUS and EXAMPLES.
• tests/mountpoint_test.sh: new ATF tests, described in the test plan.

Because the kernel reports what is true of the vnode, a chroot or jail root that is not itself a mount point is reported as "not a mount point". .. from that root stays inside it, so a mount point above the root is never reported.

Files: usr.bin/stat/Makefile, stat.1, stat.c, tests/Makefile, tests/mountpoint_test.sh (479 insertions, 5 deletions against main).

Test Plan

New ATF test cases in usr.bin/stat/tests/mountpoint_test.sh:

Test case	What it checks
not_mountpoint	a plain directory is not a mount point, with and without -q
errors	not a directory, nonexistent path and usage errors exit 2
mountpoint	a tmpfs is a mount point, also through a symlink; a subdirectory of it is not; -q prints nothing
chroot_root_not_mountpoint, jail_root_not_mountpoint	the root is a plain directory on top of a tmpfs; /, /.. and /bin are not mount points, so the mount above the root does not leak in
chroot_root_mountpoint, jail_root_mountpoint	the root is a tmpfs; / and /.. are mount points, /bin is not
chroot_root_nullfs, jail_root_nullfs	the root is a nullfs mount; / is a mount point, /bin is not
chroot_submount, jail_submount	a tmpfs mounted from the host inside a plain root; /mnt is a mount point, / and /mnt/.. are not
jail_mount_inside	a jail with allow.mount, allow.mount.tmpfs and enforce_statfs=1 mounts its own tmpfs on /mnt; /mnt is a mount point and / is not

Every case except the first two needs root. The chroot and jail cases build a minimal root containing sh, mountpoint and their shared libraries. Each check runs sh -c 'mountpoint X; echo rc=$?', because jail -c command= exits 1 whenever the command fails instead of passing its status through. The jail cases skip when already running inside a jail. Cleanup unmounts everything in reverse order.

Results:

• main: stat(1) from this branch builds with the default -Werror flags. The build machine runs releng/14.3, so it used main's sys/stat.h with the host's other headers.
• All 12 cases pass with that binary .
• Without D59910: on a kernel that lacks it, mountpoint fails at its first positive check (mnt is not a mount point), as expected. The negative cases still pass.
• Man page: mandoc -Tlint stat.1 reports only style notes that were already there. A DESTDIR install shows mountpoint and mountpoint.1.gz as hardlinks to stat and stat.1.gz, and man mountpoint renders stat(1).
• On the running system: mountpoint / and mountpoint /dev report a mount point, and mountpoint /usr/bin does not.

[kib]

This cannot work for deep enough hierarchies. Also I am not sure that it works after chroot or jailing, or rather it should not.

I propose the following D59910. It should allow you to get the info directly from source, with single stat(2).

usr.bin/mountpoint/mountpoint.c

46 ↗

(On Diff #187432)

nullfs supports file and socket mounts over files

[kib]

In D59906#1374853, @kib wrote:

This cannot work for deep enough hierarchies. Also I am not sure that it works after chroot or jailing, or rather it should not.

I propose the following D59910. It should allow you to get the info directly from source, with single stat(2).

And then might be mountpoint(1) should become a hardlink to stat(1).

[sobomax]

This comment was removed by sobomax.

[sobomax]

@kib reimplemented atop SFBSD_MNTPOINT and made into a stat(1) alias. Please re-review, thanks!

[kib]

usr.bin/stat/stat.1

86

'as reported ...' is an implementation detail not too important to the reader IMO. I would suggest to either remove that part, or put it into the next paragraph after this one, where the text already mentions stat(2).

usr.bin/stat/stat.c

427

Do you want to skip mounts over the regular files and sockets?

[sobomax]

@kib

• usr.bin/stat/stat.1:86 ("'as reported ...' is an implementation detail") ---

Agreed, moved it. The mountpoint paragraph now only says what the utility does, and adds that nullfs(5) can mount over regular files and sockets. The SFBSD_MNTPOINT / st_bsdflags sentence is now in the next paragraph, which already explains that stat uses lstat(2): "When invoked as mountpoint, stat(2) is called instead and the SFBSD_MNTPOINT flag in the st_bsdflags field is checked."

• usr.bin/stat/stat.c:427 ("Do you want to skip mounts over the regular files and sockets?") ---

No, good catch. nullfs sets VV_ROOT on its root vnode whatever its type, so stat(2) already reports SFBSD_MNTPOINT for file and socket mounts, and the S_ISDIR() check only hid them behind a "not a directory" error. The check is gone. The argument is now called "file" in the usage line and the man page, and a non-directory that is not a mount point is reported as "not a mount point" (exit 1). I added a test that nullfs-mounts a file over a file and expects a mount point, directly and through a symlink.