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 /* NULL ok */); 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 * Returns NULL on failure. 107 */ 108 char **xs_directory(struct xs_handle *h, xs_transaction_t t, 109 const char *path, unsigned int *num); 110 111 /* Get the value of a single file, nul terminated. 112 * Returns a malloced value: call free() on it after use. 113 * len indicates length in bytes, not including terminator. 114 * Returns NULL on failure. 115 */ 116 void *xs_read(struct xs_handle *h, xs_transaction_t t, 117 const char *path, unsigned int *len); 118 119 /* Write the value of a single file. 120 * Returns false on failure. 121 */ 122 bool xs_write(struct xs_handle *h, xs_transaction_t t, 123 const char *path, const void *data, unsigned int len); 124 125 /* Create a new directory. 126 * Returns false on failure, or success if it already exists. 127 */ 128 bool xs_mkdir(struct xs_handle *h, xs_transaction_t t, 129 const char *path); 130 131 /* Destroy a file or directory (and children). 132 * Returns false on failure, or if it doesn't exist. 133 */ 134 bool xs_rm(struct xs_handle *h, xs_transaction_t t, 135 const char *path); 136 137 /* Fake function which will always return false (required to let 138 * libxenstore remain at 3.0 version. 139 */ 140 bool xs_restrict(struct xs_handle *h, unsigned domid); 141 142 /* Get permissions of node (first element is owner, first perms is "other"). 143 * Returns malloced array, or NULL: call free() after use. 144 */ 145 struct xs_permissions *xs_get_permissions(struct xs_handle *h, 146 xs_transaction_t t, 147 const char *path, unsigned int *num); 148 149 /* Set permissions of node (must be owner). Returns false on failure. 150 * 151 * Domain 0 may read / write anywhere in the store, regardless of 152 * permission settings. 153 * 154 * Note: 155 * The perms array is a list of (domid, permissions) pairs. The first 156 * element in the list specifies the owner of the list, plus the flags 157 * for every domain not explicitly specified subsequently. The 158 * subsequent entries are normal capabilities. 159 * 160 * Example C code: 161 * 162 * struct xs_permissions perms[2]; 163 * 164 * perms[0].id = dm_domid; 165 * perms[0].perms = XS_PERM_NONE; 166 * perms[1].id = guest_domid; 167 * perms[1].perms = XS_PERM_READ; 168 * 169 * It means the owner of the path is domain $dm_domid (hence it always 170 * has read and write permission), all other domains (unless specified 171 * in subsequent pair) can neither read from nor write to that 172 * path. It then specifies domain $guest_domid can read from that 173 * path. 174 */ 175 bool xs_set_permissions(struct xs_handle *h, xs_transaction_t t, 176 const char *path, struct xs_permissions *perms, 177 unsigned int num_perms); 178 179 /* Watch a node for changes (poll on fd to detect, or call read_watch()). 180 * When the node (or any child) changes, fd will become readable. 181 * Token is returned when watch is read, to allow matching. 182 * Returns false on failure. 183 */ 184 bool xs_watch(struct xs_handle *h, const char *path, const char *token); 185 186 /* Return the FD to poll on to see if a watch has fired. */ 187 int xs_fileno(struct xs_handle *h); 188 189 /* Check for node changes. On success, returns a non-NULL pointer ret 190 * such that ret[0] and ret[1] are valid C strings, namely the 191 * triggering path (see docs/misc/xenstore.txt) and the token (from 192 * xs_watch). On error return value is NULL setting errno. 193 * 194 * Callers should, after xs_fileno has become readable, repeatedly 195 * call xs_check_watch until it returns NULL and sets errno to EAGAIN. 196 * (If the fd became readable, xs_check_watch is allowed to make it no 197 * longer show up as readable even if future calls to xs_check_watch 198 * will return more watch events.) 199 * 200 * After the caller is finished with the returned information it 201 * should be freed all in one go with free(ret). 202 */ 203 char **xs_check_watch(struct xs_handle *h); 204 205 /* Find out what node change was on (will block if nothing pending). 206 * Returns array containing the path and token, or NULL. 207 * Use XS_WATCH_* to access these elements. 208 * Call free() after use. 209 */ 210 char **xs_read_watch(struct xs_handle *h, unsigned int *num); 211 212 /* Remove a watch on a node: implicitly acks any outstanding watch. 213 * Returns false on failure (no watch on that node). 214 */ 215 bool xs_unwatch(struct xs_handle *h, const char *path, const char *token); 216 217 /* Start a transaction: changes by others will not be seen during this 218 * transaction, and changes will not be visible to others until end. 219 * Returns NULL on failure. 220 */ 221 xs_transaction_t xs_transaction_start(struct xs_handle *h); 222 223 /* End a transaction. 224 * If abandon is true, transaction is discarded instead of committed. 225 * Returns false on failure: if errno == EAGAIN, you have to restart 226 * transaction. 227 */ 228 bool xs_transaction_end(struct xs_handle *h, xs_transaction_t t, 229 bool abort); 230 231 /* Introduce a new domain. 232 * This tells the store daemon about a shared memory page, event channel and 233 * store path associated with a domain: the domain uses these to communicate. 234 */ 235 bool xs_introduce_domain(struct xs_handle *h, 236 unsigned int domid, 237 unsigned long mfn, 238 unsigned int eventchn); 239 240 /* Set the target of a domain 241 * This tells the store daemon that a domain is targetting another one, so 242 * it should let it tinker with it. 243 */ 244 bool xs_set_target(struct xs_handle *h, 245 unsigned int domid, 246 unsigned int target); 247 248 /* Resume a domain. 249 * Clear the shutdown flag for this domain in the store. 250 */ 251 bool xs_resume_domain(struct xs_handle *h, unsigned int domid); 252 253 /* Release a domain. 254 * Tells the store domain to release the memory page to the domain. 255 */ 256 bool xs_release_domain(struct xs_handle *h, unsigned int domid); 257 258 /* Query the home path of a domain. Call free() after use. 259 */ 260 char *xs_get_domain_path(struct xs_handle *h, unsigned int domid); 261 262 /* Returns true if child is either equal to parent, or a node underneath 263 * parent; or false otherwise. Done by string comparison, so relative and 264 * absolute pathnames never in a parent/child relationship by this 265 * definition. Cannot fail. 266 */ 267 bool xs_path_is_subpath(const char *parent, const char *child); 268 269 /* Return whether the domain specified has been introduced to xenstored. 270 */ 271 bool xs_is_domain_introduced(struct xs_handle *h, unsigned int domid); 272 273 char *xs_control_command(struct xs_handle *h, const char *cmd, 274 void *data, unsigned int len); 275 /* Deprecated: use xs_control_command() instead. */ 276 char *xs_debug_command(struct xs_handle *h, const char *cmd, 277 void *data, unsigned int len); 278 279 int xs_suspend_evtchn_port(int domid); 280 #endif /* XENSTORE_H */ 281 282 /* 283 * Local variables: 284 * mode: C 285 * c-file-style: "linux" 286 * indent-tabs-mode: t 287 * c-basic-offset: 8 288 * tab-width: 8 289 * End: 290 */ 291