xenstore: Clarify xs_open() semantics

Added to the xs_open() comments in xenstore.h. The text has been
taken almost verbatim from a xen-devel email by Ian Campbell,
and confirmed as accurate by Ian Jackson.

Suggested-by: Ian Campbell <Ian.Campbell@citrix.com>
Signed-off-by: Razvan Cojocaru <rcojocaru@bitdefender.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

diff --git a/tools/xenstore/include/xenstore.h b/tools/xenstore/include/xenstore.h
index fdf5e764ba164aa190b37ad70e02b359e93dce46..b4b113edd8495d440fafaf147e8b1dd353ec72f5 100644 (file)
--- a/tools/xenstore/include/xenstore.h
+++ b/tools/xenstore/include/xenstore.h
@@ -59,10 +59,20 @@ typedef uint32_t xs_transaction_t;
 /* On failure, these routines set errno. */
 
 /* Open a connection to the xs daemon.
- * Attempts to make a connection over the socket interface, 
+ * Attempts to make a connection over the socket interface,
  * and if it fails, then over the  xenbus interface.
  * Mode 0 specifies read-write access, XS_OPEN_READONLY for
  * read-only access.
+ *
+ * * Connections made with xs_open(0) (which might be shared page or
+ *   socket based) are only guaranteed to work in the parent after
+ *   fork.
+ * * Connections made with xs_open(XS_OPEN_SOCKETONLY) will be usable
+ *   in either the parent or the child after fork, but not both.
+ * * xs_daemon_open*() and xs_domain_open() are deprecated synonyms
+ *   for xs_open(0).
+ * * XS_OPEN_READONLY has no bearing on any of this.
+ *
  * Returns a handle or NULL.
  */
 struct xs_handle *xs_open(unsigned long flags);