[PATCH v2] xenstore: document xs_set_permissions

[PATCH v2] xenstore: document xs_set_permissions

[Wei Liu]

Signed-off-by: Wei Liu <wei.liu2@citrix.com>
Cc: Ian Campbell <ian.campbell@citrix.com>
Cc: Ian Jackson <ian.jackson@eu.citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>
---
Change in v2: say explicitly owner has read and write permission
---
 tools/xenstore/include/xenstore.h | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/tools/xenstore/include/xenstore.h b/tools/xenstore/include/xenstore.h
index b4b113e..43ee93f 100644
--- a/tools/xenstore/include/xenstore.h
+++ b/tools/xenstore/include/xenstore.h
@@ -149,8 +149,31 @@ struct xs_permissions *xs_get_permissions(struct xs_handle *h,
 					  xs_transaction_t t,
 					  const char *path, unsigned int *num);
 
-/* Set permissions of node (must be owner).
- * Returns false on failure.
+/* Set permissions of node (must be owner).  Returns false on failure.
+ *
+ * Domain 0 may read / write anywhere in the store, regardless of
+ * permission settings.
+ *
+ * Note:
+ * The perms array is a list of (domid, permissions) pairs. The first
+ * element in the list specifies the owner of the list, plus the flags
+ * for every domain not explicitly specified subsequently. The
+ * subsequent entries are normal capabilities.
+ *
+ * Example C code:
+ *
+ *  struct xs_permissions perms[2];
+ *
+ *  perms[0].id = dm_domid;
+ *  perms[0].perms = XS_PERM_NONE;
+ *  perms[1].id = guest_domid;
+ *  perms[1].perms = XS_PERM_READ;
+ *
+ * It means the owner of the path is domain $dm_domid (hence it always
+ * has read and write permission), all other domains (unless specified
+ * in subsequent pair) can neither read from nor write to that
+ * path. It then specifies domain $guest_domid can read from that
+ * path.
  */
 bool xs_set_permissions(struct xs_handle *h, xs_transaction_t t,
 			const char *path, struct xs_permissions *perms,
-- 
1.9.1

Re: [PATCH v2] xenstore: document xs_set_permissions

[Ian Campbell]

On Tue, 2015-03-31 at 13:26 +0100, Wei Liu wrote:
> Signed-off-by: Wei Liu <wei.liu2@citrix.com>
> Cc: Ian Campbell <ian.campbell@citrix.com>
> Cc: Ian Jackson <ian.jackson@eu.citrix.com>
> Acked-by: Ian Campbell <ian.campbell@citrix.com>

Applied, thanks.