Re: [PATCH] man/man2const/TIOCLINUX.2const: Document CAP_SYS_ADMIN requirement for TIOCL_SETSEL modes

["Günther Noack" <gnoack3000@gmail.com>]

Hello Alejandro!

On Thu, May 01, 2025 at 10:19:01PM +0200, Alejandro Colomar wrote:
> On Thu, May 01, 2025 at 09:33:52PM +0200, Günther Noack wrote:
> > > > @@ -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?

Both patches are applied to all up-to-date versions of stable kernels.

6.7 to 6.11  (EOL) have none of the two patches:
             CAP_SYS_ADMIN is enforced broadly
6.12.26      (longterm) has both
6.13.12      (EOL) has only the first patch
6.14.5       (stable) has both
6.15         (not released yet) will have both


> >  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.

Yes, I think so too.  I'll send a V2 that says "since Linux 6.7".  The
fact that we permitted some of these invocations without CAP_SYS_ADMIN
was a bug in hindsight and only a temporary state.

Thanks,
–Günther