* Document the fact that non-superusers cannot change file flags for

  objects with SF_IMMUTABLE, SF_APPEND, or SF_NOUNLINK.
* Document that non-superusers cannot set or clear any SF_* flag
  (setting fails with EPERM, clearing is silently ignored).
* Document that superusers cannot change any flag if one of
  SF_IMMUTABLE, SF_APPEND, SF_NOUNLINK is set and securelevel is
  greater than 0.
* Document SF_SNAPSHOT and note that it is maintained by the
  system and is, for this reason, impossible to set to clear by
  any user.

PR:             docs/33877
Submitted by:   harti
Help by:        George Marsellis <gam9478@njit.edu>
MFC after:      1 week

1 files changed, 47 insertions, 2 deletions

diff --git a/lib/libc/sys/chflags.2 b/lib/libc/sys/chflags.2
index 0160878..3897d38 100644
--- a/lib/libc/sys/chflags.2
+++ b/lib/libc/sys/chflags.2
@@ -93,8 +93,21 @@ The file may not be changed.
 The file may only be appended to.
 .It SF_NOUNLINK
 The file may not be renamed or deleted.
+.It SF_SNAPSHOT
+The file is a snapshot file.
 .El
 .Pp
+If one of 
+.Dq SF_IMMUTABLE ,
+.Dq SF_APPEND ,
+or
+.Dq SF_NOUNLINK
+is set a non-super-user cannot change any flags and even the super-user
+can change flags only if securelevel is greater than 0.
+(See
+.Xr init 8
+for details.)
+.Pp
 The
 .Dq UF_IMMUTABLE ,
 .Dq UF_APPEND ,
@@ -111,13 +124,17 @@ The
 and
 .Dq SF_ARCHIVED
 flags may only be set or unset by the super-user.
-Attempts by the non-super-user to set the super-user only flags
-are silently ignored.
+Attempts to set these flags by non-super-users are rejected, attempts by
+non-superusers to clear flags that are already unset are silently ignored.
 These flags may be set at any time, but normally may only be unset when
 the system is in single-user mode.
 (See
 .Xr init 8
 for details.)
+.Pp
+The
+.Dq SF_SNAPSHOT
+flag is maintained by the system and cannot be changed by any user.
 .Sh RETURN VALUES
 .Rv -std
 .Sh ERRORS
@@ -139,6 +156,20 @@ Too many symbolic links were encountered in translating the pathname.
 .It Bq Er EPERM
 The effective user ID does not match the owner of the file and
 the effective user ID is not the super-user.
+.It Bq Er EPERM
+One of
+.Dq SF_IMMUTABLE ,
+.Dq SF_APPEND ,
+or
+.Dq SF_NOUNLINK
+is set and the user is either not the super-user or
+securelevel is greater than 0.
+.It Bq Er EPERM
+A non-super-user tries to set one of
+.Dq SF_IMMUTABLE ,
+.Dq SF_APPEND ,
+or
+.Dq SF_NOUNLINK .
 .It Bq Er EROFS
 The named file resides on a read-only file system.
 .It Bq Er EFAULT
@@ -168,6 +199,20 @@ refers to a socket, not to a file.
 .It Bq Er EPERM
 The effective user ID does not match the owner of the file and
 the effective user ID is not the super-user.
+.It Bq Er EPERM
+One of
+.Dq SF_IMMUTABLE ,
+.Dq SF_APPEND ,
+or
+.Dq SF_NOUNLINK
+is set and the user is either not the super-user or
+securelevel is greater than 0.
+.It Bq Er EPERM
+A non-super-user tries to set one of
+.Dq SF_IMMUTABLE ,
+.Dq SF_APPEND ,
+or
+.Dq SF_NOUNLINK .
 .It Bq Er EROFS
 The file resides on a read-only file system.
 .It Bq Er EIO