ia64/xen-unstable

view tools/xenstore/xs.h @ 7238:971e7c7411b3

Raise an exception if an error appears on the pipes to our children, and make
sure that the child's pipes are closed even under that exception. Move the
handling of POLLHUP to the end of the loop, so that we guarantee to read any
remaining data from the child if POLLHUP and POLLIN appear at the same time.

Signed-off-by: Ewan Mellor <ewan@xensource.com>
author emellor@ewan
date Thu Oct 06 10:13:11 2005 +0100 (2005-10-06)
parents ef9591d03fdd
children 93e27f7ca8a8 61b3b357d827 402b5eb85905
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.
57 */
58 bool xs_write(struct xs_handle *h, const char *path, const void *data,
59 unsigned int len);
61 /* Create a new directory.
62 * Returns false on failure, or success if it already exists.
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, or success if it doesn't exist.
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 * You can only have one transaction at any time.
113 * Returns false on failure.
114 */
115 bool xs_transaction_start(struct xs_handle *h);
117 /* End a transaction.
118 * If abandon is true, transaction is discarded instead of committed.
119 * Returns false on failure: if errno == EAGAIN, you have to restart
120 * transaction.
121 */
122 bool xs_transaction_end(struct xs_handle *h, bool abort);
124 /* Introduce a new domain.
125 * This tells the store daemon about a shared memory page, event channel
126 * and store path associated with a domain: the domain uses these to communicate.
127 */
128 bool xs_introduce_domain(struct xs_handle *h, domid_t domid, unsigned long mfn,
129 unsigned int eventchn, const char *path);
131 /* Release a domain.
132 * Tells the store domain to release the memory page to the domain.
133 */
134 bool xs_release_domain(struct xs_handle *h, domid_t domid);
136 /* Query the home path of a domain.
137 */
138 char *xs_get_domain_path(struct xs_handle *h, domid_t domid);
140 /* Only useful for DEBUG versions */
141 char *xs_debug_command(struct xs_handle *h, const char *cmd,
142 void *data, unsigned int len);
144 /* Shut down the daemon. */
145 bool xs_shutdown(struct xs_handle *h);
147 #endif /* _XS_H */