TIOCLINUX.2const: Document TIOCL_SETSEL selection modes
cover TIOCLINUX.2const: Document TIOCL_SETSEL selection modes
Hi!
For context:
TIOCLINUX's TIOCL_SETSEL sub-code has another layer of sub-operations, called "selection modes" (even though not all of them actually deal with the mouse selection).
Going forward, the CAP_SYS_ADMIN requirement will be different for some of these selection modes, which promted me to at least list the different selection modes with a short description. I am leaving CAP_SYS_ADMIN documentation as it is for now and will send another patch once these semantics are finalized [1].
Thanks,
–Günther
[1] https://lore.kernel.org/all/[email protected]/
Günther Noack (1):
TIOCLINUX.2const: Document TIOCL_SETSEL selection modes
man/man2const/TIOCLINUX.2const | 48 ++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 5 deletions(-)
Signature · 1 line
2.48.1
PATCH 1/1 TIOCLINUX.2const: Document TIOCL_SETSEL selection modes
These previously undocumented selection modes for the Linux console are implemented in drivers/tty/vt/selection.c.
--- man/man2const/TIOCLINUX.2const | 48 ++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 5 deletions(-)
man/man2const/TIOCLINUX.2const +43 -5
@@ -65,11 +65,49 @@ are the ending column and row. (Upper left corner is row=column=1.) .I sel_mode -is 0 for character-by-character selection, -1 for word-by-word selection, -or 2 for line-by-line selection. -The indicated screen characters are highlighted and saved -in a kernel buffer. +may be one of the following operations: +.RS +.TP +.B TIOCL_SELCHAR +Select character-by-character. +The indicated screen characters are highlighted +and saved in a kernel buffer. +.TP +.B TIOCL_SELWORD +Select word-by-word. +The indicated screen characters are highlighted +and saved in a kernel buffer. +.TP +.B TIOCL_SELLINE +Select line-by-line. +The indicated screen characters are highlighted +and saved in a kernel buffer. +.TP +.B TIOCL_SELPOINTER +Show the pointer at position +.RI ( xe ", " ye ). +.TP +.B TIOCL_SELCLEAR +Remove the current selection highlight, if any, +from the console holding the selection. +.TP +.B TIOCL_SELMOUSEREPORT +Report +.RI ( xs ", " ys ) +as the current mouse location. +In this selection mode, +the lower 4 bits of +.I sel_mode +.RB ( TIOCL_SELBUTTONMASK ) +may additionally be set to indicate the desired button press and +modifier key information for the mouse event. +.\" https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Normal-tracking-mode +.IP +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 .B CAP_SYS_ADMIN
Signature · 1 line
2.48.1
Quoted 38 lines · Günther Noack
These previously undocumented selection modes for the Linux console are implemented in
drivers/tty/vt/selection.c.Cc Jared Finder <[email protected]>Cc Hanno Böck <[email protected]>Cc Jann Horn <[email protected]>Cc Jiri Slaby <[email protected]>Signed-off-by Günther Noack <[email protected]>--- man/man2const/TIOCLINUX.2const | 48 ++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 5 deletions(-)man/man2const/TIOCLINUX.2const +12
-5@@ -65,11 +65,49 @@ are the ending column and row. (Upper left corner is row=column=1.) .I sel_mode -is 0 for character-by-character selection, -1 for word-by-word selection, -or 2 for line-by-line selection. -The indicated screen characters are highlighted and saved -in a kernel buffer. +may be one of the following operations: +.RS +.TP +.B TIOCL_SELCHAR +Select character-by-character. +The indicated screen characters are highlighted +and saved in a kernel buffer. +.TP +.B TIOCL_SELWORD +Select word-by-word. +The indicated screen characters are highlighted +and saved in a kernel buffer.
man/man2const/TIOCLINUX.2const are the ending · line 89
Quoted 10 lines
man/man2const/TIOCLINUX.2const +10
-0+.TP +.B TIOCL_SELLINE +Select line-by-line. +The indicated screen characters are highlighted +and saved in a kernel buffer. +.TP +.B TIOCL_SELPOINTER +Show the pointer at position +.RI ( xe ", " ye ). +.TP
Wouldn't it be appropriate to call out here that this specific code is not intended to be protected by CAP_SYS_ADMIN?
man/man2const/TIOCLINUX.2const are the ending · line 93
Quoted 4 lines
man/man2const/TIOCLINUX.2const +4
-0+.B TIOCL_SELCLEAR +Remove the current selection highlight, if any, +from the console holding the selection. +.TP
And this one too?
Quoted 13 lines
man/man2const/TIOCLINUX.2const +11
-0+.B TIOCL_SELMOUSEREPORT +Report +.RI ( xs ", " ys ) +as the current mouse location. +In this selection mode, +the lower 4 bits of +.I sel_mode +.RB ( TIOCL_SELBUTTONMASK ) +may additionally be set to indicate the desired button press and +modifier key information for the mouse event. +.\"https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Normal-tracking-mode
+.IP
man/man2const/TIOCLINUX.2const are the ending · line 113
Quoted 8 lines
man/man2const/TIOCLINUX.2const +5
-0+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 .B CAP_SYS_ADMIN
-- MJF
Hi!
Thanks for the review!
Quoted 32 lines · Jared Finder
Quoted 31 lines · Günther Noack
man/man2const/TIOCLINUX.2const +17
-5@@ -65,11 +65,49 @@ are the ending column and row. (Upper left corner is row=column=1.) .I sel_mode -is 0 for character-by-character selection, -1 for word-by-word selection, -or 2 for line-by-line selection. -The indicated screen characters are highlighted and saved -in a kernel buffer. +may be one of the following operations: +.RS +.TP +.B TIOCL_SELCHAR +Select character-by-character. +The indicated screen characters are highlighted +and saved in a kernel buffer. +.TP +.B TIOCL_SELWORD +Select word-by-word. +The indicated screen characters are highlighted +and saved in a kernel buffer. +.TP +.B TIOCL_SELLINE +Select line-by-line. +The indicated screen characters are highlighted +and saved in a kernel buffer.
Quoted 8 lines
man/man2const/TIOCLINUX.2const are the ending · line 89
Quoted 5 lines
man/man2const/TIOCLINUX.2const +5
-0+.TP +.B TIOCL_SELPOINTER +Show the pointer at position +.RI ( xe ", " ye ). +.TPWouldn't it be appropriate to call out here that this specific code is not intended to be protected by
CAP_SYS_ADMIN?
Yes, it would, and that's the intention and what this change is preparing for. This commit describes the "selection modes" (without touching on the CAP_SYS_ADMIN topic) and a follow-up commit should move the CAP_SYS_ADMIN remark into the sections for the individual selection modes.
I intentionally postponed the CAP_SYS_ADMIN part of the change until the time when the semantics are finalized in the kernel, because I did not want to risk calling the slightly broken intermediate logic to anyone's attention (where TIOCL_SELMOUSEREPORT requires CAP_SYS_ADMIN, but only as long as one of the lower four bits of the sel_mode are set) - that behavior was unintentional and I don't want to promote that further than necessary. ;-)
So yes, I'll send another small patch once we have a fix on the kernel side which is merged.
–Günther
Alejandro Colomar
maintainerHi!
Quoted 33 lines · Günther Noack
These previously undocumented selection modes for the Linux console are implemented in
drivers/tty/vt/selection.c.Cc Jared Finder <[email protected]>Cc Hanno Böck <[email protected]>Cc Jann Horn <[email protected]>Cc Jiri Slaby <[email protected]>Signed-off-by Günther Noack <[email protected]>--- man/man2const/TIOCLINUX.2const | 48 ++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 5 deletions(-)man/man2const/TIOCLINUX.2const +7
-5@@ -65,11 +65,49 @@ are the ending column and row. (Upper left corner is row=column=1.) .I sel_mode -is 0 for character-by-character selection, -1 for word-by-word selection, -or 2 for line-by-line selection. -The indicated screen characters are highlighted and saved -in a kernel buffer. +may be one of the following operations: +.RS +.TP +.B TIOCL_SELCHAR +Select character-by-character. +The indicated screen characters are highlighted +and saved in a kernel buffer.
man/man2const/TIOCLINUX.2const are the ending · line 84
Quoted 10 lines
man/man2const/TIOCLINUX.2const +10
-0+.TP +.B TIOCL_SELWORD +Select word-by-word. +The indicated screen characters are highlighted +and saved in a kernel buffer. +.TP +.B TIOCL_SELLINE +Select line-by-line. +The indicated screen characters are highlighted +and saved in a kernel buffer.
It might be interesting to split this into two patches:
1) A first one that fixes existing wording, line breaks, etc, and gives names to the values 0,1,2.
2) And a second one that adds new documentation.
man/man2const/TIOCLINUX.2const are the ending · line 88
Quoted 4 lines
man/man2const/TIOCLINUX.2const +4
-0+.TP +.B TIOCL_SELPOINTER +Show the pointer at position +.RI ( xe ", " ye ).
I'd use a non-breaking space \~, which also has the benefit of not needing quotes:
.RI ( xe ,\~ ye ).
man/man2const/TIOCLINUX.2const are the ending · line 96
Quoted 8 lines
man/man2const/TIOCLINUX.2const +8
-0+.TP +.B TIOCL_SELCLEAR +Remove the current selection highlight, if any, +from the console holding the selection. +.TP +.B TIOCL_SELMOUSEREPORT +Report +.RI ( xs ", " ys )
.
man/man2const/TIOCLINUX.2const are the ending · line 104
Quoted 8 lines
man/man2const/TIOCLINUX.2const +8
-0+as the current mouse location. +In this selection mode, +the lower 4 bits of +.I sel_mode +.RB ( TIOCL_SELBUTTONMASK ) +may additionally be set to indicate the desired button press and +modifier key information for the mouse event. +.\" https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Normal-tracking-mode
Please always enclose URIs in <>. (See uri(7).)
man/man2const/TIOCLINUX.2const are the ending · line 110
Quoted 6 lines
man/man2const/TIOCLINUX.2const +6
-0+.IP +If mouse reporting is not enabled for the terminal, +this operation yields an +.B EINVAL +error. +.RE
Have a lovely night!
Alex
Quoted 6 lines
man/man2const/TIOCLINUX.2const +0
-0.IP Since Linux 6.7, using this subcode requires the .B CAP_SYS_ADMINSignature · 1 line
2.48.1
Signature · 1 line
<https://www.alejandro-colomar.es/>