Bug: libmount essentially undocumented

[Werner Baumann <werner.baumann@onlinehome.de>]

While there is a documentation at
https://www.kernel.org/pub/linux/utils/util-linux/v2.24/libmount-docs/index.html
this documentation mainly consists of nice formatting with almost no
information about what the library functions are doing. Therefore the
library is essentially unusable (except for the maintainer of the
library).

Some examples:

* libmount Overview
"The libmount library is used to parse /etc/fstab, /etc/mtab
and /proc/self/mountinfo files, manage the mtab file, evaluate mount
options, etc."
That's all. Well, "etc" may be a good starting point.

* struct libmnt_context
This is a central object of the library, used by a zillion of
functions. While it is perfectly o.k. to hide the internals from the
public interface, it is not o.k. to have no description of this object
at all.
What kind of data will it hold (well, the context I know)?
What is its intended use? There is one example use case, without
explanation except:
"This code is similar to: mount -o
aaa,bbb,ccc=CCC,noatime,noexec /mnt/foo", nothing more.
Please not: it says "similar to", not "the same as". It's anyone's guess
what might be the difference.

* mnt_new_context ()
"struct libmnt_context * mnt_new_context (void);
 Returns : newly allocated mount context"
Nothing more. What's the initial state of the context. What values are
the mount options set to. The defaults from 'man mount'? All zeros? Is
all zeros the same as the defaults from 'man mount'?
What are necessary functions to apply before you can use the mount
context in a call of mnt_context_mount(), what is optional?

* mnt_context_prepare_mount ()
"int mnt_context_prepare_mount (struct libmnt_context *cxt);
 Prepare context for mounting, unnecessary for mnt_context_mount().
 cxt : context
 Returns : negative number on error, zero on success"
Is this all I have to do. How does this function know which file system
I want to mount?
More confusing: A inline comment in the nfs mount program (maintained
by the maintainer of libmount) says:
"The libmount strictly uses only options from fstab if running in restricted mode (suid, non-root user). This is done in mnt_context_prepare_mount() by default."
Why is this not mentioned in the documentation of
mnt_context_prepare_mount? And how does the library know whether it is
in "restricted mode"? mnt_context_apply_fstab too has no information on
this.

* mnt_context_set_options ()
"int mnt_context_set_options (struct libmnt_context *cxt, const char
*optstr);
 cxt : mount context
 optstr : comma delimited mount options
 Returns : 0 on success, negative number in case of error."
What will happen when this function is applied a second time? Will the
new options replace the old ones, or will the new options be merged
into the old ones? Naming the function "*_set_*" indicates replacement,
for merging I would expect a name with "_add_". But looking at the nfs
code it seems to add the new optons and not replace the old ones.

* By chance I noticed a new file on my system: "/var/run/mount/utab".
  Not worth mentioning? Funnily comments in the nfs code mention
  "/dev/.mount/utab" which I can't find on my system. Maybe udev will
  create it on occasion or is it just the same moved to another
  location?

I will stop the examples here. It's the same with almost all functions
in libmount. From the documentation you can't know what a function will
do, leave alone what preconditions must be met before applying a
function on the mount context.

I consider this bug serious because it renders the library unusable.

Cheers
Werner