Hello Günther!

On Thu, May 01, 2025 at 09:33:52PM +0200, Günther Noack wrote:

quoted

quoted

@@ -118,11 +130,11 @@ If mouse reporting is not enabled for the terminal,
 this operation yields an
 .B EINVAL
 error.
-.RE
 .IP
-Since Linux 6.7, using this subcode requires the
+Since Linux 6.12.26, using this selection mode requires the
 .B CAP_SYS_ADMIN
 capability.

I'm not sure I understand this part.  Was it required since 6.7 and now
it's only since 6.12.26?  How can that be?

Legitimate question.  For the TIOCL_SELMOUSEREPORT selection mode, the
requirement was briefly lifted (but in a confusing way due to an
implementation mistake).

The way that the diff came out is slightly misleading.  Note that the
.RE "moved", which really means that this text is now talking about
the TIOCL_SELMOUSEREPORT selection mode instead of the TIOCL_SETSEL
subcode - so we are now documenting the more fine-grained selection
modes instead of the more coarse grained TIOCL_SETSEL subcode.

For the selection modes, we had three cases:

 1. The selection modes which continue to require CAP_SYS_ADMIN.
    For these this is true before and after these kernel patches,
    so this is "required since Linux 6.7", as before.

 2. The selection modes which do not require CAP_SYS_ADMIN any more.
    For these, I dropped the remark.
    
 3. The TIOCL_SELMOUSEREPORT selection mode.  For this one, we had an
    unfortunate back-and-forth for when CAP_SYS_ADMIN is required:

    - It used to not be required.
    - It was required in 6.7+
    - After 2f83e38a095f, which aimed to loosen the requirement, it
      was *sometimes required* (unintentional and really too confusing
      to describe in a man page, IMHO)
    - After ee6a44da3c87 (coming up in Linux 6.12.26), it requires
      CAP_SYS_ADMIN again.

Hmmmm.

So for TIOCL_SELMOUSEREPORT, I am now saying it is required since
6.12.26 (an upcoming stable kernel).

Makes sense.  However, 6.12.26 is a branch, and we would need to clarify
what's the state in 6.{13,14,15}, don't we?

 But we can as well change it to
say "since 6.7" if that sounds better to you.  Maybe that would be
simpler and err on the safe side for users of the API.  (To be fair,
these interfaces are anyway only used by gpm and consolation. I am
mostly documenting it for completeness.)

Do you have a preference how to word this?  Should we say "since Linux
6.7" instead?

I don't have a preference.  Maybe since Linux 6.7 is easier than saying
since Linux 6.12.26, 6.13.x, 6.14.y, and 6.15.z.

Thanks for the review!
–Günther

You're welcome!  :)


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>