Re: [PATCH 3/3] tools/xenstore: add documentation for extended watch command

[Juergen Gross <jgross@xxxxxxxx>]

On 16.03.22 19:16, Luca Fancellu wrote:
> > On 16 Mar 2022, at 16:10, Juergen Gross <jgross@xxxxxxxx> wrote:
> >
> > Add documentation for an extension of the WATCH command used to limit
> > the scope of watched paths. Additionally it enables to receive more
> > information in the events related to special watches (@introduceDomain
> > or @releaseDomain).
> >
> > Signed-off-by: Juergen Gross <jgross@xxxxxxxx>
> > ---
> > docs/misc/xenstore-ring.txt |  1 +
> > docs/misc/xenstore.txt      | 16 +++++++++++++---
> > 2 files changed, 14 insertions(+), 3 deletions(-)
> >
> > diff --git a/docs/misc/xenstore-ring.txt b/docs/misc/xenstore-ring.txt
> > index 0cb72a3e35..eaa6d0a1a3 100644
> > --- a/docs/misc/xenstore-ring.txt
> > +++ b/docs/misc/xenstore-ring.txt
> > @@ -70,6 +70,7 @@ Mask    Description
> > 2       Connection error indicator (see connection error feature below)
> > 4       GET_FEATURE and SET_FEATURE Xenstore wire commands are available
> > 8       GET_QUOTA and SET_QUOTA Xenstore wire commands are available
> > +16      WATCH can take a third parameter limiting its scope
> >
> > The "Connection state" field is used to request a ring close and reconnect.
> > The "Connection state" field only contains valid data if the server has
> > diff --git a/docs/misc/xenstore.txt b/docs/misc/xenstore.txt
> > index dd75a81328..f86c6d9757 100644
> > --- a/docs/misc/xenstore.txt
> > +++ b/docs/misc/xenstore.txt
> > @@ -188,7 +188,7 @@ SET_PERMS           <path>|<perm-as-string>|+?
> >
> > ---------- Watches ----------
> >
> > -WATCH                  <wpath>|<token>|?
> > +WATCH                  <wpath>|<token>|[<depth>|]?
> >         Adds a watch.
> >
> >         When a <path> is modified (including path creation, removal,
> > @@ -199,7 +199,11 @@ WATCH                      <wpath>|<token>|?
> >         matching watch results in a WATCH_EVENT message (see below).
> >
> >         The event's path matches the watch's <wpath> if it is an child
> > -       of <wpath>.
> > +       of <wpath>. This match can be limited by specifying <depth> (a
> > +       decimal value of 0 or larger): it denotes the directory levels
> > +       below <wpath> to consider for a match ("0" would not match for
> > +       a child of <wpath>, "1" would match only for a direct child,
> > +       etc.).
> >
> >         <wpath> can be a <path> to watch or @<wspecial>.  In the
> >         latter case <wspecial> may have any syntax but it matches
> > @@ -210,7 +214,13 @@ WATCH                      <wpath>|<token>|?
> >                                 shutdown, and also on RELEASE
> >                                 and domain destruction
> >         <wspecial> events are sent to privileged callers or explicitly
> > -       via SET_PERMS enabled domains only.
> > +       via SET_PERMS enabled domains only. The semantics for a
> > +       specification of <depth> differ for generating <wspecial>
> Typo: s/differ/differs/?
I think "semantics" is a plural word, but I've found some references
that it is often used with a singular verb. It seems both variants are
in use.

> I’m not an English native speaker so apologies if there is no mistake.
Me neither. Any advice from a native English speaker?


Juergen

Attachment: OpenPGP_0xB0DE9DD628BF132F.asc
Description: OpenPGP public key

Attachment: OpenPGP_signature
Description: OpenPGP digital signature