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