[PATCH v2] Documentation: sysrq: Rewrite /proc/sysrq-trigger usage

[PATCH v2] Documentation: sysrq: Rewrite /proc/sysrq-trigger usage

[Bagas Sanjaya]

/proc/sysrq-trigger usage documentation (in "On all" section) states
that it is not recommended to write extra characters to it to avoid
undefined behavior, which is contradictive to previous sentence that
such characters are ignored. Also, in order to actually process them
(as a string), prepending it with underscore is required.

Rewrite the description.

Link: https://lore.kernel.org/lkml/7ca05672-dc20-413f-a923-f77ce0a9d307@anselmschueler.com/
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
Changes since v1 [1]:

  - Rewrite the whole "On all" section (Jon, Randy)

[1]: https://lore.kernel.org/linux-doc/20251008112409.33622-1-bagasdotme@gmail.com/

 Documentation/admin-guide/sysrq.rst | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst
index 9c7aa817adc72d..6157d93e03a1e2 100644
--- a/Documentation/admin-guide/sysrq.rst
+++ b/Documentation/admin-guide/sysrq.rst
@@ -75,16 +75,13 @@ On other
 	submit a patch to be included in this section.
 
 On all
-	Write a single character to /proc/sysrq-trigger.
-	Only the first character is processed, the rest of the string is
-	ignored. However, it is not recommended to write any extra characters
-	as the behavior is undefined and might change in the future versions.
-	E.g.::
+	Write a single character to /proc/sysrq-trigger. E.g.::
 
 		echo t > /proc/sysrq-trigger
 
-	Alternatively, write multiple characters prepended by underscore.
-	This way, all characters will be processed. E.g.::
+	If a string (multiple characters) is written instead, only the
+	first character is processed unless the string is prepended by
+	an underscore, like::
 
 		echo _reisub > /proc/sysrq-trigger
 

base-commit: a1af37b935c73049c54cb1412cf0850212af420e
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH v2] Documentation: sysrq: Rewrite /proc/sysrq-trigger usage

[Randy Dunlap]

Hi,

On 10/16/25 3:36 AM, Bagas Sanjaya wrote:
> /proc/sysrq-trigger usage documentation (in "On all" section) states
> that it is not recommended to write extra characters to it to avoid
> undefined behavior, which is contradictive to previous sentence that
> such characters are ignored. Also, in order to actually process them
> (as a string), prepending it with underscore is required.
> 
> Rewrite the description.
> 
> Link: https://lore.kernel.org/lkml/7ca05672-dc20-413f-a923-f77ce0a9d307@anselmschueler.com/
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
> Changes since v1 [1]:
> 
>   - Rewrite the whole "On all" section (Jon, Randy)
> 
> [1]: https://lore.kernel.org/linux-doc/20251008112409.33622-1-bagasdotme@gmail.com/
> 
>  Documentation/admin-guide/sysrq.rst | 11 ++++-------
>  1 file changed, 4 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst
> index 9c7aa817adc72d..6157d93e03a1e2 100644
> --- a/Documentation/admin-guide/sysrq.rst
> +++ b/Documentation/admin-guide/sysrq.rst
> @@ -75,16 +75,13 @@ On other
>  	submit a patch to be included in this section.
>  
>  On all
> -	Write a single character to /proc/sysrq-trigger.
> -	Only the first character is processed, the rest of the string is
> -	ignored. However, it is not recommended to write any extra characters
> -	as the behavior is undefined and might change in the future versions.
> -	E.g.::

I didn't quite follow Tomas's objection to the patch.
However, if we need to keep most of the paragraph above, I think
that it should at least say something like:

	In this mode, only the first character is processed; the rest of the string
	is silently ignored. To write multiple characters, see the
	alternative mode below.


At any rate, this patch LGTM.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

Or there is yet another alternative wording below.

> +	Write a single character to /proc/sysrq-trigger. E.g.::
>  
>  		echo t > /proc/sysrq-trigger
>  
> -	Alternatively, write multiple characters prepended by underscore.
> -	This way, all characters will be processed. E.g.::
> +	If a string (multiple characters) is written instead, only the
> +	first character is processed unless the string is prepended by
> +	an underscore, like::
>  
>  		echo _reisub > /proc/sysrq-trigger
>  
> 
> base-commit: a1af37b935c73049c54cb1412cf0e850212af420e


Alternative rewrite:

On all
	To write a single character to /proc/sysrq-trigger::

		echo command_key > /proc/sysrq-trigger

	E.g::
		echo t > /proc/sysrq-trigger

	Only the first character is processed; any following characters
	are silently ignored.
	However, it is not recommended to write any extra characters
	as the behavior is undefined and might change in the future versions.

	Alternatively, to write multiple characters to /proc/sysrq-trigger,
	prepend then with an underscore.
	This way, all characters will be processed. E.g.::

		echo _reisub > /proc/sysrq-trigger


I am still OK with removing the 2 "However" lines. We don't typically
document or provide warnings for how the code might be changed in the
future. If someone modifies this code and the documentation needs to be
updated, it should be updated at that time.

-- 
~Randy

Re: [PATCH v2] Documentation: sysrq: Rewrite /proc/sysrq-trigger usage

[Tomáš Mudruňka]

> I am still OK with removing the 2 "However" lines. We don't typically
> document or provide warnings for how the code might be changed in the
> future. If someone modifies this code and the documentation needs to be
> updated, it should be updated at that time.
>
> --
> ~Randy

Problem here is, that you cannot really modify the code without warning
users in advance. This is the warning.

Re: [PATCH v2] Documentation: sysrq: Rewrite /proc/sysrq-trigger usage

[Randy Dunlap]

On 10/20/25 4:50 AM, Tomáš Mudruňka wrote:
>> I am still OK with removing the 2 "However" lines. We don't typically
>> document or provide warnings for how the code might be changed in the
>> future. If someone modifies this code and the documentation needs to be
>> updated, it should be updated at that time.
>>
>> --
>> ~Randy
> 
> Problem here is, that you cannot really modify the code without warning
> users in advance. This is the warning.

All code in the kernel is subject to change in the future (anything
that breaks userspace less so than other code).
I don't see thousands of warnings about such future changes.

-- 
~Randy

Re: [PATCH v2] Documentation: sysrq: Rewrite /proc/sysrq-trigger usage

[Tomáš Mudruňka]

In that case, can we use some short form? Something like
"extra characters are ignored for now, which might change in future".

Thing is that i wanted to add handling of extra characters, but
maintainer said it cannot be done because people might currently rely
on characters being ignored as written in documentation.

Re: [PATCH v2] Documentation: sysrq: Rewrite /proc/sysrq-trigger usage

[Randy Dunlap]

On 10/21/25 1:37 AM, Tomáš Mudruňka wrote:
> In that case, can we use some short form? Something like
> "extra characters are ignored for now, which might change in future".
> 
> Thing is that i wanted to add handling of extra characters, but
> maintainer said it cannot be done because people might currently rely
> on characters being ignored as written in documentation.

Sure, OK with me.
Thanks.

-- 
~Randy

Re: [PATCH v2] Documentation: sysrq: Rewrite /proc/sysrq-trigger usage

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 582 bytes --]

On Tue, Oct 21, 2025 at 10:04:59AM -0700, Randy Dunlap wrote:
> 
> 
> On 10/21/25 1:37 AM, Tomáš Mudruňka wrote:
> > In that case, can we use some short form? Something like
> > "extra characters are ignored for now, which might change in future".
> > 
> > Thing is that i wanted to add handling of extra characters, but
> > maintainer said it cannot be done because people might currently rely
> > on characters being ignored as written in documentation.
> 
> Sure, OK with me.

No problem on my side.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]