debuggers.hg

view tools/xenstore/xs.h @ 22848:6341fe0f4e5a

Added tag 4.1.0-rc2 for changeset 9dca60d88c63
author Keir Fraser <keir@xen.org>
date Tue Jan 25 14:06:55 2011 +0000 (2011-01-25)
parents f46d49257da5
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 #define XS_OPEN_READONLY 1UL<<0
28 #define XS_OPEN_SOCKETONLY 1UL<<1
30 struct xs_handle;
31 typedef uint32_t xs_transaction_t;
33 /* IMPORTANT: For details on xenstore protocol limits, see
34 * docs/misc/xenstore.txt in the Xen public source repository, and use the
35 * XENSTORE_*_MAX limit macros defined in xen/io/xs_wire.h.
36 */
38 /* On failure, these routines set errno. */
40 /* Open a connection to the xs daemon.
41 * Attempts to make a connection over the socket interface,
42 * and if it fails, then over the xenbus interface.
43 * Mode 0 specifies read-write access, XS_OPEN_READONLY for
44 * read-only access.
45 * Returns a handle or NULL.
46 */
47 struct xs_handle *xs_open(unsigned long flags);
49 /* Close the connection to the xs daemon. */
50 void xs_close(struct xs_handle *xsh);
52 /* Connect to the xs daemon.
53 * Returns a handle or NULL.
54 * Deprecated, please use xs_open(0) instead
55 */
56 struct xs_handle *xs_daemon_open(void);
57 struct xs_handle *xs_domain_open(void);
59 /* Connect to the xs daemon (readonly for non-root clients).
60 * Returns a handle or NULL.
61 * Deprecated, please use xs_open(XS_OPEN_READONLY) instead
62 */
63 struct xs_handle *xs_daemon_open_readonly(void);
65 /* Close the connection to the xs daemon.
66 * Deprecated, please use xs_close() instead
67 */
68 void xs_daemon_close(struct xs_handle *);
70 /* Throw away the connection to the xs daemon, for use after fork(). */
71 void xs_daemon_destroy_postfork(struct xs_handle *);
73 /* Get contents of a directory.
74 * Returns a malloced array: call free() on it after use.
75 * Num indicates size.
76 */
77 char **xs_directory(struct xs_handle *h, xs_transaction_t t,
78 const char *path, unsigned int *num);
80 /* Get the value of a single file, nul terminated.
81 * Returns a malloced value: call free() on it after use.
82 * len indicates length in bytes, not including terminator.
83 */
84 void *xs_read(struct xs_handle *h, xs_transaction_t t,
85 const char *path, unsigned int *len);
87 /* Write the value of a single file.
88 * Returns false on failure.
89 */
90 bool xs_write(struct xs_handle *h, xs_transaction_t t,
91 const char *path, const void *data, unsigned int len);
93 /* Create a new directory.
94 * Returns false on failure, or success if it already exists.
95 */
96 bool xs_mkdir(struct xs_handle *h, xs_transaction_t t,
97 const char *path);
99 /* Destroy a file or directory (and children).
100 * Returns false on failure, or if it doesn't exist.
101 */
102 bool xs_rm(struct xs_handle *h, xs_transaction_t t,
103 const char *path);
105 /* Restrict a xenstore handle so that it acts as if it had the
106 * permissions of domain @domid. The handle must currently be
107 * using domain 0's credentials.
108 *
109 * Returns false on failure, in which case the handle continues
110 * to use the old credentials, or true on success.
111 */
112 bool xs_restrict(struct xs_handle *h, unsigned domid);
114 /* Get permissions of node (first element is owner, first perms is "other").
115 * Returns malloced array, or NULL: call free() after use.
116 */
117 struct xs_permissions *xs_get_permissions(struct xs_handle *h,
118 xs_transaction_t t,
119 const char *path, unsigned int *num);
121 /* Set permissions of node (must be owner).
122 * Returns false on failure.
123 */
124 bool xs_set_permissions(struct xs_handle *h, xs_transaction_t t,
125 const char *path, struct xs_permissions *perms,
126 unsigned int num_perms);
128 /* Watch a node for changes (poll on fd to detect, or call read_watch()).
129 * When the node (or any child) changes, fd will become readable.
130 * Token is returned when watch is read, to allow matching.
131 * Returns false on failure.
132 */
133 bool xs_watch(struct xs_handle *h, const char *path, const char *token);
135 /* Return the FD to poll on to see if a watch has fired. */
136 int xs_fileno(struct xs_handle *h);
138 /* Find out what node change was on (will block if nothing pending).
139 * Returns array containing the path and token. Use XS_WATCH_* to access these
140 * elements. Call free() after use.
141 */
142 char **xs_read_watch(struct xs_handle *h, unsigned int *num);
144 /* Remove a watch on a node: implicitly acks any outstanding watch.
145 * Returns false on failure (no watch on that node).
146 */
147 bool xs_unwatch(struct xs_handle *h, const char *path, const char *token);
149 /* Start a transaction: changes by others will not be seen during this
150 * transaction, and changes will not be visible to others until end.
151 * Returns NULL on failure.
152 */
153 xs_transaction_t xs_transaction_start(struct xs_handle *h);
155 /* End a transaction.
156 * If abandon is true, transaction is discarded instead of committed.
157 * Returns false on failure: if errno == EAGAIN, you have to restart
158 * transaction.
159 */
160 bool xs_transaction_end(struct xs_handle *h, xs_transaction_t t,
161 bool abort);
163 /* Introduce a new domain.
164 * This tells the store daemon about a shared memory page, event channel and
165 * store path associated with a domain: the domain uses these to communicate.
166 */
167 bool xs_introduce_domain(struct xs_handle *h,
168 unsigned int domid,
169 unsigned long mfn,
170 unsigned int eventchn);
172 /* Set the target of a domain
173 * This tells the store daemon that a domain is targetting another one, so
174 * it should let it tinker with it.
175 */
176 bool xs_set_target(struct xs_handle *h,
177 unsigned int domid,
178 unsigned int target);
180 /* Resume a domain.
181 * Clear the shutdown flag for this domain in the store.
182 */
183 bool xs_resume_domain(struct xs_handle *h, unsigned int domid);
185 /* Release a domain.
186 * Tells the store domain to release the memory page to the domain.
187 */
188 bool xs_release_domain(struct xs_handle *h, unsigned int domid);
190 /* Query the home path of a domain. Call free() after use.
191 */
192 char *xs_get_domain_path(struct xs_handle *h, unsigned int domid);
194 /* Return whether the domain specified has been introduced to xenstored.
195 */
196 bool xs_is_domain_introduced(struct xs_handle *h, unsigned int domid);
198 /* Only useful for DEBUG versions */
199 char *xs_debug_command(struct xs_handle *h, const char *cmd,
200 void *data, unsigned int len);
202 int xs_suspend_evtchn_port(int domid);
203 #endif /* _XS_H */
205 /*
206 * Local variables:
207 * c-file-style: "linux"
208 * indent-tabs-mode: t
209 * c-indent-level: 8
210 * c-basic-offset: 8
211 * tab-width: 8
212 * End:
213 */