[src/trunk]: src/lib/libutil stat_flags(3): try to improve the descriptions

[uwe <uwe%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/aabbd2bcd2be
branches:  trunk
changeset: 376099:aabbd2bcd2be
user:      uwe <uwe%NetBSD.org@localhost>
date:      Wed May 31 21:49:39 2023 +0000

description:
stat_flags(3): try to improve the descriptions

List all alternative forms recognized by string_to_flags(3).
Both "dump" and "nonodump" are the negative of "nodump".
string_to_flags does not recognize "snap".
Provide xrefs for flag descriptions where applicable.

diffstat:

 lib/libutil/stat_flags.3 |  100 ++++++++++++++++++++++++++++++++++------------
 1 files changed, 73 insertions(+), 27 deletions(-)

diffs (158 lines):

diff -r 2571713ace1b -r aabbd2bcd2be lib/libutil/stat_flags.3
--- a/lib/libutil/stat_flags.3  Wed May 31 21:02:50 2023 +0000
+++ b/lib/libutil/stat_flags.3  Wed May 31 21:49:39 2023 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: stat_flags.3,v 1.8 2012/09/19 23:22:56 wiz Exp $
+.\" $NetBSD: stat_flags.3,v 1.9 2023/05/31 21:49:39 uwe Exp $
 .\"
 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd September 20, 2012
+.Dd May 31, 2023
 .Dt STAT_FLAGS 3
 .Os
 .Sh NAME
@@ -49,36 +49,59 @@ and
 .Fn string_to_flags
 functions are used by
 programs such as
+.Xr chflags 1 ,
 .Xr ls 1 ,
-.Xr mtree 8 ,
 .Xr makefs 8 ,
+.Xr mtree 8 ,
 etc., to parse and/or print the
-.Dv st_flags field in the
+.Fa st_flags
+field in the
 .Xr stat 2
 structure.
+.
 .Pp
 They recognize the following flags:
-.Bl -column -offset indent "uappnd " "SF_IMMUTABLE" "xxx"
-.It Sy String Ta Sy Flag Ta Sy Description
-.It Va arch Ta Dv SF_ARCHIVED Ta file is archived
-.It Va nodump Ta Dv UF_NODUMP Ta do not dump file
-.It Va opaque Ta Dv UF_OPAQUE Ta directory is opaque in union filesystems
-.It Va sappnd Ta Dv SF_APPEND Ta writes to the file may only append
-.It Va schg Ta Dv SF_IMMUTABLE Ta file cannot be changed; it is immutable
-.It Va snap Ta Dv SF_SNAPSHOT Ta file is a snapshot inode
-.It Va uappnd Ta Dv UF_APPEND Ta writes to the file may only append
-.It Va uchg Ta Dv UF_IMMUTABLE Ta file cannot be changed; it is immutable
+.
+.Bl -tag -width Cm -offset indent
+.
+.It Cm arch , Cm archived Pq Dv SF_ARCHIVED
+file is archived
+.Po legacy/compat flag for
+.Xr mount_msdos 8
+filesystems
+.Pc
+.
+.It Cm nodump Pq Dv UF_NODUMP
+do not
+.Xr dump 8
+file
+.
+.It Cm opaque Pq Dv UF_OPAQUE
+directory is opaque in
+.Xr mount_union 8
+filesystems
+.
+.It Cm sappnd , Cm sappend Pq Dv SF_APPEND
+writes to the file may only append
+.Pq flag can be changed by the superuser only
+.
+.It Cm schg , Cm schange , Cm simmutable Pq Dv SF_IMMUTABLE
+file cannot be changed; it is immutable
+.Pq flag can be changed by the superuser only
+.
+.It Cm snap Pq Dv SF_SNAPSHOT
+file is an
+.Xr fss 4
+snapshot inode
+.
+.It Cm uappnd , Cm uappend Pq Dv UF_APPEND
+writes to the file may only append
+.
+.It Cm uchg , Cm uchange , Cm uimmutable Pq Dv UF_IMMUTABLE
+file cannot be changed; it is immutable
+.
 .El
-.Pp
-The
-.Dv SF_APPEND
-and
-.Dv SF_IMMUTABLE
-flags are for the superuser only, whereas
-.Dv UF_APPEND
-and
-.Dv UF_IMMUTABLE
-are for the user only.
+.
 .Pp
 The
 .Fn flags_to_string
@@ -94,6 +117,10 @@ and it is the responsibility of the call
 .Xr free 3
 it.
 .Pp
+Where the above list has several flag names for a flag,
+the first of the listed names is returned.
+.
+.Pp
 The
 .Fn string_to_flags
 function takes a
@@ -102,16 +129,35 @@ of space, comma, or tab separated flag n
 and places their bit value on the
 .Fa setp
 argument.
-If the flag name is prefixed by:
-.Dq no ,
+.Pp
+If the flag name is prefixed by
+.Ql no ,
 then the bit value is placed on the
 .Fa clrp
 argument.
+Both
+.Cm nonodump
+and
+.Cm dump
+are recognized as negative forms of the
+.Cm nodump
+flag name.
+.Pp
+Where the above list has several flag names for a flag,
+all of them are recognized.
+The
+.Cm snap
+flag name is
+.Em not
+recognized
+.Pq as its flag cannot be changed anyway .
+.
 .Sh RETURN VALUES
 .Fn flags_to_string
 returns the symbolic representation of flags, the default string, or
 .Dv NULL
 if allocation failed.
+.
 .Pp
 .Fn string_to_flags
 returns
@@ -120,7 +166,7 @@ on success and
 .Dv 1
 if it fails to parse the string, setting
 .Fa stringp
-to point to the first string that it failed to parse.
+to point to the first name that it failed to parse.
 .Sh SEE ALSO
 .Xr chflags 2 ,
 .Xr stat 2