1 /* 2 Xen Store Daemon providing simple tree-like database. 3 Copyright (C) 2005 Rusty Russell IBM Corporation 4 5 This library is free software; you can redistribute it and/or 6 modify it under the terms of the GNU Lesser General Public 7 License as published by the Free Software Foundation; either 8 version 2.1 of the License, or (at your option) any later version. 9 10 This library is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Lesser General Public License for more details. 14 15 You should have received a copy of the GNU Lesser General Public 16 License along with this library; If not, see <http://www.gnu.org/licenses/>. 17 */ 18 19 #ifndef XENSTORE_H 20 #define XENSTORE_H 21 22 #include <xenstore_lib.h> 23 24 #define XBT_NULL 0 25 26 #define XS_OPEN_READONLY 1UL<<0 27 #define XS_OPEN_SOCKETONLY 1UL<<1 28 29 /* 30 * Setting XS_UNWATCH_FILTER arranges that after xs_unwatch, no 31 * related watch events will be delivered via xs_read_watch. But 32 * this relies on the couple token, subpath is unique. 33 * 34 * XS_UNWATCH_FILTER clear XS_UNWATCH_FILTER set 35 * 36 * Even after xs_unwatch, "stale" After xs_unwatch returns, no 37 * instances of the watch event watch events with the same 38 * may be delivered. token and with the same subpath 39 * will be delivered. 40 * 41 * A path and a subpath can be The application must avoid 42 * register with the same token. registering a path (/foo/) and 43 * a subpath (/foo/bar) with the 44 * same path until a successful 45 * xs_unwatch for the first watch 46 * has returned. 47 */ 48 #define XS_UNWATCH_FILTER 1UL<<2 49 50 struct xs_handle; 51 typedef uint32_t xs_transaction_t; 52 53 /* IMPORTANT: For details on xenstore protocol limits, see 54 * docs/misc/xenstore.txt in the Xen public source repository, and use the 55 * XENSTORE_*_MAX limit macros defined in xen/io/xs_wire.h. 56 */ 57 58 /* On failure, these routines set errno. */ 59 60 /* Open a connection to the xs daemon. 61 * Attempts to make a connection over the socket interface, 62 * and if it fails, then over the xenbus interface. 63 * Mode 0 specifies read-write access, XS_OPEN_READONLY for 64 * read-only access. 65 * 66 * * Connections made with xs_open(0) (which might be shared page or 67 * socket based) are only guaranteed to work in the parent after 68 * fork. 69 * * Connections made with xs_open(XS_OPEN_SOCKETONLY) will be usable 70 * in either the parent or the child after fork, but not both. 71 * * xs_daemon_open*() and xs_domain_open() are deprecated synonyms 72 * for xs_open(0). 73 * * XS_OPEN_READONLY has no bearing on any of this. 74 * 75 * Returns a handle or NULL. 76 */ 77 struct xs_handle *xs_open(unsigned long flags); 78 79 /* Close the connection to the xs daemon. */ 80 void xs_close(struct xs_handle *xsh); 81 82 /* Connect to the xs daemon. 83 * Returns a handle or NULL. 84 * Deprecated, please use xs_open(0) instead 85 */ 86 struct xs_handle *xs_daemon_open(void); 87 struct xs_handle *xs_domain_open(void); 88 89 /* Connect to the xs daemon (readonly for non-root clients). 90 * Returns a handle or NULL. 91 * Deprecated, please use xs_open(XS_OPEN_READONLY) instead 92 */ 93 struct xs_handle *xs_daemon_open_readonly(void); 94 95 /* Close the connection to the xs daemon. 96 * Deprecated, please use xs_close() instead 97 */ 98 void xs_daemon_close(struct xs_handle *); 99 100 /* Throw away the connection to the xs daemon, for use after fork(). */ 101 void xs_daemon_destroy_postfork(struct xs_handle *); 102 103 /* Get contents of a directory. 104 * Returns a malloced array: call free() on it after use. 105 * Num indicates size. 106 */ 107 char **xs_directory(struct xs_handle *h, xs_transaction_t t, 108 const char *path, unsigned int *num); 109 110 /* Get the value of a single file, nul terminated. 111 * Returns a malloced value: call free() on it after use. 112 * len indicates length in bytes, not including terminator. 113 */ 114 void *xs_read(struct xs_handle *h, xs_transaction_t t, 115 const char *path, unsigned int *len); 116 117 /* Write the value of a single file. 118 * Returns false on failure. 119 */ 120 bool xs_write(struct xs_handle *h, xs_transaction_t t, 121 const char *path, const void *data, unsigned int len); 122 123 /* Create a new directory. 124 * Returns false on failure, or success if it already exists. 125 */ 126 bool xs_mkdir(struct xs_handle *h, xs_transaction_t t, 127 const char *path); 128 129 /* Destroy a file or directory (and children). 130 * Returns false on failure, or if it doesn't exist. 131 */ 132 bool xs_rm(struct xs_handle *h, xs_transaction_t t, 133 const char *path); 134 135 /* Get permissions of node (first element is owner, first perms is "other"). 136 * Returns malloced array, or NULL: call free() after use. 137 */ 138 struct xs_permissions *xs_get_permissions(struct xs_handle *h, 139 xs_transaction_t t, 140 const char *path, unsigned int *num); 141 142 /* Set permissions of node (must be owner). Returns false on failure. 143 * 144 * Domain 0 may read / write anywhere in the store, regardless of 145 * permission settings. 146 * 147 * Note: 148 * The perms array is a list of (domid, permissions) pairs. The first 149 * element in the list specifies the owner of the list, plus the flags 150 * for every domain not explicitly specified subsequently. The 151 * subsequent entries are normal capabilities. 152 * 153 * Example C code: 154 * 155 * struct xs_permissions perms[2]; 156 * 157 * perms[0].id = dm_domid; 158 * perms[0].perms = XS_PERM_NONE; 159 * perms[1].id = guest_domid; 160 * perms[1].perms = XS_PERM_READ; 161 * 162 * It means the owner of the path is domain $dm_domid (hence it always 163 * has read and write permission), all other domains (unless specified 164 * in subsequent pair) can neither read from nor write to that 165 * path. It then specifies domain $guest_domid can read from that 166 * path. 167 */ 168 bool xs_set_permissions(struct xs_handle *h, xs_transaction_t t, 169 const char *path, struct xs_permissions *perms, 170 unsigned int num_perms); 171 172 /* Watch a node for changes (poll on fd to detect, or call read_watch()). 173 * When the node (or any child) changes, fd will become readable. 174 * Token is returned when watch is read, to allow matching. 175 * Returns false on failure. 176 */ 177 bool xs_watch(struct xs_handle *h, const char *path, const char *token); 178 179 /* Return the FD to poll on to see if a watch has fired. */ 180 int xs_fileno(struct xs_handle *h); 181 182 /* Check for node changes. On success, returns a non-NULL pointer ret 183 * such that ret[0] and ret[1] are valid C strings, namely the 184 * triggering path (see docs/misc/xenstore.txt) and the token (from 185 * xs_watch). On error return value is NULL setting errno. 186 * 187 * Callers should, after xs_fileno has become readable, repeatedly 188 * call xs_check_watch until it returns NULL and sets errno to EAGAIN. 189 * (If the fd became readable, xs_check_watch is allowed to make it no 190 * longer show up as readable even if future calls to xs_check_watch 191 * will return more watch events.) 192 * 193 * After the caller is finished with the returned information it 194 * should be freed all in one go with free(ret). 195 */ 196 char **xs_check_watch(struct xs_handle *h); 197 198 /* Find out what node change was on (will block if nothing pending). 199 * Returns array containing the path and token. Use XS_WATCH_* to access these 200 * elements. Call free() after use. 201 */ 202 char **xs_read_watch(struct xs_handle *h, unsigned int *num); 203 204 /* Remove a watch on a node: implicitly acks any outstanding watch. 205 * Returns false on failure (no watch on that node). 206 */ 207 bool xs_unwatch(struct xs_handle *h, const char *path, const char *token); 208 209 /* Start a transaction: changes by others will not be seen during this 210 * transaction, and changes will not be visible to others until end. 211 * Returns NULL on failure. 212 */ 213 xs_transaction_t xs_transaction_start(struct xs_handle *h); 214 215 /* End a transaction. 216 * If abandon is true, transaction is discarded instead of committed. 217 * Returns false on failure: if errno == EAGAIN, you have to restart 218 * transaction. 219 */ 220 bool xs_transaction_end(struct xs_handle *h, xs_transaction_t t, 221 bool abort); 222 223 /* Introduce a new domain. 224 * This tells the store daemon about a shared memory page, event channel and 225 * store path associated with a domain: the domain uses these to communicate. 226 */ 227 bool xs_introduce_domain(struct xs_handle *h, 228 unsigned int domid, 229 unsigned long mfn, 230 unsigned int eventchn); 231 232 /* Set the target of a domain 233 * This tells the store daemon that a domain is targetting another one, so 234 * it should let it tinker with it. 235 */ 236 bool xs_set_target(struct xs_handle *h, 237 unsigned int domid, 238 unsigned int target); 239 240 /* Resume a domain. 241 * Clear the shutdown flag for this domain in the store. 242 */ 243 bool xs_resume_domain(struct xs_handle *h, unsigned int domid); 244 245 /* Release a domain. 246 * Tells the store domain to release the memory page to the domain. 247 */ 248 bool xs_release_domain(struct xs_handle *h, unsigned int domid); 249 250 /* Query the home path of a domain. Call free() after use. 251 */ 252 char *xs_get_domain_path(struct xs_handle *h, unsigned int domid); 253 254 /* Returns true if child is either equal to parent, or a node underneath 255 * parent; or false otherwise. Done by string comparison, so relative and 256 * absolute pathnames never in a parent/child relationship by this 257 * definition. Cannot fail. 258 */ 259 bool xs_path_is_subpath(const char *parent, const char *child); 260 261 /* Return whether the domain specified has been introduced to xenstored. 262 */ 263 bool xs_is_domain_introduced(struct xs_handle *h, unsigned int domid); 264 265 char *xs_control_command(struct xs_handle *h, const char *cmd, 266 void *data, unsigned int len); 267 /* Deprecated: use xs_control_command() instead. */ 268 char *xs_debug_command(struct xs_handle *h, const char *cmd, 269 void *data, unsigned int len); 270 271 int xs_suspend_evtchn_port(int domid); 272 #endif /* XENSTORE_H */ 273 274 /* 275 * Local variables: 276 * c-file-style: "linux" 277 * indent-tabs-mode: t 278 * c-indent-level: 8 279 * c-basic-offset: 8 280 * tab-width: 8 281 * End: 282 */ 283