Document mntopts(3) functions and add getmntpoint() and chkdoreload().

[mckusick]

Summary

The mntopts(3) functions support operations associated with a mount point. The main purpose of this commit is to document the mntopts(3) functions that now appear in 18 utilities in the base system. See mntopt.3 below for the documentation details.

The getmntopts() function appeared in 4.4BSD. The build_iovec(), build_iovec_argf(), free_iovec(), checkpath(), and rmslashes() functions were added with nmount(8) in FreeBSD 5.0. The getmntpoint() and chkdoreload() functions are being added in this commit for FreeBSD 14.0. Only the getmntopts() function was documented and its manual page was never installed.

These functions should be in a library but for historic reasons are in a file in the sources for the mount(8) program. Thus, to access them the following lines need to be added to the Makefile of the program wanting to use them:

SRCS+= getmntopts.c
MOUNT= ${.CURDIR:H}/mount
CFLAGS+= -I${MOUNT}
.PATH: ${MOUNT}

Once these changes have been MFC'ed to 13 they may be made into a library, -lmntops. Please comment on whether you think mntopts(3) should be made into a library.

Test Plan

Have Peter Holm run his filesystem tests on the affected utilities.

[kib]

Why not add the functions to libutil?

[mckusick]

In D37907#861317, @kib wrote:

Why not add the functions to libutil?

The functions are being added to the rest of the functions to which they relate and which they use. One could argue that all these functions should move to libutil though they really all specific to mount points and thus are specialized enough that they are better kept where they are or in a library of their own.

[kib]

If you do not want to move it to libutil, then a private library might be due. I do not like idea of shipping one more library for such specialized purpose.

Private libraries are not distributed, they are only built during buildword stage and are statically linked into consumers. To build it, it seems to be enough to put INTERNALLIB= line into Makefile.

[mckusick]

In D37907#862802, @kib wrote:

If you do not want to move it to libutil, then a private library might be due. I do not like idea of shipping one more library for such specialized purpose.

Private libraries are not distributed, they are only built during buildword stage and are statically linked into consumers. To build it, it seems to be enough to put INTERNALLIB= line into Makefile.

These functions are not currently set up as a library. As noted in my description, the getmntopts.c and mntopts.h files are in the sbin/mount directory. Programs that want to use them bring them in using:

SRCS+= getmntopts.c
MOUNT= ${SRCTOP}/sbin/mount
CFLAGS+= -I${MOUNT}
.PATH: ${MOUNT}

Likely there are many programs in ports that also use them. So my take is to take out the part in the manual page about making them a library:

--- a/sbin/mount/mntopts.3
+++ b/sbin/mount/mntopts.3
@@ -71,8 +71,7 @@
The
.Nm mntopts
functions support operations associated with a mount point.
-They should be in a library but for historic reasons
-are in a file in the sources for the
+For historic reasons are in a file in the sources for the
.Xr mount 8
program.

Then make this commit as it is currently shown. This will have the benefit of getting rid of the redundant (and in one instance wrong) copies of these files without breaking any existing uses of them in the tree or in ports. It will also create much needed documentation for folks coming across these functions and wondering what they are doing and where to find if they wish to use them.

[kib]

In D37907#864700, @mckusick wrote:

In D37907#862802, @kib wrote:

If you do not want to move it to libutil, then a private library might be due. I do not like idea of shipping one more library for such specialized purpose.

Private libraries are not distributed, they are only built during buildword stage and are statically linked into consumers. To build it, it seems to be enough to put INTERNALLIB= line into Makefile.

These functions are not currently set up as a library. As noted in my description, the getmntopts.c and mntopts.h files are in the sbin/mount directory. Programs that want to use them bring them in using:

SRCS+= getmntopts.c
MOUNT= ${SRCTOP}/sbin/mount
CFLAGS+= -I${MOUNT}
.PATH: ${MOUNT}

Likely there are many programs in ports that also use them.

I suspect there are not many programs in ports that use them, or even there is no such programs at all. The reason is that poudriere typically builds packages without sources for the base system installed.

So my take is to take out the part in the manual page about making them a library:

--- a/sbin/mount/mntopts.3
+++ b/sbin/mount/mntopts.3
@@ -71,8 +71,7 @@
The
.Nm mntopts
functions support operations associated with a mount point.
-They should be in a library but for historic reasons
-are in a file in the sources for the
+For historic reasons are in a file in the sources for the
.Xr mount 8
program.

Then make this commit as it is currently shown. This will have the benefit of getting rid of the redundant (and in one instance wrong) copies of these files without breaking any existing uses of them in the tree or in ports. It will also create much needed documentation for folks coming across these functions and wondering what they are doing and where to find if they wish to use them.

It is probably fine as the first step, but ultimately the common code should be moved into the library instead of build system being abused this way.

[gbe]

LGTM for the manual page parts.

[arrowd]

Just for information: I had to copy-paste build_iovec() when I was porting Collabora Online: https://github.com/CollaboraOnline/online/blob/master/tools/mount.cpp#L39

[kib]

So if you indeed want to make them usable outside the src/ tree, move the functions into a convenience library (just libXXX.a) and install it into /usr/lib?