[Xen-devel] [PATCH] docs/misc/xenstore.txt minor fixes

[Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>]

Steven Smith has pointed out a few minor errors and provided some more
information about the behaviour of old xenstoreds.  I've documented
the relevant facts, as I understand them, in the attached
documentation patch.

I'm going to follow this up with another patch about size limits for
xenstore messages.

Ian.

Signed-off-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>

diff -r 4553bc1087d9 docs/misc/xenstore.txt
--- a/docs/misc/xenstore.txt    Wed Dec 12 15:41:20 2007 +0000
+++ b/docs/misc/xenstore.txt    Wed Dec 12 16:13:55 2007 +0000
@@ -174,6 +174,17 @@ WATCH                      <wpath>|<token>|?
        away, with <path> equal to <wpath>.  Watches may be triggered
        spuriously.  The tx_id in a WATCH request is ignored.
 
+       Watches are supposed to be restricted by the permissions
+       system but in practice the implementation is imperfect.
+       Applications should not rely on being sent a notification for
+       paths that they cannot read; however, an application may rely
+       on being sent a watch when a path which it _is_ able to read
+       is deleted even if that leaves only a nonexistent unreadable
+       parent.  A notification may omitted if a node's permissions
+       are changed so as to make it unreadable, in which case future
+       notifications may be suppressed (and if the node is later made
+       readable, some notifications may have been lost).
+
 WATCH_EVENT                                    <epath>|<token>|
        Unsolicited `reply' generated for matching modfication events
        as described above.  req_id and tx_id are both 0.
@@ -182,7 +193,7 @@ WATCH_EVENT                                 <epath>|<token>|
        modifed; however if the event was the recursive removal of an
        parent of <wpath>, <epath> is just
        <wpath> (rather than the actual path which was removed).  So
-       <epath> is a child of <epath>, regardless.
+       <epath> is a child of <wpath>, regardless.
 
        Iff <wpath> for the watch was specified as a relative pathname,
        the <epath> path will also be relative (with the same base,
@@ -192,7 +203,7 @@ UNWATCH                     <wpath>|<token>|?
 
 ---------- Transactions ----------
 
-TRANSACTION_START      ??                      <transid>|
+TRANSACTION_START      |                       <transid>|
        <transid> is an opaque uint32_t allocated by xenstored
        represented as unsigned decimal.  After this, transaction may
        be referenced by using <transid> (as 32-bit binary) in the
@@ -202,11 +213,6 @@ TRANSACTION_START  ??                      <transid>|
        Currently xenstored has the bug that after 2^32 transactions
        it will allocate the transid 0 for an actual transaction.
 
-       Clients using the provided xs.c bindings will send a single
-       nul byte for the argument payload.  We recommend that future
-       clients continue to do the same; any future extension will not
-       use that syntax.
-
 TRANSACTION_END                T|
 TRANSACTION_END                F|
        tx_id must refer to existing transaction.  After this

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel