Re: Better for mount(2)
Here is an improved version, after a lot of feedback from jmc@.
Quick list of changes:
* the unmount description moved closer to the top, since we
mention it in flags description anyway;
* list of mount options is now sorted;
* the description of the MNT_RELOAD flag was added;
* the descriptions of the MNT_FORCE and MNT_UPDATE flags were reworked
and moved to separate paragraphs.
Okay to commit?
--
WBR,
Vadim Zhukov
Index: mount.2
===
RCS file: /cvs/src/lib/libc/sys/mount.2,v
retrieving revision 1.46
diff -u -p -r1.46 mount.2
--- mount.2 27 May 2016 19:45:04 - 1.46
+++ mount.2 17 Jul 2016 22:13:06 -
@@ -70,31 +70,41 @@ at the time
of a successful mount are swept under the carpet, so to speak, and
are unavailable until the filesystem is unmounted.
.Pp
+The
+.Fn unmount
+function disassociates the filesystem from the specified
+mount point
+.Fa dir .
+.Pp
The following
.Fa flags
-may be specified to
-suppress default semantics which affect filesystem access.
+may be specified to change default behaviour:
.Bl -tag -width MNT_SYNCHRONOUS
-.It Dv MNT_RDONLY
-The filesystem should be treated as read-only:
-even the superuser may not write to it.
+.It Dv MNT_ASYNC
+All I/O to the filesystem should be done asynchronously.
.It Dv MNT_NOATIME
Do not update the access time on files in the filesystem unless
the modification or status change times are also being updated.
+.It Dv MNT_NODEV
+Do not interpret special files on the filesystem.
.It Dv MNT_NOEXEC
Do not allow files to be executed from the filesystem.
.It Dv MNT_NOSUID
Do not honor setuid or setgid bits on files when executing them.
-.It Dv MNT_NODEV
-Do not interpret special files on the filesystem.
-.It Dv MNT_SYNCHRONOUS
-All I/O to the filesystem should be done synchronously.
-.It Dv MNT_ASYNC
-All I/O to the filesystem should be done asynchronously.
+.It Dv MNT_RDONLY
+The filesystem should be treated as read-only:
+even the superuser may not write to it.
+.It Dv MNT_RELOAD
+Reload a MNT_RDONLY filesystem.
+Used, for example, by
+.Xr fsck 8
+after modification of on-disk structures.
.It Dv MNT_SOFTDEP
Use soft dependencies.
Applies to FFS filesystems only (see 'softdep' in
.Xr mount 8 ) .
+.It Dv MNT_SYNCHRONOUS
+All I/O to the filesystem should be done synchronously.
.It MNT_WXALLOWED
Processes that ask for memory to be made writeable plus executable
using the
@@ -108,10 +118,13 @@ The option is typically used on the
filesystem.
.El
.Pp
-The flag
+Two more flags affect the behaviour of system calls themselves,
+and not the behaviour of the corresponding filesystem:
+.Pp
+The
.Dv MNT_UPDATE
-indicates that the mount command is being applied
-to an already mounted filesystem.
+flag indicates that the mount command is being applied to an already
+mounted filesystem.
This allows the mount flags to be changed without requiring
that the filesystem be unmounted and remounted.
Some filesystems may not allow all flags to be changed.
@@ -119,6 +132,18 @@ For example,
most filesystems will not allow a change from read-write to read-only.
.Pp
The
+.Dv MNT_FORCE
+flag, if used together with
+.Dv MNT_UPDATE ,
+allows transition from read-write to read-only,
+even if there are files open for writing.
+And when used on unmount, it specifies that the filesystem
+should be forcibly unmounted even if files are still active;
+active special devices continue to work,
+but any further access to any other active files result in errors,
+even if the filesystem is later remounted.
+.Pp
+The
.Fa type
argument defines the type of the filesystem.
The types of filesystems known to the system are defined in
@@ -237,22 +262,6 @@ struct udf_args {
char*fspec; /* block special device to mount */
};
.Ed
-.Pp
-The
-.Fn unmount
-function call disassociates the filesystem from the specified
-mount point
-.Fa dir .
-.Pp
-The
-.Fa flags
-argument may specify
-.Dv MNT_FORCE
-to specify that the filesystem should be forcibly unmounted even if files are
-still active.
-Active special devices continue to work,
-but any further accesses to any other active files result in errors
-even if the filesystem is later remounted.
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
Re: Better for mount(2)
On Sat, Jul 09, 2016 at 06:20:49PM +0300, Vadim Zhukov wrote:
> Hello all.
>
evening.
> As found by some of my students, mount(2) lacks description of some
> flags used by userland. After trying to sync things out, I realized
> that this page is not well organized at all. For example, unmount
> syscall is mentioned closer to end, after description of flags that
> it could use.
>
> I didn't document all of the flags involved in mount calls, since
> some of them are purely kernel internal. But I could easily miss
> something crucial...
>
> So this is my first public draft of mount(2) patch. Looking for
> comments & thanks in advance!
>
> --
> WBR,
> Vadim Zhukov
>
comments inline.
>
> Index: mount.2
> ===
> RCS file: /cvs/src/lib/libc/sys/mount.2,v
> retrieving revision 1.46
> diff -u -p -r1.46 mount.2
> --- mount.2 27 May 2016 19:45:04 - 1.46
> +++ mount.2 9 Jul 2016 15:16:29 -
> @@ -70,31 +70,57 @@ at the time
> of a successful mount are swept under the carpet, so to speak, and
> are unavailable until the filesystem is unmounted.
> .Pp
> +The
> +.Fn unmount
> +function call disassociates the filesystem from the specified
> +mount point
> +.Fa dir .
> +.Pp
i agree this is an improvement.
> The following
> .Fa flags
> may be specified to
> suppress default semantics which affect filesystem access.
note the sentence above. it makes adding some of these options tricky
since it will essentially contradict what is written there. so, assuming
there is a reason to document these other flags (that is, no reason not
to), you will have to change that sentence.
> .Bl -tag -width MNT_SYNCHRONOUS
> -.It Dv MNT_RDONLY
> -The filesystem should be treated as read-only:
> -even the superuser may not write to it.
> +.It Dv MNT_ASYNC
> +All I/O to the filesystem should be done asynchronously.
ordering these alphabetically seems reasonable - i assume there's no
reason for the current order?
> +.It Dv MNT_FORCE
> +On unmount, specifies that the filesystem should be forcibly unmounted
> +even if files are still active.
> +Active special devices continue to work,
> +but any further accesses to any other active files result in errors
s/accesses/access/
> +even if the filesystem is later remounted.
> +On update, allows to forcibly change from read-write to read-only,
s/allows to forcibly change/forcibly changes/
> +even if there are files open for writing.
> .It Dv MNT_NOATIME
> Do not update the access time on files in the filesystem unless
> the modification or status change times are also being updated.
> +.It Dv MNT_NODEV
> +Do not interpret special files on the filesystem.
> .It Dv MNT_NOEXEC
> Do not allow files to be executed from the filesystem.
> .It Dv MNT_NOSUID
> Do not honor setuid or setgid bits on files when executing them.
> -.It Dv MNT_NODEV
> -Do not interpret special files on the filesystem.
> -.It Dv MNT_SYNCHRONOUS
> -All I/O to the filesystem should be done synchronously.
> -.It Dv MNT_ASYNC
> -All I/O to the filesystem should be done asynchronously.
> +.It Dv MNT_RDONLY
> +The filesystem should be treated as read-only:
> +even the superuser may not write to it.
> +.It Dv MNT_RELOAD
> +Reload already mounted filesystem.
i think "reload" is a bit ambiguous. what does it actually do?
> +Used, e.g., by
i'd change the e.g. to "for example". or at least kill the comma after
the "g."
> +.Xr fsck 8 .
> .It Dv MNT_SOFTDEP
> Use soft dependencies.
> Applies to FFS filesystems only (see 'softdep' in
> .Xr mount 8 ) .
> +.It Dv MNT_SYNCHRONOUS
> +All I/O to the filesystem should be done synchronously.
> +.It Dv MNT_UPDATE
> +Indicates that the mount command is being applied to an already mounted
> +filesystem.
> +This allows the mount flags to be changed without requiring
> +that the filesystem be unmounted and remounted.
> +Some filesystems may not allow all flags to be changed.
> +For example,
> +most filesystems will not allow a change from read-write to read-only.
> .It MNT_WXALLOWED
> Processes that ask for memory to be made writeable plus executable
> using the
> @@ -108,16 +134,6 @@ The option is typically used on the
> filesystem.
> .El
> .Pp
> -The flag
> -.Dv MNT_UPDATE
> -indicates that the mount command is being applied
> -to an already mounted filesystem.
> -This allows the mount flags to be changed without requiring
> -that the filesystem be unmounted and remounted.
> -Some filesystems may not allow all flags to be changed.
> -For example,
> -most filesystems will not allow a change from read-write to read-only.
> -.Pp
i'm less sure here. i think this option makes sense outwith the option
list. but i guess if you change the first sentence, it might work. not
convinced, though.
> The
> .Fa type
> argument defines the type of the filesystem.
> @@ -237,22 +253,6 @@ struct udf_args {
> char*fspec; /* block special device to mount */
> };
> .Ed
> -.Pp
> -The
> -.Fn
Better for mount(2)
Hello all.
As found by some of my students, mount(2) lacks description of some
flags used by userland. After trying to sync things out, I realized
that this page is not well organized at all. For example, unmount
syscall is mentioned closer to end, after description of flags that
it could use.
I didn't document all of the flags involved in mount calls, since
some of them are purely kernel internal. But I could easily miss
something crucial...
So this is my first public draft of mount(2) patch. Looking for
comments & thanks in advance!
--
WBR,
Vadim Zhukov
Index: mount.2
===
RCS file: /cvs/src/lib/libc/sys/mount.2,v
retrieving revision 1.46
diff -u -p -r1.46 mount.2
--- mount.2 27 May 2016 19:45:04 - 1.46
+++ mount.2 9 Jul 2016 15:16:29 -
@@ -70,31 +70,57 @@ at the time
of a successful mount are swept under the carpet, so to speak, and
are unavailable until the filesystem is unmounted.
.Pp
+The
+.Fn unmount
+function call disassociates the filesystem from the specified
+mount point
+.Fa dir .
+.Pp
The following
.Fa flags
may be specified to
suppress default semantics which affect filesystem access.
.Bl -tag -width MNT_SYNCHRONOUS
-.It Dv MNT_RDONLY
-The filesystem should be treated as read-only:
-even the superuser may not write to it.
+.It Dv MNT_ASYNC
+All I/O to the filesystem should be done asynchronously.
+.It Dv MNT_FORCE
+On unmount, specifies that the filesystem should be forcibly unmounted
+even if files are still active.
+Active special devices continue to work,
+but any further accesses to any other active files result in errors
+even if the filesystem is later remounted.
+On update, allows to forcibly change from read-write to read-only,
+even if there are files open for writing.
.It Dv MNT_NOATIME
Do not update the access time on files in the filesystem unless
the modification or status change times are also being updated.
+.It Dv MNT_NODEV
+Do not interpret special files on the filesystem.
.It Dv MNT_NOEXEC
Do not allow files to be executed from the filesystem.
.It Dv MNT_NOSUID
Do not honor setuid or setgid bits on files when executing them.
-.It Dv MNT_NODEV
-Do not interpret special files on the filesystem.
-.It Dv MNT_SYNCHRONOUS
-All I/O to the filesystem should be done synchronously.
-.It Dv MNT_ASYNC
-All I/O to the filesystem should be done asynchronously.
+.It Dv MNT_RDONLY
+The filesystem should be treated as read-only:
+even the superuser may not write to it.
+.It Dv MNT_RELOAD
+Reload already mounted filesystem.
+Used, e.g., by
+.Xr fsck 8 .
.It Dv MNT_SOFTDEP
Use soft dependencies.
Applies to FFS filesystems only (see 'softdep' in
.Xr mount 8 ) .
+.It Dv MNT_SYNCHRONOUS
+All I/O to the filesystem should be done synchronously.
+.It Dv MNT_UPDATE
+Indicates that the mount command is being applied to an already mounted
+filesystem.
+This allows the mount flags to be changed without requiring
+that the filesystem be unmounted and remounted.
+Some filesystems may not allow all flags to be changed.
+For example,
+most filesystems will not allow a change from read-write to read-only.
.It MNT_WXALLOWED
Processes that ask for memory to be made writeable plus executable
using the
@@ -108,16 +134,6 @@ The option is typically used on the
filesystem.
.El
.Pp
-The flag
-.Dv MNT_UPDATE
-indicates that the mount command is being applied
-to an already mounted filesystem.
-This allows the mount flags to be changed without requiring
-that the filesystem be unmounted and remounted.
-Some filesystems may not allow all flags to be changed.
-For example,
-most filesystems will not allow a change from read-write to read-only.
-.Pp
The
.Fa type
argument defines the type of the filesystem.
@@ -237,22 +253,6 @@ struct udf_args {
char*fspec; /* block special device to mount */
};
.Ed
-.Pp
-The
-.Fn unmount
-function call disassociates the filesystem from the specified
-mount point
-.Fa dir .
-.Pp
-The
-.Fa flags
-argument may specify
-.Dv MNT_FORCE
-to specify that the filesystem should be forcibly unmounted even if files are
-still active.
-Active special devices continue to work,
-but any further accesses to any other active files result in errors
-even if the filesystem is later remounted.
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
