[PATCH] docs: filesystems: sysfs: Recommend sysfs_emit() for new code only

[PATCH] docs: filesystems: sysfs: Recommend sysfs_emit() for new code only

[Bart Van Assche]

The advantages of converting existing sysfs show() methods to sysfs_emit()
and sysfs_emit_at() do not outweigh the risk of introducing bugs. Hence
recommend sysfs_emit() and sysfs_emit_at() only for new implementations of
show() methods.

Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: James Bottomley <James.Bottomley@HansenPartnership.com>
Cc: Martin K. Petersen <martin.petersen@oracle.com>
Signed-off-by: Bart Van Assche <bvanassche@acm.org>
---
 Documentation/filesystems/sysfs.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/filesystems/sysfs.rst b/Documentation/filesystems/sysfs.rst
index c32993bc83c7..624e4f51212e 100644
--- a/Documentation/filesystems/sysfs.rst
+++ b/Documentation/filesystems/sysfs.rst
@@ -243,8 +243,8 @@ Other notes:
 - show() methods should return the number of bytes printed into the
   buffer.
 
-- show() should only use sysfs_emit() or sysfs_emit_at() when formatting
-  the value to be returned to user space.
+- New implementations of show() methods should only use sysfs_emit() or
+  sysfs_emit_at() when formatting the value to be returned to user space.
 
 - store() should return the number of bytes used from the buffer. If the
   entire buffer has been used, just return the count argument.

Re: [PATCH] docs: filesystems: sysfs: Recommend sysfs_emit() for new code only

[Greg Kroah-Hartman]

On Thu, Jul 24, 2025 at 08:34:42AM -0700, Bart Van Assche wrote:
> The advantages of converting existing sysfs show() methods to sysfs_emit()
> and sysfs_emit_at() do not outweigh the risk of introducing bugs. Hence
> recommend sysfs_emit() and sysfs_emit_at() only for new implementations of
> show() methods.
> 
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Cc: James Bottomley <James.Bottomley@HansenPartnership.com>
> Cc: Martin K. Petersen <martin.petersen@oracle.com>
> Signed-off-by: Bart Van Assche <bvanassche@acm.org>
> ---
>  Documentation/filesystems/sysfs.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

Re: [PATCH] docs: filesystems: sysfs: Recommend sysfs_emit() for new code only

[Martin K. Petersen]

Hi Bart!

> -- show() should only use sysfs_emit() or sysfs_emit_at() when
> formatting

With my standards hat on: That's a "should", not a "shall". But I guess
the "only" makes it sound slightly less optional.

> +- New implementations of show() methods should only use sysfs_emit() or
> +  sysfs_emit_at() when formatting the value to be returned to user
>    space.

Should we make this a "shall" for new implementations?

I'm fine either way.

Reviewed-by: Martin K. Petersen <martin.petersen@oracle.com>

-- 
Martin K. Petersen

Re: [PATCH] docs: filesystems: sysfs: Recommend sysfs_emit() for new code only

[Jonathan Corbet]

Bart Van Assche <bvanassche@acm.org> writes:

> The advantages of converting existing sysfs show() methods to sysfs_emit()
> and sysfs_emit_at() do not outweigh the risk of introducing bugs. Hence
> recommend sysfs_emit() and sysfs_emit_at() only for new implementations of
> show() methods.
>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Cc: James Bottomley <James.Bottomley@HansenPartnership.com>
> Cc: Martin K. Petersen <martin.petersen@oracle.com>
> Signed-off-by: Bart Van Assche <bvanassche@acm.org>
> ---
>  Documentation/filesystems/sysfs.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/filesystems/sysfs.rst b/Documentation/filesystems/sysfs.rst
> index c32993bc83c7..624e4f51212e 100644
> --- a/Documentation/filesystems/sysfs.rst
> +++ b/Documentation/filesystems/sysfs.rst
> @@ -243,8 +243,8 @@ Other notes:
>  - show() methods should return the number of bytes printed into the
>    buffer.
>  
> -- show() should only use sysfs_emit() or sysfs_emit_at() when formatting
> -  the value to be returned to user space.
> +- New implementations of show() methods should only use sysfs_emit() or
> +  sysfs_emit_at() when formatting the value to be returned to user space.
>  

Applied, thanks.

jon