git: d289382897e7 - main - rights.4: various corrections on capability rights

The branch main has been updated by imp:

URL: https://cgit.FreeBSD.org/src/commit/?id=d289382897e7ded566a3aa10ae535235149c4056

commit d289382897e7ded566a3aa10ae535235149c4056
Author:     CismonX <admin@cismon.net>
AuthorDate: 2024-04-29 04:48:26 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
CommitDate: 2024-04-29 04:48:31 +0000

    rights.4: various corrections on capability rights
    
    - A file descriptor obtained from accept(2), accept4(2) and openat(2)
      is not always assigned all capability rights.  Instead, it inherits
      capability rights from the "parent" socket/dir file descriptor.
    - getdents(2) and getdirentries(2) requires CAP_READ.
    - openat(2) with O_WRONLY|O_TRUNC does not require CAP_SEEK.
    
    Reviewed by: imp
    Pull Request: https://github.com/freebsd/freebsd-src/pull/1207
---
 lib/libsys/cap_rights_limit.2 | 12 +++++++-----
 share/man/man4/rights.4       | 21 +++++++++++++++------
 2 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/lib/libsys/cap_rights_limit.2 b/lib/libsys/cap_rights_limit.2
index eca30f55ea48..8372d07f6a5c 100644
--- a/lib/libsys/cap_rights_limit.2
+++ b/lib/libsys/cap_rights_limit.2
@@ -30,7 +30,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd March 9, 2023
+.Dd April 27, 2024
 .Dt CAP_RIGHTS_LIMIT 2
 .Os
 .Sh NAME
@@ -44,20 +44,22 @@
 .Fn cap_rights_limit "int fd" "const cap_rights_t *rights"
 .Sh DESCRIPTION
 When a file descriptor is created by a function such as
-.Xr accept 2 ,
-.Xr accept4 2 ,
 .Xr fhopen 2 ,
 .Xr kqueue 2 ,
 .Xr mq_open 2 ,
 .Xr open 2 ,
-.Xr openat 2 ,
 .Xr pdfork 2 ,
 .Xr pipe 2 ,
 .Xr shm_open 2 ,
 .Xr socket 2
 or
 .Xr socketpair 2 ,
-it is assigned all capability rights.
+it is assigned all capability rights; for
+.Xr accept 2 ,
+.Xr accept4 2
+or
+.Xr openat 2 ,
+it inherits capability rights from the "parent" file descriptor.
 Those rights can be reduced (but never expanded) by using the
 .Fn cap_rights_limit
 system call.
diff --git a/share/man/man4/rights.4 b/share/man/man4/rights.4
index 2d44a1060006..3e5e18fc65d8 100644
--- a/share/man/man4/rights.4
+++ b/share/man/man4/rights.4
@@ -30,7 +30,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd March 22, 2024
+.Dd April 27, 2024
 .Dt RIGHTS 4
 .Os
 .Sh NAME
@@ -38,20 +38,22 @@
 .Nd Capsicum capability rights for file descriptors
 .Sh DESCRIPTION
 When a file descriptor is created by a function such as
-.Xr accept 2 ,
-.Xr accept4 2 ,
 .Xr fhopen 2 ,
 .Xr kqueue 2 ,
 .Xr mq_open 2 ,
 .Xr open 2 ,
-.Xr openat 2 ,
 .Xr pdfork 2 ,
 .Xr pipe 2 ,
 .Xr shm_open 2 ,
 .Xr socket 2
 or
 .Xr socketpair 2 ,
-it is assigned all capability rights.
+it is assigned all capability rights; for
+.Xr accept 2 ,
+.Xr accept4 2
+or
+.Xr openat 2 ,
+it inherits capability rights from the "parent" file descriptor.
 Those rights can be reduced (but never expanded) by using the
 .Xr cap_rights_limit 2 ,
 .Xr cap_fcntls_limit 2 and
@@ -501,7 +503,10 @@ with the
 is also required),
 .Xr preadv 2
 .Dv ( CAP_SEEK
-is also required) and related system calls.
+is also required),
+.Xr getdents 2 ,
+.Xr getdirentries 2 ,
+and related system calls.
 .It Dv CAP_RECV
 An alias to
 .Dv CAP_READ .
@@ -611,6 +616,8 @@ with the
 .Dv O_WRONLY
 flag, but without the
 .Dv O_APPEND
+or
+.Dv O_TRUNC
 flag,
 .Dv CAP_SEEK
 is also required.
@@ -657,6 +664,8 @@ is also required.
 .Xr fsync 2 ,
 .Xr ftruncate 2 ,
 .Xr futimes 2 ,
+.Xr getdents 2 ,
+.Xr getdirentries 2 ,
 .Xr getpeername 2 ,
 .Xr getsockname 2 ,
 .Xr getsockopt 2 ,