man/man2const/TIOCLINUX.2const: Document CAP_SYS_ADMIN requirement for TIOCL_SETSEL modes

PATCH Superseded Günther Noack 2 participants 5 messages May 1, 2025 – May 2, 2025 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Günther Noack

author

2025-05-01 11:01 UTC #0 lore raw

PATCH 1/1 man/man2const/TIOCLINUX.2const: Document CAP_SYS_ADMIN requirement for TIOCL_SETSEL modes

CAP_SYS_ADMIN was previously required for the entire TIOCL_SETSEL subcode, but is now only needed for a subset of the selection modes, since linux.git 2f83e38a095f ("tty: Permit some TIOCL_SETSEL modes without CAP_SYS_ADMIN").

The CAP_SYS_ADMIN requirement for TIOCL_SELMOUSEREPORT was further corrected in linux.git ee6a44da3c87 ("tty: Require CAP_SYS_ADMIN for all usages of TIOCL_SELMOUSEREPORT").

Link <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit?id=2f83e38a095f8bf7c6029883d894668b03b9bd93>

Link <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit?id=ee6a44da3c87cf64d67dd02be8c0127a5bf56175>

Signed-off-by Günther Noack <[email protected]>

---
 man/man2const/TIOCLINUX.2const | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

man/man2const/TIOCLINUX.2const +14 -2

index 61f1c596d..f48132ea1 100644
@@ -72,18 +72,30 @@ may be one of the following operations:
 Select character-by-character.
 The indicated screen characters are highlighted
 and saved in a kernel buffer.
+.IP
+Since Linux 6.7, using this selection mode requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .B TIOCL_SELWORD
 Select word-by-word,
 expanding the selection outwards to align with word boundaries.
 The indicated screen characters are highlighted
 and saved in a kernel buffer.
+.IP
+Since Linux 6.7, using this selection mode requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .B TIOCL_SELLINE
 Select line-by-line,
 expanding the selection outwards to select full lines.
 The indicated screen characters are highlighted
 and saved in a kernel buffer.
+.IP
+Since Linux 6.7, using this selection mode requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .B TIOCL_SELPOINTER
 Show the pointer at position

@@ -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.
+.RE
 .TP
 .BR subcode = TIOCL_PASTESEL
 Paste selection.

Signature · 1 line

2.49.0

Alejandro Colomar

maintainer

2025-05-01 15:05 UTC #1 lore raw

Hi Günther,

Quoted 8 lines · Günther Noack

CAP_SYS_ADMIN was previously required for the entire TIOCL_SETSEL subcode, but is now only needed for a subset of the selection modes, since linux.git 2f83e38a095f ("tty: Permit some TIOCL_SETSEL modes without CAP_SYS_ADMIN").
The CAP_SYS_ADMIN requirement for TIOCL_SELMOUSEREPORT was further corrected in linux.git ee6a44da3c87 ("tty: Require CAP_SYS_ADMIN for all usages of TIOCL_SELMOUSEREPORT").

In these commit references, it would be interesting to include the commit date (when there are more than one, to get an idea of the chronology). This git alias might be useful for you to produce these references:

	$ grep -A1 '\<ref\>' /etc/gitconfig 
		ref = show --no-patch --abbrev=12 --date=short \
			--format=tformat:'%C(auto)%h%C(reset) %C(white)(%cd%x3B \"%C(reset)%C(auto)%s%C(reset)%C(white)\")%C(reset)'
	$ git ref 2f83e38a095f ee6a44da3c87
	2f83e38a095f (2025-01-13; "tty: Permit some TIOCL_SETSEL modes without CAP_SYS_ADMIN")
	ee6a44da3c87 (2025-04-11; "tty: Require CAP_SYS_ADMIN for all usages of TIOCL_SELMOUSEREPORT")

Quoted 44 lines

Link <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit?id=2f83e38a095f8bf7c6029883d894668b03b9bd93>

Link <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit?id=ee6a44da3c87cf64d67dd02be8c0127a5bf56175>

Signed-off-by Günther Noack <[email protected]>

---
 man/man2const/TIOCLINUX.2const | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

man/man2const/TIOCLINUX.2const +12 -0

index 61f1c596d..f48132ea1 100644
@@ -72,18 +72,30 @@ may be one of the following operations:
 Select character-by-character.
 The indicated screen characters are highlighted
 and saved in a kernel buffer.
+.IP
+Since Linux 6.7, using this selection mode requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .B TIOCL_SELWORD
 Select word-by-word,
 expanding the selection outwards to align with word boundaries.
 The indicated screen characters are highlighted
 and saved in a kernel buffer.
+.IP
+Since Linux 6.7, using this selection mode requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .B TIOCL_SELLINE
 Select line-by-line,
 expanding the selection outwards to select full lines.
 The indicated screen characters are highlighted
 and saved in a kernel buffer.
+.IP
+Since Linux 6.7, using this selection mode requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .B TIOCL_SELPOINTER
 Show the pointer at position

man/man2const/TIOCLINUX.2const If mouse reporting is not enabled for the terminal, · line 136

Quoted 9 lines

man/man2const/TIOCLINUX.2const +1 -2

@@ -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?

Have a lovely day!
Alex

Quoted 7 lines

man/man2const/TIOCLINUX.2const +1 -0
+.RE
 .TP
 .BR subcode = TIOCL_PASTESEL
 Paste selection.
Signature · 1 line
2.49.0

Signature · 1 line

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

Günther Noack

author

2025-05-01 19:34 UTC #2 lore raw

Hello Alejandro!

Quoted 15 lines · Alejandro Colomar

Quoted 8 lines · Günther Noack
CAP_SYS_ADMIN was previously required for the entire TIOCL_SETSEL subcode, but is now only needed for a subset of the selection modes, since linux.git 2f83e38a095f ("tty: Permit some TIOCL_SETSEL modes without CAP_SYS_ADMIN").
The CAP_SYS_ADMIN requirement for TIOCL_SELMOUSEREPORT was further corrected in linux.git ee6a44da3c87 ("tty: Require CAP_SYS_ADMIN for all usages of TIOCL_SELMOUSEREPORT").
In these commit references, it would be interesting to include the commit date (when there are more than one, to get an idea of the chronology). This git alias might be useful for you to produce these references:

Quoted 6 lines

	$ grep -A1 '\<ref\>' /etc/gitconfig 
		ref = show --no-patch --abbrev=12 --date=short \
			--format=tformat:'%C(auto)%h%C(reset) %C(white)(%cd%x3B \"%C(reset)%C(auto)%s%C(reset)%C(white)\")%C(reset)'
	$ git ref 2f83e38a095f ee6a44da3c87
	2f83e38a095f (2025-01-13; "tty: Permit some TIOCL_SETSEL modes without CAP_SYS_ADMIN")
	ee6a44da3c87 (2025-04-11; "tty: Require CAP_SYS_ADMIN for all usages of TIOCL_SELMOUSEREPORT")

Thanks, that's a useful alias.

Quoted 47 lines

Link <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit?id=2f83e38a095f8bf7c6029883d894668b03b9bd93>

Link <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit?id=ee6a44da3c87cf64d67dd02be8c0127a5bf56175>

Signed-off-by Günther Noack <[email protected]>

---
 man/man2const/TIOCLINUX.2const | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

man/man2const/TIOCLINUX.2const +12 -1

index 61f1c596d..f48132ea1 100644
@@ -72,18 +72,30 @@ may be one of the following operations:
 Select character-by-character.
 The indicated screen characters are highlighted
 and saved in a kernel buffer.
+.IP
+Since Linux 6.7, using this selection mode requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .B TIOCL_SELWORD
 Select word-by-word,
 expanding the selection outwards to align with word boundaries.
 The indicated screen characters are highlighted
 and saved in a kernel buffer.
+.IP
+Since Linux 6.7, using this selection mode requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .B TIOCL_SELLINE
 Select line-by-line,
 expanding the selection outwards to select full lines.
 The indicated screen characters are highlighted
 and saved in a kernel buffer.
+.IP
+Since Linux 6.7, using this selection mode requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .B TIOCL_SELPOINTER
 Show the pointer at position

@@ -118,11 +130,11 @@ If mouse reporting is not enabled for the terminal,
 this operation yields an
 .B EINVAL
 error.
-.RE

Quoted 8 lines

man/man2const/TIOCLINUX.2const If mouse reporting is not enabled for the terminal, · line 136
Quoted 5 lines
man/man2const/TIOCLINUX.2const +1 -1
 .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.

So for TIOCL_SELMOUSEREPORT, I am now saying it is required since 6.12.26 (an upcoming stable kernel). 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?

There are more details in the commit message of ee6a44da3c87 (2025-04-11; "tty: Require CAP_SYS_ADMIN for all usages of TIOCL_SELMOUSEREPORT"), and in the related mail threads.

Quoted 1 line

man/man2const/TIOCLINUX.2const If mouse reporting is not enabled for the terminal, · line 137
Quoted 1 line
man/man2const/TIOCLINUX.2const +1 -0
+.RE

^^^^
The diff looks like I moved .RE,
but I really moved the remark into a different indentation level.

Quoted 5 lines

Quoted 5 lines
man/man2const/TIOCLINUX.2const +0 -0
 .TP
 .BR subcode = TIOCL_PASTESEL
 Paste selection.
Signature · 1 line
2.49.0

Thanks for the review!
–Günther

Alejandro Colomar

maintainer

2025-05-01 20:19 UTC #3 lore raw

Hello Günther!

Quoted 36 lines · Günther Noack

Quoted 5 lines
Quoted 5 lines
man/man2const/TIOCLINUX.2const +0 -1
@@ -118,11 +130,11 @@ If mouse reporting is not enabled for the terminal,
 this operation yields an
 .B EINVAL
 error.
-.RE
Quoted 8 lines
man/man2const/TIOCLINUX.2const If mouse reporting is not enabled for the terminal, · line 136
Quoted 5 lines
man/man2const/TIOCLINUX.2const +1 -1
 .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:

Quoted 7 lines

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

Quoted 2 lines

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?

Quoted 8 lines

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.

Quoted 2 lines

Thanks for the review!
–Günther

You're welcome! :)

Have a lovely night!
Alex

Signature · 1 line

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

Günther Noack

author

2025-05-02 10:17 UTC #4 lore raw

Hello Alejandro!

Quoted 45 lines · Alejandro Colomar

Quoted 36 lines · Günther Noack
Quoted 5 lines
Quoted 5 lines
man/man2const/TIOCLINUX.2const +0 -1
@@ -118,11 +130,11 @@ If mouse reporting is not enabled for the terminal,
 this operation yields an
 .B EINVAL
 error.
-.RE
Quoted 8 lines
man/man2const/TIOCLINUX.2const If mouse reporting is not enabled for the terminal, · line 136
Quoted 5 lines
man/man2const/TIOCLINUX.2const +1 -1
 .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:
Quoted 7 lines
- 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.

Quoted 7 lines

Hmmmm.
Quoted 2 lines
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

Quoted 11 lines

Quoted 8 lines
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