Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
From:   Nicholas Mc Guire <hofrat@osadl.org>
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Nicholas Mc Guire <hofrat@osadl.org>
Subject: [PATCH RFC] sysfs.txt: add note on available attribute macros
Date:   Thu, 14 Feb 2019 12:21:50 +0100
Message-Id: <1550143310-17463-1-git-send-email-hofrat@osadl.org>
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

The common cases of attributes should probably be using the __ATTR_XXX
macros to make code more concise and readable but the current sysfs.txt
does not point developers to those convenience macros. Further there is
no note in sysfs.txt currently explaining why trying to set a sysfs file
to mode 0666 will fail.

Signed-off-by: Nicholas Mc Guire <hofrat@osadl.org>
---

Note quite sure if this is the right place to place the note on mode 0666 
but it should be somewhere as any attempt to set 0666 will be reverted 
to 0664.

 Documentation/filesystems/sysfs.txt | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt
index 41411b0..c246142 100644
--- a/Documentation/filesystems/sysfs.txt
+++ b/Documentation/filesystems/sysfs.txt
@@ -116,6 +116,22 @@ static struct device_attribute dev_attr_foo = {
 	.store = store_foo,
 };
 
+Note as stated in include/linux/kernel.h "OTHER_WRITABLE?  Generally
+considered a bad idea." so trying to set a sysfs file writable for
+everyone will fail reverting to mode 0664.
+
+For this common cases sysfs.h provides convenience macros to
+make defining attributes easier as well as making code more
+concise and readable. The above case could be shortened to:
+
+static struct device_attribute dev_attr_foo = __ATTR_RW(foo);
+
+the list of helpers available is:
+__ATTR_RO(name): same as above with mode 0444
+__ATTR_WO(name): same as above with mode 0200
+__ATTR_RO_MODE(name, mode): allowing to pass in a specific mode
+__ATTR_RW(name): setting mode to 0644
+__ATTR_NULL: which sets the name to NULL
 
 Subsystem-Specific Callbacks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.1.4