ia64/xen-unstable

view tools/xenstore/xs.h @ 19586:54dbd70406ad

xenstore: Add brief notice regarding xenstore protocol limits to xs.h.

Signed-off-by: Keir Fraser <keir.fraser@citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Thu Apr 30 09:43:29 2009 +0100 (2009-04-30)
parents a5f497f02e34
children
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 #define XBT_NULL 0
27 struct xs_handle;
28 typedef uint32_t xs_transaction_t;
30 /* IMPORTANT: For details on xenstore protocol limits, see
31 * docs/misc/xenstore.txt in the Xen public source repository, and use the
32 * XENSTORE_*_MAX limit macros defined in xen/io/xs_wire.h.
33 */
35 /* On failure, these routines set errno. */
37 /* Connect to the xs daemon.
38 * Returns a handle or NULL.
39 */
40 struct xs_handle *xs_daemon_open(void);
41 struct xs_handle *xs_domain_open(void);
43 /* Connect to the xs daemon (readonly for non-root clients).
44 * Returns a handle or NULL.
45 */
46 struct xs_handle *xs_daemon_open_readonly(void);
48 /* Close the connection to the xs daemon. */
49 void xs_daemon_close(struct xs_handle *);
51 /* Get contents of a directory.
52 * Returns a malloced array: call free() on it after use.
53 * Num indicates size.
54 */
55 char **xs_directory(struct xs_handle *h, xs_transaction_t t,
56 const char *path, unsigned int *num);
58 /* Get the value of a single file, nul terminated.
59 * Returns a malloced value: call free() on it after use.
60 * len indicates length in bytes, not including terminator.
61 */
62 void *xs_read(struct xs_handle *h, xs_transaction_t t,
63 const char *path, unsigned int *len);
65 /* Write the value of a single file.
66 * Returns false on failure.
67 */
68 bool xs_write(struct xs_handle *h, xs_transaction_t t,
69 const char *path, const void *data, unsigned int len);
71 /* Create a new directory.
72 * Returns false on failure, or success if it already exists.
73 */
74 bool xs_mkdir(struct xs_handle *h, xs_transaction_t t,
75 const char *path);
77 /* Destroy a file or directory (and children).
78 * Returns false on failure, or if it doesn't exist.
79 */
80 bool xs_rm(struct xs_handle *h, xs_transaction_t t,
81 const char *path);
83 /* Get permissions of node (first element is owner, first perms is "other").
84 * Returns malloced array, or NULL: call free() after use.
85 */
86 struct xs_permissions *xs_get_permissions(struct xs_handle *h,
87 xs_transaction_t t,
88 const char *path, unsigned int *num);
90 /* Set permissions of node (must be owner).
91 * Returns false on failure.
92 */
93 bool xs_set_permissions(struct xs_handle *h, xs_transaction_t t,
94 const char *path, struct xs_permissions *perms,
95 unsigned int num_perms);
97 /* Watch a node for changes (poll on fd to detect, or call read_watch()).
98 * When the node (or any child) changes, fd will become readable.
99 * Token is returned when watch is read, to allow matching.
100 * Returns false on failure.
101 */
102 bool xs_watch(struct xs_handle *h, const char *path, const char *token);
104 /* Return the FD to poll on to see if a watch has fired. */
105 int xs_fileno(struct xs_handle *h);
107 /* Find out what node change was on (will block if nothing pending).
108 * Returns array containing the path and token. Use XS_WATCH_* to access these
109 * elements. Call free() after use.
110 */
111 char **xs_read_watch(struct xs_handle *h, unsigned int *num);
113 /* Remove a watch on a node: implicitly acks any outstanding watch.
114 * Returns false on failure (no watch on that node).
115 */
116 bool xs_unwatch(struct xs_handle *h, const char *path, const char *token);
118 /* Start a transaction: changes by others will not be seen during this
119 * transaction, and changes will not be visible to others until end.
120 * Returns NULL on failure.
121 */
122 xs_transaction_t xs_transaction_start(struct xs_handle *h);
124 /* End a transaction.
125 * If abandon is true, transaction is discarded instead of committed.
126 * Returns false on failure: if errno == EAGAIN, you have to restart
127 * transaction.
128 */
129 bool xs_transaction_end(struct xs_handle *h, xs_transaction_t t,
130 bool abort);
132 /* Introduce a new domain.
133 * This tells the store daemon about a shared memory page, event channel and
134 * store path associated with a domain: the domain uses these to communicate.
135 */
136 bool xs_introduce_domain(struct xs_handle *h,
137 unsigned int domid,
138 unsigned long mfn,
139 unsigned int eventchn);
141 /* Set the target of a domain
142 * This tells the store daemon that a domain is targetting another one, so
143 * it should let it tinker with it.
144 */
145 bool xs_set_target(struct xs_handle *h,
146 unsigned int domid,
147 unsigned int target);
149 /* Resume a domain.
150 * Clear the shutdown flag for this domain in the store.
151 */
152 bool xs_resume_domain(struct xs_handle *h, unsigned int domid);
154 /* Release a domain.
155 * Tells the store domain to release the memory page to the domain.
156 */
157 bool xs_release_domain(struct xs_handle *h, unsigned int domid);
159 /* Query the home path of a domain. Call free() after use.
160 */
161 char *xs_get_domain_path(struct xs_handle *h, unsigned int domid);
163 /* Return whether the domain specified has been introduced to xenstored.
164 */
165 bool xs_is_domain_introduced(struct xs_handle *h, unsigned int domid);
167 /* Only useful for DEBUG versions */
168 char *xs_debug_command(struct xs_handle *h, const char *cmd,
169 void *data, unsigned int len);
171 int xs_suspend_evtchn_port(int domid);
172 #endif /* _XS_H */
174 /*
175 * Local variables:
176 * c-file-style: "linux"
177 * indent-tabs-mode: t
178 * c-indent-level: 8
179 * c-basic-offset: 8
180 * tab-width: 8
181 * End:
182 */