* [PATCH man 0/1] TIOCLINUX.2const: Document TIOCL_SETSEL selection modes @ 2025-02-23 9:13 Günther Noack 2025-02-23 9:13 ` [PATCH man 1/1] " Günther Noack 0 siblings, 1 reply; 5+ messages in thread From: Günther Noack @ 2025-02-23 9:13 UTC (permalink / raw) To: Alejandro Colomar Cc: linux-man, Jared Finder, Hanno Böck, Jann Horn, Jiri Slaby, jwilk, Günther Noack 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/20250221.0a947528d8f3@gnoack.org/ Günther Noack (1): TIOCLINUX.2const: Document TIOCL_SETSEL selection modes man/man2const/TIOCLINUX.2const | 48 ++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 5 deletions(-) -- 2.48.1 ^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH man 1/1] TIOCLINUX.2const: Document TIOCL_SETSEL selection modes 2025-02-23 9:13 [PATCH man 0/1] TIOCLINUX.2const: Document TIOCL_SETSEL selection modes Günther Noack @ 2025-02-23 9:13 ` Günther Noack 2025-02-23 16:35 ` Jared Finder 2025-02-23 19:36 ` Alejandro Colomar 0 siblings, 2 replies; 5+ messages in thread From: Günther Noack @ 2025-02-23 9:13 UTC (permalink / raw) To: Alejandro Colomar Cc: linux-man, Jared Finder, Hanno Böck, Jann Horn, Jiri Slaby, jwilk, Günther Noack These previously undocumented selection modes for the Linux console are implemented in drivers/tty/vt/selection.c. Cc: Jared Finder <jared@finder.org> Cc: Hanno Böck <hanno@hboeck.de> Cc: Jann Horn <jannh@google.com> Cc: Jiri Slaby <jirislaby@kernel.org> Cc: jwilk@jwilk.net Signed-off-by: Günther Noack <gnoack3000@gmail.com> --- man/man2const/TIOCLINUX.2const | 48 ++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 5 deletions(-) diff --git a/man/man2const/TIOCLINUX.2const b/man/man2const/TIOCLINUX.2const index c0acdd0ea..27758584e 100644 --- a/man/man2const/TIOCLINUX.2const +++ b/man/man2const/TIOCLINUX.2const @@ -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 -- 2.48.1 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH man 1/1] TIOCLINUX.2const: Document TIOCL_SETSEL selection modes 2025-02-23 9:13 ` [PATCH man 1/1] " Günther Noack @ 2025-02-23 16:35 ` Jared Finder 2025-02-23 19:15 ` Günther Noack 2025-02-23 19:36 ` Alejandro Colomar 1 sibling, 1 reply; 5+ messages in thread From: Jared Finder @ 2025-02-23 16:35 UTC (permalink / raw) To: Günther Noack Cc: Alejandro Colomar, linux-man, Hanno Böck, Jann Horn, Jiri Slaby, jwilk On 2025-02-23 01:13, Günther Noack wrote: > These previously undocumented selection modes for the Linux console > are implemented in drivers/tty/vt/selection.c. > > Cc: Jared Finder <jared@finder.org> > Cc: Hanno Böck <hanno@hboeck.de> > Cc: Jann Horn <jannh@google.com> > Cc: Jiri Slaby <jirislaby@kernel.org> > Cc: jwilk@jwilk.net > Signed-off-by: Günther Noack <gnoack3000@gmail.com> > --- > man/man2const/TIOCLINUX.2const | 48 ++++++++++++++++++++++++++++++---- > 1 file changed, 43 insertions(+), 5 deletions(-) > > diff --git a/man/man2const/TIOCLINUX.2const > b/man/man2const/TIOCLINUX.2const > index c0acdd0ea..27758584e 100644 > --- a/man/man2const/TIOCLINUX.2const > +++ b/man/man2const/TIOCLINUX.2const > @@ -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 Wouldn't it be appropriate to call out here that this specific code is not intended to be protected by CAP_SYS_ADMIN? > +.B TIOCL_SELCLEAR > +Remove the current selection highlight, if any, > +from the console holding the selection. > +.TP And this one too? > +.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 -- MJF ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH man 1/1] TIOCLINUX.2const: Document TIOCL_SETSEL selection modes 2025-02-23 16:35 ` Jared Finder @ 2025-02-23 19:15 ` Günther Noack 0 siblings, 0 replies; 5+ messages in thread From: Günther Noack @ 2025-02-23 19:15 UTC (permalink / raw) To: Jared Finder Cc: Alejandro Colomar, linux-man, Hanno Böck, Jann Horn, Jiri Slaby, jwilk Hi! Thanks for the review! On Sun, Feb 23, 2025 at 08:35:16AM -0800, Jared Finder wrote: > On 2025-02-23 01:13, Günther Noack wrote: > > diff --git a/man/man2const/TIOCLINUX.2const > > b/man/man2const/TIOCLINUX.2const > > index c0acdd0ea..27758584e 100644 > > --- a/man/man2const/TIOCLINUX.2const > > +++ b/man/man2const/TIOCLINUX.2const > > @@ -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 > > Wouldn'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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH man 1/1] TIOCLINUX.2const: Document TIOCL_SETSEL selection modes 2025-02-23 9:13 ` [PATCH man 1/1] " Günther Noack 2025-02-23 16:35 ` Jared Finder @ 2025-02-23 19:36 ` Alejandro Colomar 1 sibling, 0 replies; 5+ messages in thread From: Alejandro Colomar @ 2025-02-23 19:36 UTC (permalink / raw) To: Günther Noack Cc: Alejandro Colomar, linux-man, Jared Finder, Hanno Böck, Jann Horn, Jiri Slaby, jwilk [-- Attachment #1: Type: text/plain, Size: 2893 bytes --] Hi! On Sun, Feb 23, 2025 at 10:13:42AM +0100, Günther Noack wrote: > These previously undocumented selection modes for the Linux console > are implemented in drivers/tty/vt/selection.c. > > Cc: Jared Finder <jared@finder.org> > Cc: Hanno Böck <hanno@hboeck.de> > Cc: Jann Horn <jannh@google.com> > Cc: Jiri Slaby <jirislaby@kernel.org> > Cc: jwilk@jwilk.net > Signed-off-by: Günther Noack <gnoack3000@gmail.com> > --- > man/man2const/TIOCLINUX.2const | 48 ++++++++++++++++++++++++++++++---- > 1 file changed, 43 insertions(+), 5 deletions(-) > > diff --git a/man/man2const/TIOCLINUX.2const b/man/man2const/TIOCLINUX.2const > index c0acdd0ea..27758584e 100644 > --- a/man/man2const/TIOCLINUX.2const > +++ b/man/man2const/TIOCLINUX.2const > @@ -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. 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. > +.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 ). > +.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 Please always enclose URIs in <>. (See uri(7).) > +.IP > +If mouse reporting is not enabled for the terminal, > +this operation yields an > +.B EINVAL > +error. > +.RE Have a lovely night! Alex > .IP > Since Linux 6.7, using this subcode requires the > .B CAP_SYS_ADMIN > -- > 2.48.1 > -- <https://www.alejandro-colomar.es/> [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2025-02-23 19:36 UTC | newest] Thread overview: 5+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2025-02-23 9:13 [PATCH man 0/1] TIOCLINUX.2const: Document TIOCL_SETSEL selection modes Günther Noack 2025-02-23 9:13 ` [PATCH man 1/1] " Günther Noack 2025-02-23 16:35 ` Jared Finder 2025-02-23 19:15 ` Günther Noack 2025-02-23 19:36 ` Alejandro Colomar
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox