Re: CVS commit: src/usr.bin/chflags

[Greg Troxel <gdt%lexort.com@localhost>]

Taylor R Campbell <campbell+netbsd-source-changes-d%mumble.net@localhost> writes:

> jschauma@'s change did help clarify (1) and (2).  Let's try to work
> together to make it better?

Well said.


I can shed a little light on some of the questions.

> 1. What is `arch' or `archived' supposed to mean?  Who sets it, who
>    pays attention to it, and what consequences does it have?  Is it
>    obsolete?  What was it used for?  From the current text, I have no
>    idea!

From reading sources, I think it is exactly "the archive bit is set in
the foreign filesystem entry that this vnode is representting" and that
it is basically an MS-DOS thing that is likely not important (even to
people that do not dismiss all things Windows!) any more.

> 2. What is `nodump' supposed to mean?  Who sets it, who pays attention
>    to it, and what consequences does it have?  Does the kernel do
>    anything about it, or is it just an extra bit of storage that
>    programs like dump(8) can choose to examine?  From the current
>    text, I have no idea!

I believe it is just a bit that other programs can query, and that the
intent is that dump(8) will decline to dump files with the bit set.

(I intend, in my Copious Spare Time, to extend pkgsrc/sysutils/bup to
respect this flag.  I have previously made extensive use of nodump with
dump.  Partly because of lack of the bit in bup and partly for
organizational sanity, I use /u0 and /n0 for things that should and
should not be backed up.  But that's me in case it helps motivate why
nodump is useful, not about flag docs.)

I believe that nodump continues to be relevant today.

> 3. What is the difference between `system' and `user' immutable or
>    append-only?  If I set uchg, does that mean the _owner_ can't
>    modify the file, or that _nobody_ can modify the file?

Not useful for a 1 man page, but

  egrep '[SU]F_' /usr/include/sys/stat.h

is illuminating to programmers.

I believe, but would have to read the code to be 100% sure, that

  only root can modify schg and sappnd flags (and archive)

  either root or the owner can modify other flags (except on
  device files, on which only root may modify flags, for reasons that
  are unclear, but the rationale seems unimportant)

  etiher schg or uchg means the file can't be modified, probably, but
  it's possible that uchg applies to everybody but root and schg applies
  to everybody.  A quick experiment shows that root cannot write to a
  gdt-owned file with the uchg bit set.

Fundamentally there are 16 flag bits for user and 16 for system and I
think it is baked in hard that only root can modify the system set.

> jschauma@'s change did help clarify (1) and (2).  Let's try to work
> together to make it better?

The fundamental issue is that the table attempts to

  - map the tokens used by chflags(1) (good)

  - to names that sort of represent the flags (which are fundamentally C
    preprocessor token) but are a third namespace that exists only here
    (bad)

  - describe the flags permissions as if they are individual, instead of
    simly saying that schg and sappend may be changed by superuser
    only (confusing)

  - does not give semantics (ok, because that is not consistent with a
    table)

Also, the man page does not explain that because "nodump" is the name of
a flag, one does "chflags dump foo" to remove the nodump flag.

(I don't think it needs explanation that the design decision is that
nodump is a flag, instead of dump, because the norms are that files tend
not to have any flags set and that all files should be backed up.)



I would recommend:

  Noting that archive flag represents something in some foreign
  filesystems, currently known to exist only for some MSDOS filesystems,
  and that the specific filesystem should document that.

  Explaining that the nodump flag is a request that backup programs omit
  the file from backups and to see dump(8).

  Be clearer about permissions.

  Drop the restatement of tokens into a third only-here namespace.
  Instead, use paragraphs following to describe that each token means.