ia64/xen-unstable

view tools/xenstore/xs.h @ 6946:e703abaf6e3d

Add behaviour to the remove methods to remove the transaction's path itself. This allows us to write Remove(path) to remove the specified path rather than having to slice the path ourselves.
author emellor@ewan
date Sun Sep 18 14:42:13 2005 +0100 (2005-09-18)
parents 3233e7ecfa9f
children a5d67e3fbff1 872cf6ee0594
line source
1 /*
2 Xen Store Daemon providing simple tree-like database.
3 Copyright (C) 2005 Rusty Russell IBM Corporation
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.
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.
15 You should have received a copy of the GNU Lesser General Public
16 License along with this library; if not, write to the Free Software
17 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18 */
20 #ifndef _XS_H
21 #define _XS_H
23 #include "xs_lib.h"
25 struct xs_handle;
27 /* On failure, these routines set errno. */
29 /* Connect to the xs daemon.
30 * Returns a handle or NULL.
31 */
32 struct xs_handle *xs_daemon_open(void);
33 struct xs_handle *xs_domain_open(void);
35 /* Connect to the xs daemon (readonly for non-root clients).
36 * Returns a handle or NULL.
37 */
38 struct xs_handle *xs_daemon_open_readonly(void);
40 /* Close the connection to the xs daemon. */
41 void xs_daemon_close(struct xs_handle *);
43 /* Get contents of a directory.
44 * Returns a malloced array: call free() on it after use.
45 * Num indicates size.
46 */
47 char **xs_directory(struct xs_handle *h, const char *path, unsigned int *num);
49 /* Get the value of a single file, nul terminated.
50 * Returns a malloced value: call free() on it after use.
51 * len indicates length in bytes, not including terminator.
52 */
53 void *xs_read(struct xs_handle *h, const char *path, unsigned int *len);
55 /* Write the value of a single file.
56 * Returns false on failure. createflags can be 0, O_CREAT, or O_CREAT|O_EXCL.
57 */
58 bool xs_write(struct xs_handle *h, const char *path, const void *data,
59 unsigned int len, int createflags);
61 /* Create a new directory.
62 * Returns false on failure.
63 */
64 bool xs_mkdir(struct xs_handle *h, const char *path);
66 /* Destroy a file or directory (and children).
67 * Returns false on failure.
68 */
69 bool xs_rm(struct xs_handle *h, const char *path);
71 /* Get permissions of node (first element is owner, first perms is "other").
72 * Returns malloced array, or NULL: call free() after use.
73 */
74 struct xs_permissions *xs_get_permissions(struct xs_handle *h,
75 const char *path, unsigned int *num);
77 /* Set permissions of node (must be owner).
78 * Returns false on failure.
79 */
80 bool xs_set_permissions(struct xs_handle *h, const char *path,
81 struct xs_permissions *perms, unsigned int num_perms);
83 /* Watch a node for changes (poll on fd to detect, or call read_watch()).
84 * When the node (or any child) changes, fd will become readable.
85 * Token is returned when watch is read, to allow matching.
86 * Returns false on failure.
87 */
88 bool xs_watch(struct xs_handle *h, const char *path, const char *token);
90 /* Return the FD to poll on to see if a watch has fired. */
91 int xs_fileno(struct xs_handle *h);
93 /* Find out what node change was on (will block if nothing pending).
94 * Returns array of two pointers: path and token, or NULL.
95 * Call free() after use.
96 */
97 char **xs_read_watch(struct xs_handle *h);
99 /* Acknowledge watch on node. Watches must be acknowledged before
100 * any other watches can be read.
101 * Returns false on failure.
102 */
103 bool xs_acknowledge_watch(struct xs_handle *h, const char *token);
105 /* Remove a watch on a node: implicitly acks any outstanding watch.
106 * Returns false on failure (no watch on that node).
107 */
108 bool xs_unwatch(struct xs_handle *h, const char *path, const char *token);
110 /* Start a transaction: changes by others will not be seen during this
111 * transaction, and changes will not be visible to others until end.
112 * Transaction only applies to the given subtree.
113 * You can only have one transaction at any time.
114 * Returns false on failure.
115 */
116 bool xs_transaction_start(struct xs_handle *h, const char *subtree);
118 /* End a transaction.
119 * If abandon is true, transaction is discarded instead of committed.
120 * Returns false on failure, which indicates an error: transactions will
121 * not fail spuriously.
122 */
123 bool xs_transaction_end(struct xs_handle *h, bool abort);
125 /* Introduce a new domain.
126 * This tells the store daemon about a shared memory page, event channel
127 * and store path associated with a domain: the domain uses these to communicate.
128 */
129 bool xs_introduce_domain(struct xs_handle *h, domid_t domid, unsigned long mfn,
130 unsigned int eventchn, const char *path);
132 /* Release a domain.
133 * Tells the store domain to release the memory page to the domain.
134 */
135 bool xs_release_domain(struct xs_handle *h, domid_t domid);
137 /* Query the home path of a domain.
138 */
139 char *xs_get_domain_path(struct xs_handle *h, domid_t domid);
141 /* Only useful for DEBUG versions */
142 char *xs_debug_command(struct xs_handle *h, const char *cmd,
143 void *data, unsigned int len);
145 /* Shut down the daemon. */
146 bool xs_shutdown(struct xs_handle *h);
148 #endif /* _XS_H */