~ubuntu-branches/ubuntu/oneiric/libvirt/oneiric-updates
» Revision
132
: .pc/9027-CVE-2011-1146.patch/src/libvirt.c
« back to all changes in this revision
Viewing changes to .pc/9027-CVE-2011-1146.patch/src/libvirt.c
- browse files at revision 132
- compare with another revision
- download diff
- download tarball
- view history from revision 132
- Committer: Package Import Robot
- Author(s): Serge Hallyn
- Date: 2011-05-11 12:29:51 UTC
- mfrom: (1.2.10) (3.4.30 sid)
- Revision ID: package-import@ubuntu.com-20110511122951-ku5fk1tv37o5aymm
Tags: 0.9.1-1ubuntu1
* Resynchronize and merge from Debian unstable (LP: #794378). Remaining
changes:
- debian/control:
* set X-Python-Version to 2.7, as 2.6 is not in oneiric.
* set ubuntu maintainer
* Build-Depends:
- remove [linux-any] from all dependencies
- remove [!linux-any] deps
- swap libxen to libxen3, qemu to qemu-kvm, and open-iscsi to
open-iscsi-utils in Build-Depends
- remove virtualbox-ose Build-Depends
- add parted and libapparmor-dev Build-Depends
* convert Vcs-Git to Xs-Debian-Vcs-Git
* libvirt-bin Depends: move netcat-openbsd, bridge-utils, dnsmasq-base
(>= 2.46-1), and iptables from Recommends to Depends
* libvirt-bin Recommends: move qemu to Suggests
* libvirt-bin Suggests: add apparmor
* libvirt0 Recommands: move lvm2 to Suggests
- keep debian/libvirt-bin.apport
- keep debian/libvirt-bin.cron.daily
- debian/libvirt-bin.dirs:
* add apparmor, cron.daily, and apport dirs
- debian/libvirt-bin.examples:
* add debian/libvirt-suspendonreboot
- debian/libvirt-bin.install:
* add /etc/apparmor.d files
* add apport hook
- debian/libvirt-bin.manpages:
* add debian/libvirt-migrate-qemu-disks.1
- debian/libvirt-bin.postinst:
* replace libvirt groupname with libvirtd
* add each admin user to libvirtd group
* call apparmor_parser on usr.sbin.libvirtd and
usr.lib.libvirt.virt-aa-helper
* call 'libvirt-migrate-qemu-disks -a' after
libvirt-bin has started if migrating from
older than 0.8.3-1ubuntu1
- debian/libvirt-bin.postrm:
* replace libvirt groupname with libvirtd
* remove usr.sbin.libvirtd and
usr.lib.libvirt.virt-aa-helper
- keep added files under debian/:
* libvirt-bin.upstart
* libvirt-migrate-qemu-disks
* libvirt-migrate-qemu-disks.1
* libvirt-suspendonreboot
* apparmor profiles
- debian/README.Debian:
* add 'Apparmor Profile' section
* add 'Disk migration' section
- debian/rules:
* move include of debhelper.mk to top of file so DEB_HOST_ARCH_OS
is defined.
* don't build with vbox since virtualbox-ose is in universe
- remove WITH_VBOX, add explicit --without-vbox
* add --with-apparmor to DEB_CONFIGURE_EXTRA_FLAGS
* set DEB_DH_INSTALLINIT_ARGS to '--upstart-only'
* remove unneeded binary-install/libvirt-bin:: and clean::
sections (they only deal with sysvinit stuff)
* add build/libvirt-bin:: section to install
- apparmor files
- apport hooks
- libvirt-migrate-qemu-disks
* debian/patches/series:
- don't apply Disable-CHECKSUM-rule.patch: our iptables can do this
- don't apply Debian-specific Debianize-libvirt-guests.patch (sysvinit only)
- don't apply Disable qemu-disable-network.diff.patch
* debian/patches:
- drop 9007-fix-daemon-conf-ftbfs.patch (looks like it may be fixed)
- drop patches applied upstream:
* 9022-drop-booton-when-kernel-specified.patch
* 9023-fix-lxc-console-hangup.patch
* 9024-fix-broken-commandtest.patch
* 9025-Pass-virSecurityManagerPtr-to-virSecurityDAC-Set-Res.patch
* 9026-security-avoid-memory-leak.patch
* 9027-CVE-2011-1146.patch
- keep patches:
* 9000-delayed_iff_up_bridge.patch
* 9001-dont_clobber_existing_bridges.patch
* 9002-better_default_uri_virsh.patch
* 9003-better-default-arch.patch
* 9004-libvirtd-group-name.patch
* 9005-increase-unix-socket-timeout.patch
* 9006-default-config-test-case.patch
* 9011-move-ebtables-script.patch (refreshed)
* 9014-skip-nodeinfotest.patch (modified to make it apply)
* 9020-lp545795.patch (modified to make it still apply)
* 9021-fix-uint64_t.patch
* 9022-allows-lxc-containers-with-lxcguest.patch (renamed, modified
to make it still apply, and added DEP-3 tags).
- new patches:
* 9023-disable-test-poll.patch - don't run broken test-poll
changes:
- debian/control:
* set X-Python-Version to 2.7, as 2.6 is not in oneiric.
* set ubuntu maintainer
* Build-Depends:
- remove [linux-any] from all dependencies
- remove [!linux-any] deps
- swap libxen to libxen3, qemu to qemu-kvm, and open-iscsi to
open-iscsi-utils in Build-Depends
- remove virtualbox-ose Build-Depends
- add parted and libapparmor-dev Build-Depends
* convert Vcs-Git to Xs-Debian-Vcs-Git
* libvirt-bin Depends: move netcat-openbsd, bridge-utils, dnsmasq-base
(>= 2.46-1), and iptables from Recommends to Depends
* libvirt-bin Recommends: move qemu to Suggests
* libvirt-bin Suggests: add apparmor
* libvirt0 Recommands: move lvm2 to Suggests
- keep debian/libvirt-bin.apport
- keep debian/libvirt-bin.cron.daily
- debian/libvirt-bin.dirs:
* add apparmor, cron.daily, and apport dirs
- debian/libvirt-bin.examples:
* add debian/libvirt-suspendonreboot
- debian/libvirt-bin.install:
* add /etc/apparmor.d files
* add apport hook
- debian/libvirt-bin.manpages:
* add debian/libvirt-migrate-qemu-disks.1
- debian/libvirt-bin.postinst:
* replace libvirt groupname with libvirtd
* add each admin user to libvirtd group
* call apparmor_parser on usr.sbin.libvirtd and
usr.lib.libvirt.virt-aa-helper
* call 'libvirt-migrate-qemu-disks -a' after
libvirt-bin has started if migrating from
older than 0.8.3-1ubuntu1
- debian/libvirt-bin.postrm:
* replace libvirt groupname with libvirtd
* remove usr.sbin.libvirtd and
usr.lib.libvirt.virt-aa-helper
- keep added files under debian/:
* libvirt-bin.upstart
* libvirt-migrate-qemu-disks
* libvirt-migrate-qemu-disks.1
* libvirt-suspendonreboot
* apparmor profiles
- debian/README.Debian:
* add 'Apparmor Profile' section
* add 'Disk migration' section
- debian/rules:
* move include of debhelper.mk to top of file so DEB_HOST_ARCH_OS
is defined.
* don't build with vbox since virtualbox-ose is in universe
- remove WITH_VBOX, add explicit --without-vbox
* add --with-apparmor to DEB_CONFIGURE_EXTRA_FLAGS
* set DEB_DH_INSTALLINIT_ARGS to '--upstart-only'
* remove unneeded binary-install/libvirt-bin:: and clean::
sections (they only deal with sysvinit stuff)
* add build/libvirt-bin:: section to install
- apparmor files
- apport hooks
- libvirt-migrate-qemu-disks
* debian/patches/series:
- don't apply Disable-CHECKSUM-rule.patch: our iptables can do this
- don't apply Debian-specific Debianize-libvirt-guests.patch (sysvinit only)
- don't apply Disable qemu-disable-network.diff.patch
* debian/patches:
- drop 9007-fix-daemon-conf-ftbfs.patch (looks like it may be fixed)
- drop patches applied upstream:
* 9022-drop-booton-when-kernel-specified.patch
* 9023-fix-lxc-console-hangup.patch
* 9024-fix-broken-commandtest.patch
* 9025-Pass-virSecurityManagerPtr-to-virSecurityDAC-Set-Res.patch
* 9026-security-avoid-memory-leak.patch
* 9027-CVE-2011-1146.patch
- keep patches:
* 9000-delayed_iff_up_bridge.patch
* 9001-dont_clobber_existing_bridges.patch
* 9002-better_default_uri_virsh.patch
* 9003-better-default-arch.patch
* 9004-libvirtd-group-name.patch
* 9005-increase-unix-socket-timeout.patch
* 9006-default-config-test-case.patch
* 9011-move-ebtables-script.patch (refreshed)
* 9014-skip-nodeinfotest.patch (modified to make it apply)
* 9020-lp545795.patch (modified to make it still apply)
* 9021-fix-uint64_t.patch
* 9022-allows-lxc-containers-with-lxcguest.patch (renamed, modified
to make it still apply, and added DEP-3 tags).
- new patches:
* 9023-disable-test-poll.patch - don't run broken test-poll
- files added:
- .pc/9022-allows-lxc-containers-with-lxcguest.patch
- .pc/9022-allows-lxc-containers-with-lxcguest.patch/src
- .pc/9022-allows-lxc-containers-with-lxcguest.patch/src/lxc
- .pc/9023-disable-test-poll.patch
- .pc/9023-disable-test-poll.patch/gnulib
- .pc/9023-disable-test-poll.patch/gnulib/tests
- .pc/Disable-daemon-start-test.patch
- .pc/Disable-daemon-start-test.patch/tests
- .pc/allow-libvirt-group-to-access-the-socket.patch/tests
- .pc/virsh-Initialize-library-before-calling-virResetLast.patch
- .pc/virsh-Initialize-library-before-calling-virResetLast.patch/tools
- src/libxl
- src/xenxs
- files removed:
- .pc/9007-fix-daemon-conf-ftbfs.patch
- .pc/9007-fix-daemon-conf-ftbfs.patch/tests
- .pc/9022-drop-booton-when-kernel-specified.patch
- .pc/9022-drop-booton-when-kernel-specified.patch/src
- .pc/9022-drop-booton-when-kernel-specified.patch/src/qemu
- .pc/9023-fix-lxc-console-hangup.patch
- .pc/9023-fix-lxc-console-hangup.patch/src
- .pc/9023-fix-lxc-console-hangup.patch/src/lxc
- .pc/9024-fix-broken-commandtest.patch
- .pc/9024-fix-broken-commandtest.patch/tests
- .pc/9025-Pass-virSecurityManagerPtr-to-virSecurityDAC-Set-Res.patch
- .pc/9025-Pass-virSecurityManagerPtr-to-virSecurityDAC-Set-Res.patch/src
- .pc/9025-Pass-virSecurityManagerPtr-to-virSecurityDAC-Set-Res.patch/src/security
- .pc/9026-security-avoid-memory-leak.patch
- .pc/9026-security-avoid-memory-leak.patch/src
- .pc/9026-security-avoid-memory-leak.patch/src/qemu
- .pc/9026-security-avoid-memory-leak.patch/src/security
- .pc/9027-CVE-2011-1146.patch
- .pc/9027-CVE-2011-1146.patch/src
- .pc/Don-t-pass-empty-arguments-to-dnsmasq.patch
- .pc/Don-t-pass-empty-arguments-to-dnsmasq.patch/src
- .pc/Don-t-pass-empty-arguments-to-dnsmasq.patch/src/network
- .pc/allows-lxc-containers-with-lxcguest.patch
- .pc/allows-lxc-containers-with-lxcguest.patch/src
- .pc/allows-lxc-containers-with-lxcguest.patch/src/lxc
- src/opennebula
- files modified:
- .pc/9000-delayed_iff_up_bridge.patch/src/util/bridge.c
added
removed
.pc/9027-CVE-2011-1146.patch/src/libvirt.c
1
/*
2
* libvirt.c: Main interfaces for the libvirt library to handle virtualization
3
* domains from a process running in domain 0
4
*
5
* Copyright (C) 2005-2006, 2008-2011 Red Hat, Inc.
6
*
7
* See COPYING.LIB for the License of this software
8
*
9
* Daniel Veillard <veillard@redhat.com>
10
*/
11
12
#include <config.h>
13
14
#include <stdio.h>
15
#include <stdlib.h>
16
#include <string.h>
17
#include <sys/types.h>
18
#include <sys/stat.h>
19
#include <unistd.h>
20
#include <assert.h>
21
#include <sys/wait.h>
22
#include <time.h>
23
#include <gcrypt.h>
24
25
#include <libxml/parser.h>
26
#include <libxml/xpath.h>
27
#include <libxml/uri.h>
28
#include "getpass.h"
29
30
#ifdef HAVE_WINSOCK2_H
31
# include <winsock2.h>
32
#endif
33
34
#include "virterror_internal.h"
35
#include "logging.h"
36
#include "datatypes.h"
37
#include "driver.h"
38
39
#include "uuid.h"
40
#include "util.h"
41
#include "memory.h"
42
#include "configmake.h"
43
44
#ifndef WITH_DRIVER_MODULES
45
# ifdef WITH_TEST
46
# include "test/test_driver.h"
47
# endif
48
# ifdef WITH_XEN
49
# include "xen/xen_driver.h"
50
# endif
51
# ifdef WITH_REMOTE
52
# include "remote/remote_driver.h"
53
# endif
54
# ifdef WITH_OPENVZ
55
# include "openvz/openvz_driver.h"
56
# endif
57
# ifdef WITH_VMWARE
58
# include "vmware/vmware_driver.h"
59
# endif
60
# ifdef WITH_PHYP
61
# include "phyp/phyp_driver.h"
62
# endif
63
# ifdef WITH_VBOX
64
# include "vbox/vbox_driver.h"
65
# endif
66
# ifdef WITH_ESX
67
# include "esx/esx_driver.h"
68
# endif
69
# ifdef WITH_XENAPI
70
# include "xenapi/xenapi_driver.h"
71
# endif
72
#endif
73
74
#define VIR_FROM_THIS VIR_FROM_NONE
75
76
/*
77
* TODO:
78
* - use lock to protect against concurrent accesses ?
79
* - use reference counting to guarantee coherent pointer state ?
80
*/
81
82
#define MAX_DRIVERS 20
83
84
static virDriverPtr virDriverTab[MAX_DRIVERS];
85
static int virDriverTabCount = 0;
86
static virNetworkDriverPtr virNetworkDriverTab[MAX_DRIVERS];
87
static int virNetworkDriverTabCount = 0;
88
static virInterfaceDriverPtr virInterfaceDriverTab[MAX_DRIVERS];
89
static int virInterfaceDriverTabCount = 0;
90
static virStorageDriverPtr virStorageDriverTab[MAX_DRIVERS];
91
static int virStorageDriverTabCount = 0;
92
static virDeviceMonitorPtr virDeviceMonitorTab[MAX_DRIVERS];
93
static int virDeviceMonitorTabCount = 0;
94
static virSecretDriverPtr virSecretDriverTab[MAX_DRIVERS];
95
static int virSecretDriverTabCount = 0;
96
static virNWFilterDriverPtr virNWFilterDriverTab[MAX_DRIVERS];
97
static int virNWFilterDriverTabCount = 0;
98
#ifdef WITH_LIBVIRTD
99
static virStateDriverPtr virStateDriverTab[MAX_DRIVERS];
100
static int virStateDriverTabCount = 0;
101
#endif
102
static int initialized = 0;
103
104
#if defined(POLKIT_AUTH)
105
static int virConnectAuthGainPolkit(const char *privilege) {
106
const char *const args[] = {
107
POLKIT_AUTH, "--obtain", privilege, NULL
108
};
109
int childpid, status, ret;
110
111
/* Root has all rights */
112
if (getuid() == 0)
113
return 0;
114
115
if ((childpid = fork()) < 0)
116
return -1;
117
118
if (!childpid) {
119
execvp(args[0], (char **)args);
120
_exit(-1);
121
}
122
123
while ((ret = waitpid(childpid, &status, 0) == -1) && errno == EINTR);
124
if (ret == -1) {
125
return -1;
126
}
127
128
if (!WIFEXITED(status) ||
129
(WEXITSTATUS(status) != 0 && WEXITSTATUS(status) != 1)) {
130
return -1;
131
}
132
133
return 0;
134
}
135
#endif
136
137
static int virConnectAuthCallbackDefault(virConnectCredentialPtr cred,
138
unsigned int ncred,
139
void *cbdata ATTRIBUTE_UNUSED) {
140
int i;
141
142
for (i = 0 ; i < ncred ; i++) {
143
char buf[1024];
144
char *bufptr = buf;
145
size_t len;
146
147
switch (cred[i].type) {
148
case VIR_CRED_EXTERNAL: {
149
if (STRNEQ(cred[i].challenge, "PolicyKit"))
150
return -1;
151
152
#if defined(POLKIT_AUTH)
153
if (virConnectAuthGainPolkit(cred[i].prompt) < 0)
154
return -1;
155
#else
156
/*
157
* Ignore & carry on. Although we can't auth
158
* directly, the user may have authenticated
159
* themselves already outside context of libvirt
160
*/
161
#endif
162
break;
163
}
164
165
case VIR_CRED_USERNAME:
166
case VIR_CRED_AUTHNAME:
167
case VIR_CRED_ECHOPROMPT:
168
case VIR_CRED_REALM:
169
if (printf("%s: ", cred[i].prompt) < 0)
170
return -1;
171
if (fflush(stdout) != 0)
172
return -1;
173
174
if (!fgets(buf, sizeof(buf), stdin)) {
175
if (feof(stdin)) { /* Treat EOF as "" */
176
buf[0] = '\0';
177
break;
178
}
179
return -1;
180
}
181
len = strlen(buf);
182
if (len != 0 && buf[len-1] == '\n')
183
buf[len-1] = '\0';
184
break;
185
186
case VIR_CRED_PASSPHRASE:
187
case VIR_CRED_NOECHOPROMPT:
188
if (printf("%s: ", cred[i].prompt) < 0)
189
return -1;
190
if (fflush(stdout) != 0)
191
return -1;
192
193
bufptr = getpass("");
194
if (!bufptr)
195
return -1;
196
break;
197
198
default:
199
return -1;
200
}
201
202
if (cred[i].type != VIR_CRED_EXTERNAL) {
203
if (STREQ(bufptr, "") && cred[i].defresult)
204
cred[i].result = strdup(cred[i].defresult);
205
else
206
cred[i].result = strdup(bufptr);
207
if (!cred[i].result)
208
return -1;
209
cred[i].resultlen = strlen(cred[i].result);
210
}
211
}
212
213
return 0;
214
}
215
216
/* Don't typically want VIR_CRED_USERNAME. It enables you to authenticate
217
* as one user, and act as another. It just results in annoying
218
* prompts for the username twice & is very rarely what you want
219
*/
220
static int virConnectCredTypeDefault[] = {
221
VIR_CRED_AUTHNAME,
222
VIR_CRED_ECHOPROMPT,
223
VIR_CRED_REALM,
224
VIR_CRED_PASSPHRASE,
225
VIR_CRED_NOECHOPROMPT,
226
VIR_CRED_EXTERNAL,
227
};
228
229
static virConnectAuth virConnectAuthDefault = {
230
virConnectCredTypeDefault,
231
sizeof(virConnectCredTypeDefault)/sizeof(int),
232
virConnectAuthCallbackDefault,
233
NULL,
234
};
235
236
/*
237
* virConnectAuthPtrDefault
238
*
239
* A default implementation of the authentication callbacks. This
240
* implementation is suitable for command line based tools. It will
241
* prompt for username, passwords, realm and one time keys as needed.
242
* It will print on STDOUT, and read from STDIN. If this is not
243
* suitable for the application's needs an alternative implementation
244
* should be provided.
245
*/
246
virConnectAuthPtr virConnectAuthPtrDefault = &virConnectAuthDefault;
247
248
#if HAVE_WINSOCK2_H
249
static int
250
winsock_init (void)
251
{
252
WORD winsock_version, err;
253
WSADATA winsock_data;
254
255
/* http://msdn2.microsoft.com/en-us/library/ms742213.aspx */
256
winsock_version = MAKEWORD (2, 2);
257
err = WSAStartup (winsock_version, &winsock_data);
258
return err == 0 ? 0 : -1;
259
}
260
#endif
261
262
static int virTLSMutexInit (void **priv)
263
{ \
264
virMutexPtr lock = NULL;
265
266
if (VIR_ALLOC(lock) < 0)
267
return ENOMEM;
268
269
if (virMutexInit(lock) < 0) {
270
VIR_FREE(lock);
271
return errno;
272
}
273
274
*priv = lock;
275
return 0;
276
}
277
278
static int virTLSMutexDestroy(void **priv)
279
{
280
virMutexPtr lock = *priv;
281
virMutexDestroy(lock);
282
VIR_FREE(lock);
283
return 0;
284
}
285
286
static int virTLSMutexLock(void **priv)
287
{
288
virMutexPtr lock = *priv;
289
virMutexLock(lock);
290
return 0;
291
}
292
293
static int virTLSMutexUnlock(void **priv)
294
{
295
virMutexPtr lock = *priv;
296
virMutexUnlock(lock);
297
return 0;
298
}
299
300
static struct gcry_thread_cbs virTLSThreadImpl = {
301
/* GCRY_THREAD_OPTION_VERSION was added in gcrypt 1.4.2 */
302
#ifdef GCRY_THREAD_OPTION_VERSION
303
(GCRY_THREAD_OPTION_PTHREAD | (GCRY_THREAD_OPTION_VERSION << 8)),
304
#else
305
GCRY_THREAD_OPTION_PTHREAD,
306
#endif
307
NULL,
308
virTLSMutexInit,
309
virTLSMutexDestroy,
310
virTLSMutexLock,
311
virTLSMutexUnlock,
312
NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL
313
};
314
315
/* Helper macro to print debugging information about a domain DOM,
316
* followed by a literal string FMT and any other printf arguments.
317
*/
318
#define VIR_DOMAIN_DEBUG(dom, fmt, ...) \
319
char _uuidstr[VIR_UUID_STRING_BUFLEN]; \
320
const char *_domname = NULL; \
321
\
322
if (!VIR_IS_DOMAIN(dom)) { \
323
memset(_uuidstr, 0, sizeof(_uuidstr)); \
324
} else { \
325
virUUIDFormat((dom)->uuid, _uuidstr); \
326
_domname = (dom)->name; \
327
} \
328
\
329
DEBUG("dom=%p, (VM: name=%s, uuid=%s), " fmt, \
330
dom, NULLSTR(_domname), _uuidstr, __VA_ARGS__)
331
332
#define VIR_DOMAIN_DEBUG0(dom) VIR_DOMAIN_DEBUG(dom, "%s", "")
333
334
/**
335
* virInitialize:
336
*
337
* Initialize the library. It's better to call this routine at startup
338
* in multithreaded applications to avoid potential race when initializing
339
* the library.
340
*
341
* Returns 0 in case of success, -1 in case of error
342
*/
343
int
344
virInitialize(void)
345
{
346
if (initialized)
347
return 0;
348
349
initialized = 1;
350
351
if (virThreadInitialize() < 0 ||
352
virErrorInitialize() < 0 ||
353
virRandomInitialize(time(NULL) ^ getpid()))
354
return -1;
355
356
gcry_control(GCRYCTL_SET_THREAD_CBS, &virTLSThreadImpl);
357
gcry_check_version(NULL);
358
359
virLogSetFromEnv();
360
361
DEBUG0("register drivers");
362
363
#if HAVE_WINSOCK2_H
364
if (winsock_init () == -1) return -1;
365
#endif
366
367
if (!bindtextdomain(PACKAGE, LOCALEDIR))
368
return -1;
369
370
/*
371
* Note that the order is important: the first ones have a higher
372
* priority when calling virConnectOpen.
373
*/
374
#ifdef WITH_DRIVER_MODULES
375
/* We don't care if any of these fail, because the whole point
376
* is to allow users to only install modules they want to use.
377
* If they try to open a connection for a module that
378
* is not loaded they'll get a suitable error at that point
379
*/
380
# ifdef WITH_TEST
381
virDriverLoadModule("test");
382
# endif
383
# ifdef WITH_XEN
384
virDriverLoadModule("xen");
385
# endif
386
# ifdef WITH_OPENVZ
387
virDriverLoadModule("openvz");
388
# endif
389
# ifdef WITH_VMWARE
390
virDriverLoadModule("vmware");
391
# endif
392
# ifdef WITH_VBOX
393
virDriverLoadModule("vbox");
394
# endif
395
# ifdef WITH_ESX
396
virDriverLoadModule("esx");
397
# endif
398
# ifdef WITH_XENAPI
399
virDriverLoadModule("xenapi");
400
# endif
401
# ifdef WITH_REMOTE
402
virDriverLoadModule("remote");
403
# endif
404
#else
405
# ifdef WITH_TEST
406
if (testRegister() == -1) return -1;
407
# endif
408
# ifdef WITH_XEN
409
if (xenRegister () == -1) return -1;
410
# endif
411
# ifdef WITH_OPENVZ
412
if (openvzRegister() == -1) return -1;
413
# endif
414
# ifdef WITH_VMWARE
415
if (vmwareRegister() == -1) return -1;
416
# endif
417
# ifdef WITH_PHYP
418
if (phypRegister() == -1) return -1;
419
# endif
420
# ifdef WITH_VBOX
421
if (vboxRegister() == -1) return -1;
422
# endif
423
# ifdef WITH_ESX
424
if (esxRegister() == -1) return -1;
425
# endif
426
# ifdef WITH_XENAPI
427
if (xenapiRegister() == -1) return -1;
428
# endif
429
# ifdef WITH_REMOTE
430
if (remoteRegister () == -1) return -1;
431
# endif
432
#endif
433
434
return 0;
435
}
436
437
#ifdef WIN32
438
BOOL WINAPI
439
DllMain (HINSTANCE instance, DWORD reason, LPVOID ignore);
440
441
BOOL WINAPI
442
DllMain (HINSTANCE instance ATTRIBUTE_UNUSED,
443
DWORD reason,
444
LPVOID ignore ATTRIBUTE_UNUSED)
445
{
446
switch (reason) {
447
case DLL_PROCESS_ATTACH:
448
virInitialize();
449
break;
450
451
case DLL_THREAD_ATTACH:
452
/* Nothing todo in libvirt yet */
453
break;
454
455
case DLL_THREAD_DETACH:
456
/* Release per-thread local data */
457
virThreadOnExit();
458
break;
459
460
case DLL_PROCESS_DETACH:
461
/* Don't bother releasing per-thread data
462
since (hopefully) windows cleans up
463
everything on process exit */
464
break;
465
}
466
467
return TRUE;
468
}
469
#endif
470
471
#define virLibConnError(code, ...) \
472
virReportErrorHelper(NULL, VIR_FROM_NONE, code, __FILE__, \
473
__FUNCTION__, __LINE__, __VA_ARGS__)
474
#define virLibDomainError(code, ...) \
475
virReportErrorHelper(NULL, VIR_FROM_DOM, code, __FILE__, \
476
__FUNCTION__, __LINE__, __VA_ARGS__)
477
#define virLibNetworkError(code, ...) \
478
virReportErrorHelper(NULL, VIR_FROM_NETWORK, code, __FILE__, \
479
__FUNCTION__, __LINE__, __VA_ARGS__)
480
#define virLibStoragePoolError(code, ...) \
481
virReportErrorHelper(NULL, VIR_FROM_STORAGE, code, __FILE__, \
482
__FUNCTION__, __LINE__, __VA_ARGS__)
483
#define virLibStorageVolError(code, ...) \
484
virReportErrorHelper(NULL, VIR_FROM_STORAGE, code, __FILE__, \
485
__FUNCTION__, __LINE__, __VA_ARGS__)
486
#define virLibInterfaceError(code, ...) \
487
virReportErrorHelper(NULL, VIR_FROM_INTERFACE, code, __FILE__,\
488
__FUNCTION__, __LINE__, __VA_ARGS__)
489
#define virLibNodeDeviceError(code, ...) \
490
virReportErrorHelper(NULL, VIR_FROM_NODEDEV, code, __FILE__, \
491
__FUNCTION__, __LINE__, __VA_ARGS__)
492
#define virLibSecretError(code, ...) \
493
virReportErrorHelper(NULL, VIR_FROM_SECRET, code, __FILE__, \
494
__FUNCTION__, __LINE__, __VA_ARGS__)
495
#define virLibStreamError(code, ...) \
496
virReportErrorHelper(NULL, VIR_FROM_STREAMS, code, __FILE__, \
497
__FUNCTION__, __LINE__, __VA_ARGS__)
498
#define virLibNWFilterError(code, ...) \
499
virReportErrorHelper(NULL, VIR_FROM_NWFILTER, code, __FILE__, \
500
__FUNCTION__, __LINE__, __VA_ARGS__)
501
#define virLibDomainSnapshotError(code, ...) \
502
virReportErrorHelper(NULL, VIR_FROM_DOMAIN_SNAPSHOT, code, __FILE__, \
503
__FUNCTION__, __LINE__, __VA_ARGS__)
504
505
506
/**
507
* virRegisterNetworkDriver:
508
* @driver: pointer to a network driver block
509
*
510
* Register a network virtualization driver
511
*
512
* Returns the driver priority or -1 in case of error.
513
*/
514
int
515
virRegisterNetworkDriver(virNetworkDriverPtr driver)
516
{
517
if (virInitialize() < 0)
518
return -1;
519
520
if (driver == NULL) {
521
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
522
return -1;
523
}
524
525
if (virNetworkDriverTabCount >= MAX_DRIVERS) {
526
virLibConnError(VIR_ERR_INTERNAL_ERROR,
527
_("Too many drivers, cannot register %s"),
528
driver->name);
529
return -1;
530
}
531
532
DEBUG ("registering %s as network driver %d",
533
driver->name, virNetworkDriverTabCount);
534
535
virNetworkDriverTab[virNetworkDriverTabCount] = driver;
536
return virNetworkDriverTabCount++;
537
}
538
539
/**
540
* virRegisterInterfaceDriver:
541
* @driver: pointer to an interface driver block
542
*
543
* Register an interface virtualization driver
544
*
545
* Returns the driver priority or -1 in case of error.
546
*/
547
int
548
virRegisterInterfaceDriver(virInterfaceDriverPtr driver)
549
{
550
if (virInitialize() < 0)
551
return -1;
552
553
if (driver == NULL) {
554
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
555
return -1;
556
}
557
558
if (virInterfaceDriverTabCount >= MAX_DRIVERS) {
559
virLibConnError(VIR_ERR_INTERNAL_ERROR,
560
_("Too many drivers, cannot register %s"),
561
driver->name);
562
return -1;
563
}
564
565
DEBUG ("registering %s as interface driver %d",
566
driver->name, virInterfaceDriverTabCount);
567
568
virInterfaceDriverTab[virInterfaceDriverTabCount] = driver;
569
return virInterfaceDriverTabCount++;
570
}
571
572
/**
573
* virRegisterStorageDriver:
574
* @driver: pointer to a storage driver block
575
*
576
* Register a storage virtualization driver
577
*
578
* Returns the driver priority or -1 in case of error.
579
*/
580
int
581
virRegisterStorageDriver(virStorageDriverPtr driver)
582
{
583
if (virInitialize() < 0)
584
return -1;
585
586
if (driver == NULL) {
587
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
588
return -1;
589
}
590
591
if (virStorageDriverTabCount >= MAX_DRIVERS) {
592
virLibConnError(VIR_ERR_INTERNAL_ERROR,
593
_("Too many drivers, cannot register %s"),
594
driver->name);
595
return -1;
596
}
597
598
DEBUG ("registering %s as storage driver %d",
599
driver->name, virStorageDriverTabCount);
600
601
virStorageDriverTab[virStorageDriverTabCount] = driver;
602
return virStorageDriverTabCount++;
603
}
604
605
/**
606
* virRegisterDeviceMonitor:
607
* @driver: pointer to a device monitor block
608
*
609
* Register a device monitor
610
*
611
* Returns the driver priority or -1 in case of error.
612
*/
613
int
614
virRegisterDeviceMonitor(virDeviceMonitorPtr driver)
615
{
616
if (virInitialize() < 0)
617
return -1;
618
619
if (driver == NULL) {
620
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
621
return -1;
622
}
623
624
if (virDeviceMonitorTabCount >= MAX_DRIVERS) {
625
virLibConnError(VIR_ERR_INTERNAL_ERROR,
626
_("Too many drivers, cannot register %s"),
627
driver->name);
628
return -1;
629
}
630
631
DEBUG ("registering %s as device driver %d",
632
driver->name, virDeviceMonitorTabCount);
633
634
virDeviceMonitorTab[virDeviceMonitorTabCount] = driver;
635
return virDeviceMonitorTabCount++;
636
}
637
638
/**
639
* virRegisterSecretDriver:
640
* @driver: pointer to a secret driver block
641
*
642
* Register a secret driver
643
*
644
* Returns the driver priority or -1 in case of error.
645
*/
646
int
647
virRegisterSecretDriver(virSecretDriverPtr driver)
648
{
649
if (virInitialize() < 0)
650
return -1;
651
652
if (driver == NULL) {
653
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
654
return -1;
655
}
656
657
if (virSecretDriverTabCount >= MAX_DRIVERS) {
658
virLibConnError(VIR_ERR_INTERNAL_ERROR,
659
_("Too many drivers, cannot register %s"),
660
driver->name);
661
return -1;
662
}
663
664
DEBUG ("registering %s as secret driver %d",
665
driver->name, virSecretDriverTabCount);
666
667
virSecretDriverTab[virSecretDriverTabCount] = driver;
668
return virSecretDriverTabCount++;
669
}
670
671
/**
672
* virRegisterNWFilterDriver:
673
* @driver: pointer to a network filter driver block
674
*
675
* Register a network filter virtualization driver
676
*
677
* Returns the driver priority or -1 in case of error.
678
*/
679
int
680
virRegisterNWFilterDriver(virNWFilterDriverPtr driver)
681
{
682
if (virInitialize() < 0)
683
return -1;
684
685
if (driver == NULL) {
686
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
687
return -1;
688
}
689
690
if (virNWFilterDriverTabCount >= MAX_DRIVERS) {
691
virLibConnError(VIR_ERR_INTERNAL_ERROR,
692
_("Too many drivers, cannot register %s"),
693
driver->name);
694
return -1;
695
}
696
697
DEBUG ("registering %s as network filter driver %d",
698
driver->name, virNWFilterDriverTabCount);
699
700
virNWFilterDriverTab[virNWFilterDriverTabCount] = driver;
701
return virNWFilterDriverTabCount++;
702
}
703
704
705
/**
706
* virRegisterDriver:
707
* @driver: pointer to a driver block
708
*
709
* Register a virtualization driver
710
*
711
* Returns the driver priority or -1 in case of error.
712
*/
713
int
714
virRegisterDriver(virDriverPtr driver)
715
{
716
DEBUG("driver=%p name=%s", driver, driver ? NULLSTR(driver->name) : "(null)");
717
718
if (virInitialize() < 0)
719
return -1;
720
721
if (driver == NULL) {
722
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
723
return -1;
724
}
725
726
if (virDriverTabCount >= MAX_DRIVERS) {
727
virLibConnError(VIR_ERR_INTERNAL_ERROR,
728
_("Too many drivers, cannot register %s"),
729
driver->name);
730
return -1;
731
}
732
733
if (driver->no < 0) {
734
virLibConnError(VIR_ERR_INVALID_ARG,
735
_("Tried to register an internal Xen driver"));
736
return -1;
737
}
738
739
DEBUG ("registering %s as driver %d",
740
driver->name, virDriverTabCount);
741
742
virDriverTab[virDriverTabCount] = driver;
743
return virDriverTabCount++;
744
}
745
746
#ifdef WITH_LIBVIRTD
747
/**
748
* virRegisterStateDriver:
749
* @driver: pointer to a driver block
750
*
751
* Register a virtualization driver
752
*
753
* Returns the driver priority or -1 in case of error.
754
*/
755
int
756
virRegisterStateDriver(virStateDriverPtr driver)
757
{
758
if (virInitialize() < 0)
759
return -1;
760
761
if (driver == NULL) {
762
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
763
return -1;
764
}
765
766
if (virStateDriverTabCount >= MAX_DRIVERS) {
767
virLibConnError(VIR_ERR_INTERNAL_ERROR,
768
_("Too many drivers, cannot register %s"),
769
driver->name);
770
return -1;
771
}
772
773
virStateDriverTab[virStateDriverTabCount] = driver;
774
return virStateDriverTabCount++;
775
}
776
777
/**
778
* virStateInitialize:
779
* @privileged: set to 1 if running with root privilege, 0 otherwise
780
*
781
* Initialize all virtualization drivers.
782
*
783
* Returns 0 if all succeed, -1 upon any failure.
784
*/
785
int virStateInitialize(int privileged) {
786
int i, ret = 0;
787
788
if (virInitialize() < 0)
789
return -1;
790
791
for (i = 0 ; i < virStateDriverTabCount ; i++) {
792
if (virStateDriverTab[i]->initialize &&
793
virStateDriverTab[i]->initialize(privileged) < 0) {
794
VIR_ERROR(_("Initialization of %s state driver failed"),
795
virStateDriverTab[i]->name);
796
ret = -1;
797
}
798
}
799
return ret;
800
}
801
802
/**
803
* virStateCleanup:
804
*
805
* Run each virtualization driver's cleanup method.
806
*
807
* Returns 0 if all succeed, -1 upon any failure.
808
*/
809
int virStateCleanup(void) {
810
int i, ret = 0;
811
812
for (i = 0 ; i < virStateDriverTabCount ; i++) {
813
if (virStateDriverTab[i]->cleanup &&
814
virStateDriverTab[i]->cleanup() < 0)
815
ret = -1;
816
}
817
return ret;
818
}
819
820
/**
821
* virStateReload:
822
*
823
* Run each virtualization driver's reload method.
824
*
825
* Returns 0 if all succeed, -1 upon any failure.
826
*/
827
int virStateReload(void) {
828
int i, ret = 0;
829
830
for (i = 0 ; i < virStateDriverTabCount ; i++) {
831
if (virStateDriverTab[i]->reload &&
832
virStateDriverTab[i]->reload() < 0)
833
ret = -1;
834
}
835
return ret;
836
}
837
838
/**
839
* virStateActive:
840
*
841
* Run each virtualization driver's "active" method.
842
*
843
* Returns 0 if none are active, 1 if at least one is.
844
*/
845
int virStateActive(void) {
846
int i, ret = 0;
847
848
for (i = 0 ; i < virStateDriverTabCount ; i++) {
849
if (virStateDriverTab[i]->active &&
850
virStateDriverTab[i]->active())
851
ret = 1;
852
}
853
return ret;
854
}
855
856
#endif
857
858
859
860
/**
861
* virGetVersion:
862
* @libVer: return value for the library version (OUT)
863
* @type: the type of connection/driver looked at
864
* @typeVer: return value for the version of the hypervisor (OUT)
865
*
866
* Provides two information back, @libVer is the version of the library
867
* while @typeVer will be the version of the hypervisor type @type against
868
* which the library was compiled. If @type is NULL, "Xen" is assumed, if
869
* @type is unknown or not available, an error code will be returned and
870
* @typeVer will be 0.
871
*
872
* Returns -1 in case of failure, 0 otherwise, and values for @libVer and
873
* @typeVer have the format major * 1,000,000 + minor * 1,000 + release.
874
*/
875
int
876
virGetVersion(unsigned long *libVer, const char *type,
877
unsigned long *typeVer)
878
{
879
DEBUG("libVir=%p, type=%s, typeVer=%p", libVer, type, typeVer);
880
881
if (!initialized)
882
if (virInitialize() < 0)
883
goto error;
884
885
if (libVer == NULL)
886
goto error;
887
*libVer = LIBVIR_VERSION_NUMBER;
888
889
if (typeVer != NULL) {
890
if (type == NULL)
891
type = "Xen";
892
893
/* FIXME: Add _proper_ type version handling for loadable driver modules... */
894
#ifdef WITH_DRIVER_MODULES
895
*typeVer = LIBVIR_VERSION_NUMBER;
896
#else
897
*typeVer = 0;
898
899
# if WITH_XEN
900
if (STRCASEEQ(type, "Xen"))
901
*typeVer = xenUnifiedVersion();
902
# endif
903
# if WITH_TEST
904
if (STRCASEEQ(type, "Test"))
905
*typeVer = LIBVIR_VERSION_NUMBER;
906
# endif
907
# if WITH_QEMU
908
if (STRCASEEQ(type, "QEMU"))
909
*typeVer = LIBVIR_VERSION_NUMBER;
910
# endif
911
# if WITH_LXC
912
if (STRCASEEQ(type, "LXC"))
913
*typeVer = LIBVIR_VERSION_NUMBER;
914
# endif
915
# if WITH_PHYP
916
if (STRCASEEQ(type, "phyp"))
917
*typeVer = LIBVIR_VERSION_NUMBER;
918
# endif
919
# if WITH_OPENVZ
920
if (STRCASEEQ(type, "OpenVZ"))
921
*typeVer = LIBVIR_VERSION_NUMBER;
922
# endif
923
# if WITH_VMWARE
924
if (STRCASEEQ(type, "VMware"))
925
*typeVer = LIBVIR_VERSION_NUMBER;
926
# endif
927
# if WITH_VBOX
928
if (STRCASEEQ(type, "VBox"))
929
*typeVer = LIBVIR_VERSION_NUMBER;
930
# endif
931
# if WITH_UML
932
if (STRCASEEQ(type, "UML"))
933
*typeVer = LIBVIR_VERSION_NUMBER;
934
# endif
935
# if WITH_ONE
936
if (STRCASEEQ(type, "ONE"))
937
*typeVer = LIBVIR_VERSION_NUMBER;
938
# endif
939
# if WITH_ESX
940
if (STRCASEEQ(type, "ESX"))
941
*typeVer = LIBVIR_VERSION_NUMBER;
942
# endif
943
# if WITH_XENAPI
944
if (STRCASEEQ(type, "XenAPI"))
945
*typeVer = LIBVIR_VERSION_NUMBER;
946
# endif
947
# if WITH_REMOTE
948
if (STRCASEEQ(type, "Remote"))
949
*typeVer = remoteVersion();
950
# endif
951
if (*typeVer == 0) {
952
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
953
goto error;
954
}
955
#endif /* WITH_DRIVER_MODULES */
956
}
957
return 0;
958
959
error:
960
virDispatchError(NULL);
961
return -1;
962
}
963
964
static virConnectPtr
965
do_open (const char *name,
966
virConnectAuthPtr auth,
967
int flags)
968
{
969
int i, res;
970
virConnectPtr ret;
971
972
virResetLastError();
973
974
ret = virGetConnect();
975
if (ret == NULL)
976
return NULL;
977
978
/*
979
* If no URI is passed, then check for an environment string if not
980
* available probe the compiled in drivers to find a default hypervisor
981
* if detectable.
982
*/
983
if (!name || name[0] == '\0') {
984
char *defname = getenv("LIBVIRT_DEFAULT_URI");
985
if (defname && *defname) {
986
DEBUG("Using LIBVIRT_DEFAULT_URI %s", defname);
987
name = defname;
988
} else {
989
name = NULL;
990
}
991
}
992
993
if (name) {
994
/* Convert xen -> xen:/// for back compat */
995
if (STRCASEEQ(name, "xen"))
996
name = "xen:///";
997
998
/* Convert xen:// -> xen:/// because xmlParseURI cannot parse the
999
* former. This allows URIs such as xen://localhost to work.
1000
*/
1001
if (STREQ (name, "xen://"))
1002
name = "xen:///";
1003
1004
ret->uri = xmlParseURI (name);
1005
if (!ret->uri) {
1006
virLibConnError(VIR_ERR_INVALID_ARG,
1007
_("could not parse connection URI"));
1008
goto failed;
1009
}
1010
1011
DEBUG("name \"%s\" to URI components:\n"
1012
" scheme %s\n"
1013
" opaque %s\n"
1014
" authority %s\n"
1015
" server %s\n"
1016
" user %s\n"
1017
" port %d\n"
1018
" path %s\n",
1019
name,
1020
NULLSTR(ret->uri->scheme), NULLSTR(ret->uri->opaque),
1021
NULLSTR(ret->uri->authority), NULLSTR(ret->uri->server),
1022
NULLSTR(ret->uri->user), ret->uri->port,
1023
NULLSTR(ret->uri->path));
1024
} else {
1025
DEBUG0("no name, allowing driver auto-select");
1026
}
1027
1028
/* Cleansing flags */
1029
ret->flags = flags & VIR_CONNECT_RO;
1030
1031
for (i = 0; i < virDriverTabCount; i++) {
1032
/* We're going to probe the remote driver next. So we have already
1033
* probed all other client-side-only driver before, but none of them
1034
* accepted the URI.
1035
* If the scheme corresponds to a known but disabled client-side-only
1036
* driver then report a useful error, instead of a cryptic one about
1037
* not being able to connect to libvirtd or not being able to find
1038
* certificates. */
1039
if (virDriverTab[i]->no == VIR_DRV_REMOTE &&
1040
ret->uri != NULL && ret->uri->scheme != NULL &&
1041
(
1042
#ifndef WITH_PHYP
1043
STRCASEEQ(ret->uri->scheme, "phyp") ||
1044
#endif
1045
#ifndef WITH_ESX
1046
STRCASEEQ(ret->uri->scheme, "vpx") ||
1047
STRCASEEQ(ret->uri->scheme, "esx") ||
1048
STRCASEEQ(ret->uri->scheme, "gsx") ||
1049
#endif
1050
#ifndef WITH_XENAPI
1051
STRCASEEQ(ret->uri->scheme, "xenapi") ||
1052
#endif
1053
false)) {
1054
virReportErrorHelper(NULL, VIR_FROM_NONE, VIR_ERR_INVALID_ARG,
1055
__FILE__, __FUNCTION__, __LINE__,
1056
_("libvirt was built without the '%s' driver"),
1057
ret->uri->scheme);
1058
goto failed;
1059
}
1060
1061
DEBUG("trying driver %d (%s) ...",
1062
i, virDriverTab[i]->name);
1063
res = virDriverTab[i]->open (ret, auth, flags);
1064
DEBUG("driver %d %s returned %s",
1065
i, virDriverTab[i]->name,
1066
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
1067
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
1068
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
1069
if (res == VIR_DRV_OPEN_ERROR) goto failed;
1070
else if (res == VIR_DRV_OPEN_SUCCESS) {
1071
ret->driver = virDriverTab[i];
1072
break;
1073
}
1074
}
1075
1076
if (!ret->driver) {
1077
/* If we reach here, then all drivers declined the connection. */
1078
virLibConnError(VIR_ERR_NO_CONNECT,
1079
_("No connection for URI %s"),
1080
NULLSTR(name));
1081
goto failed;
1082
}
1083
1084
for (i = 0; i < virNetworkDriverTabCount; i++) {
1085
res = virNetworkDriverTab[i]->open (ret, auth, flags);
1086
DEBUG("network driver %d %s returned %s",
1087
i, virNetworkDriverTab[i]->name,
1088
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
1089
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
1090
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
1091
if (res == VIR_DRV_OPEN_ERROR) {
1092
break;
1093
} else if (res == VIR_DRV_OPEN_SUCCESS) {
1094
ret->networkDriver = virNetworkDriverTab[i];
1095
break;
1096
}
1097
}
1098
1099
for (i = 0; i < virInterfaceDriverTabCount; i++) {
1100
res = virInterfaceDriverTab[i]->open (ret, auth, flags);
1101
DEBUG("interface driver %d %s returned %s",
1102
i, virInterfaceDriverTab[i]->name,
1103
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
1104
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
1105
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
1106
if (res == VIR_DRV_OPEN_ERROR) {
1107
break;
1108
} else if (res == VIR_DRV_OPEN_SUCCESS) {
1109
ret->interfaceDriver = virInterfaceDriverTab[i];
1110
break;
1111
}
1112
}
1113
1114
/* Secondary driver for storage. Optional */
1115
for (i = 0; i < virStorageDriverTabCount; i++) {
1116
res = virStorageDriverTab[i]->open (ret, auth, flags);
1117
DEBUG("storage driver %d %s returned %s",
1118
i, virStorageDriverTab[i]->name,
1119
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
1120
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
1121
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
1122
if (res == VIR_DRV_OPEN_ERROR) {
1123
break;
1124
} else if (res == VIR_DRV_OPEN_SUCCESS) {
1125
ret->storageDriver = virStorageDriverTab[i];
1126
break;
1127
}
1128
}
1129
1130
/* Node driver (optional) */
1131
for (i = 0; i < virDeviceMonitorTabCount; i++) {
1132
res = virDeviceMonitorTab[i]->open (ret, auth, flags);
1133
DEBUG("node driver %d %s returned %s",
1134
i, virDeviceMonitorTab[i]->name,
1135
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
1136
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
1137
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
1138
if (res == VIR_DRV_OPEN_ERROR) {
1139
break;
1140
} else if (res == VIR_DRV_OPEN_SUCCESS) {
1141
ret->deviceMonitor = virDeviceMonitorTab[i];
1142
break;
1143
}
1144
}
1145
1146
/* Secret manipulation driver. Optional */
1147
for (i = 0; i < virSecretDriverTabCount; i++) {
1148
res = virSecretDriverTab[i]->open (ret, auth, flags);
1149
DEBUG("secret driver %d %s returned %s",
1150
i, virSecretDriverTab[i]->name,
1151
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
1152
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
1153
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
1154
if (res == VIR_DRV_OPEN_ERROR) {
1155
break;
1156
} else if (res == VIR_DRV_OPEN_SUCCESS) {
1157
ret->secretDriver = virSecretDriverTab[i];
1158
break;
1159
}
1160
}
1161
1162
/* Network filter driver. Optional */
1163
for (i = 0; i < virNWFilterDriverTabCount; i++) {
1164
res = virNWFilterDriverTab[i]->open (ret, auth, flags);
1165
DEBUG("nwfilter driver %d %s returned %s",
1166
i, virNWFilterDriverTab[i]->name,
1167
res == VIR_DRV_OPEN_SUCCESS ? "SUCCESS" :
1168
(res == VIR_DRV_OPEN_DECLINED ? "DECLINED" :
1169
(res == VIR_DRV_OPEN_ERROR ? "ERROR" : "unknown status")));
1170
if (res == VIR_DRV_OPEN_ERROR) {
1171
break;
1172
} else if (res == VIR_DRV_OPEN_SUCCESS) {
1173
ret->nwfilterDriver = virNWFilterDriverTab[i];
1174
break;
1175
}
1176
}
1177
1178
return ret;
1179
1180
failed:
1181
virUnrefConnect(ret);
1182
1183
return NULL;
1184
}
1185
1186
/**
1187
* virConnectOpen:
1188
* @name: URI of the hypervisor
1189
*
1190
* This function should be called first to get a connection to the
1191
* Hypervisor and xen store
1192
*
1193
* Returns a pointer to the hypervisor connection or NULL in case of error
1194
*
1195
* If @name is NULL then probing will be done to determine a suitable
1196
* default driver to activate. This involves trying each hypervisor
1197
* in turn until one successfully opens. If the LIBVIRT_DEFAULT_URI
1198
* environment variable is set, then it will be used in preference
1199
* to probing for a driver.
1200
*
1201
* If connecting to an unprivileged hypervisor driver which requires
1202
* the libvirtd daemon to be active, it will automatically be launched
1203
* if not already running. This can be prevented by setting the
1204
* environment variable LIBVIRT_AUTOSTART=0
1205
*
1206
* URIs are documented at http://libvirt.org/uri.html
1207
*/
1208
virConnectPtr
1209
virConnectOpen (const char *name)
1210
{
1211
virConnectPtr ret = NULL;
1212
if (!initialized)
1213
if (virInitialize() < 0)
1214
goto error;
1215
1216
DEBUG("name=%s", name);
1217
ret = do_open (name, NULL, 0);
1218
if (!ret)
1219
goto error;
1220
return ret;
1221
1222
error:
1223
virDispatchError(NULL);
1224
return NULL;
1225
}
1226
1227
/**
1228
* virConnectOpenReadOnly:
1229
* @name: URI of the hypervisor
1230
*
1231
* This function should be called first to get a restricted connection to the
1232
* library functionalities. The set of APIs usable are then restricted
1233
* on the available methods to control the domains.
1234
*
1235
* See virConnectOpen for notes about environment variables which can
1236
* have an effect on opening drivers
1237
*
1238
* Returns a pointer to the hypervisor connection or NULL in case of error
1239
*
1240
* URIs are documented at http://libvirt.org/uri.html
1241
*/
1242
virConnectPtr
1243
virConnectOpenReadOnly(const char *name)
1244
{
1245
virConnectPtr ret = NULL;
1246
if (!initialized)
1247
if (virInitialize() < 0)
1248
goto error;
1249
1250
DEBUG("name=%s", name);
1251
ret = do_open (name, NULL, VIR_CONNECT_RO);
1252
if (!ret)
1253
goto error;
1254
return ret;
1255
1256
error:
1257
virDispatchError(NULL);
1258
return NULL;
1259
}
1260
1261
/**
1262
* virConnectOpenAuth:
1263
* @name: URI of the hypervisor
1264
* @auth: Authenticate callback parameters
1265
* @flags: Open flags
1266
*
1267
* This function should be called first to get a connection to the
1268
* Hypervisor. If necessary, authentication will be performed fetching
1269
* credentials via the callback
1270
*
1271
* See virConnectOpen for notes about environment variables which can
1272
* have an effect on opening drivers
1273
*
1274
* Returns a pointer to the hypervisor connection or NULL in case of error
1275
*
1276
* URIs are documented at http://libvirt.org/uri.html
1277
*/
1278
virConnectPtr
1279
virConnectOpenAuth(const char *name,
1280
virConnectAuthPtr auth,
1281
int flags)
1282
{
1283
virConnectPtr ret = NULL;
1284
if (!initialized)
1285
if (virInitialize() < 0)
1286
goto error;
1287
1288
DEBUG("name=%s, auth=%p, flags=%d", NULLSTR(name), auth, flags);
1289
ret = do_open (name, auth, flags);
1290
if (!ret)
1291
goto error;
1292
return ret;
1293
1294
error:
1295
virDispatchError(NULL);
1296
return NULL;
1297
}
1298
1299
/**
1300
* virConnectClose:
1301
* @conn: pointer to the hypervisor connection
1302
*
1303
* This function closes the connection to the Hypervisor. This should
1304
* not be called if further interaction with the Hypervisor are needed
1305
* especially if there is running domain which need further monitoring by
1306
* the application.
1307
*
1308
* Returns 0 in case of success or -1 in case of error.
1309
*/
1310
int
1311
virConnectClose(virConnectPtr conn)
1312
{
1313
int ret = -1;
1314
DEBUG("conn=%p", conn);
1315
1316
virResetLastError();
1317
1318
if (!VIR_IS_CONNECT(conn)) {
1319
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1320
goto error;
1321
}
1322
1323
ret = virUnrefConnect(conn);
1324
if (ret < 0)
1325
goto error;
1326
return ret;
1327
1328
error:
1329
virDispatchError(NULL);
1330
return ret;
1331
}
1332
1333
/**
1334
* virConnectRef:
1335
* @conn: the connection to hold a reference on
1336
*
1337
* Increment the reference count on the connection. For each
1338
* additional call to this method, there shall be a corresponding
1339
* call to virConnectClose to release the reference count, once
1340
* the caller no longer needs the reference to this object.
1341
*
1342
* This method is typically useful for applications where multiple
1343
* threads are using a connection, and it is required that the
1344
* connection remain open until all threads have finished using
1345
* it. ie, each new thread using a connection would increment
1346
* the reference count.
1347
*
1348
* Returns 0 in case of success, -1 in case of failure
1349
*/
1350
int
1351
virConnectRef(virConnectPtr conn)
1352
{
1353
if ((!VIR_IS_CONNECT(conn))) {
1354
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
1355
virDispatchError(NULL);
1356
return -1;
1357
}
1358
virMutexLock(&conn->lock);
1359
DEBUG("conn=%p refs=%d", conn, conn->refs);
1360
conn->refs++;
1361
virMutexUnlock(&conn->lock);
1362
return 0;
1363
}
1364
1365
/*
1366
* Not for public use. This function is part of the internal
1367
* implementation of driver features in the remote case.
1368
*/
1369
int
1370
virDrvSupportsFeature (virConnectPtr conn, int feature)
1371
{
1372
int ret;
1373
DEBUG("conn=%p, feature=%d", conn, feature);
1374
1375
virResetLastError();
1376
1377
if (!VIR_IS_CONNECT(conn)) {
1378
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1379
virDispatchError(NULL);
1380
return -1;
1381
}
1382
1383
if (!conn->driver->supports_feature)
1384
ret = 0;
1385
else
1386
ret = conn->driver->supports_feature(conn, feature);
1387
1388
if (ret < 0)
1389
virDispatchError(conn);
1390
1391
return ret;
1392
}
1393
1394
/**
1395
* virConnectGetType:
1396
* @conn: pointer to the hypervisor connection
1397
*
1398
* Get the name of the Hypervisor software used.
1399
*
1400
* Returns NULL in case of error, a static zero terminated string otherwise.
1401
*
1402
* See also:
1403
* http://www.redhat.com/archives/libvir-list/2007-February/msg00096.html
1404
*/
1405
const char *
1406
virConnectGetType(virConnectPtr conn)
1407
{
1408
const char *ret;
1409
DEBUG("conn=%p", conn);
1410
1411
virResetLastError();
1412
1413
if (!VIR_IS_CONNECT(conn)) {
1414
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1415
virDispatchError(NULL);
1416
return NULL;
1417
}
1418
1419
if (conn->driver->type) {
1420
ret = conn->driver->type (conn);
1421
if (ret) return ret;
1422
}
1423
return conn->driver->name;
1424
}
1425
1426
/**
1427
* virConnectGetVersion:
1428
* @conn: pointer to the hypervisor connection
1429
* @hvVer: return value for the version of the running hypervisor (OUT)
1430
*
1431
* Get the version level of the Hypervisor running. This may work only with
1432
* hypervisor call, i.e. with privileged access to the hypervisor, not
1433
* with a Read-Only connection.
1434
*
1435
* Returns -1 in case of error, 0 otherwise. if the version can't be
1436
* extracted by lack of capacities returns 0 and @hvVer is 0, otherwise
1437
* @hvVer value is major * 1,000,000 + minor * 1,000 + release
1438
*/
1439
int
1440
virConnectGetVersion(virConnectPtr conn, unsigned long *hvVer)
1441
{
1442
DEBUG("conn=%p, hvVer=%p", conn, hvVer);
1443
1444
virResetLastError();
1445
1446
if (!VIR_IS_CONNECT(conn)) {
1447
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1448
virDispatchError(NULL);
1449
return -1;
1450
}
1451
1452
if (hvVer == NULL) {
1453
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
1454
goto error;
1455
}
1456
1457
if (conn->driver->version) {
1458
int ret = conn->driver->version (conn, hvVer);
1459
if (ret < 0)
1460
goto error;
1461
return ret;
1462
}
1463
1464
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
1465
1466
error:
1467
virDispatchError(conn);
1468
return -1;
1469
}
1470
1471
/**
1472
* virConnectGetLibVersion:
1473
* @conn: pointer to the hypervisor connection
1474
* @libVer: returns the libvirt library version used on the connection (OUT)
1475
*
1476
* Provides @libVer, which is the version of libvirt used by the
1477
* daemon running on the @conn host
1478
*
1479
* Returns -1 in case of failure, 0 otherwise, and values for @libVer have
1480
* the format major * 1,000,000 + minor * 1,000 + release.
1481
*/
1482
int
1483
virConnectGetLibVersion(virConnectPtr conn, unsigned long *libVer)
1484
{
1485
int ret = -1;
1486
DEBUG("conn=%p, libVir=%p", conn, libVer);
1487
1488
virResetLastError();
1489
1490
if (!VIR_IS_CONNECT(conn)) {
1491
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1492
virDispatchError(NULL);
1493
return -1;
1494
}
1495
1496
if (libVer == NULL) {
1497
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
1498
goto error;
1499
}
1500
1501
if (conn->driver->libvirtVersion) {
1502
ret = conn->driver->libvirtVersion(conn, libVer);
1503
if (ret < 0)
1504
goto error;
1505
return ret;
1506
}
1507
1508
*libVer = LIBVIR_VERSION_NUMBER;
1509
return 0;
1510
1511
error:
1512
virDispatchError(conn);
1513
return ret;
1514
}
1515
1516
/**
1517
* virConnectGetHostname:
1518
* @conn: pointer to a hypervisor connection
1519
*
1520
* This returns the system hostname on which the hypervisor is
1521
* running (the result of the gethostname system call). If
1522
* we are connected to a remote system, then this returns the
1523
* hostname of the remote system.
1524
*
1525
* Returns the hostname which must be freed by the caller, or
1526
* NULL if there was an error.
1527
*/
1528
char *
1529
virConnectGetHostname (virConnectPtr conn)
1530
{
1531
DEBUG("conn=%p", conn);
1532
1533
virResetLastError();
1534
1535
if (!VIR_IS_CONNECT(conn)) {
1536
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1537
virDispatchError(NULL);
1538
return NULL;
1539
}
1540
1541
if (conn->driver->getHostname) {
1542
char *ret = conn->driver->getHostname (conn);
1543
if (!ret)
1544
goto error;
1545
return ret;
1546
}
1547
1548
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
1549
1550
error:
1551
virDispatchError(conn);
1552
return NULL;
1553
}
1554
1555
/**
1556
* virConnectGetURI:
1557
* @conn: pointer to a hypervisor connection
1558
*
1559
* This returns the URI (name) of the hypervisor connection.
1560
* Normally this is the same as or similar to the string passed
1561
* to the virConnectOpen/virConnectOpenReadOnly call, but
1562
* the driver may make the URI canonical. If name == NULL
1563
* was passed to virConnectOpen, then the driver will return
1564
* a non-NULL URI which can be used to connect to the same
1565
* hypervisor later.
1566
*
1567
* Returns the URI string which must be freed by the caller, or
1568
* NULL if there was an error.
1569
*/
1570
char *
1571
virConnectGetURI (virConnectPtr conn)
1572
{
1573
char *name;
1574
DEBUG("conn=%p", conn);
1575
1576
virResetLastError();
1577
1578
if (!VIR_IS_CONNECT(conn)) {
1579
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1580
virDispatchError(NULL);
1581
return NULL;
1582
}
1583
1584
name = (char *)xmlSaveUri(conn->uri);
1585
if (!name) {
1586
virReportOOMError();
1587
goto error;
1588
}
1589
return name;
1590
1591
error:
1592
virDispatchError(conn);
1593
return NULL;
1594
}
1595
1596
/**
1597
* virConnectGetSysinfo:
1598
* @conn: pointer to a hypervisor connection
1599
* @flags: callers should always pass 0
1600
*
1601
* This returns the XML description of the sysinfo details for the
1602
* host on which the hypervisor is running, in the same format as the
1603
* <sysinfo> element of a domain XML. This information is generally
1604
* available only for hypervisors running with root privileges.
1605
*
1606
* Returns the XML string which must be freed by the caller, or
1607
* NULL if there was an error.
1608
*/
1609
char *
1610
virConnectGetSysinfo (virConnectPtr conn, unsigned int flags)
1611
{
1612
DEBUG("conn=%p", conn);
1613
1614
virResetLastError();
1615
1616
if (!VIR_IS_CONNECT(conn)) {
1617
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1618
virDispatchError(NULL);
1619
return NULL;
1620
}
1621
1622
if (conn->driver->getSysinfo) {
1623
char *ret = conn->driver->getSysinfo (conn, flags);
1624
if (!ret)
1625
goto error;
1626
return ret;
1627
}
1628
1629
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
1630
1631
error:
1632
virDispatchError(conn);
1633
return NULL;
1634
}
1635
1636
/**
1637
* virConnectGetMaxVcpus:
1638
* @conn: pointer to the hypervisor connection
1639
* @type: value of the 'type' attribute in the <domain> element
1640
*
1641
* Provides the maximum number of virtual CPUs supported for a guest VM of a
1642
* specific type. The 'type' parameter here corresponds to the 'type'
1643
* attribute in the <domain> element of the XML.
1644
*
1645
* Returns the maximum of virtual CPU or -1 in case of error.
1646
*/
1647
int
1648
virConnectGetMaxVcpus(virConnectPtr conn,
1649
const char *type)
1650
{
1651
DEBUG("conn=%p, type=%s", conn, type);
1652
1653
virResetLastError();
1654
1655
if (!VIR_IS_CONNECT(conn)) {
1656
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1657
virDispatchError(NULL);
1658
return -1;
1659
}
1660
1661
if (conn->driver->getMaxVcpus) {
1662
int ret = conn->driver->getMaxVcpus (conn, type);
1663
if (ret < 0)
1664
goto error;
1665
return ret;
1666
}
1667
1668
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
1669
error:
1670
virDispatchError(conn);
1671
return -1;
1672
}
1673
1674
/**
1675
* virConnectListDomains:
1676
* @conn: pointer to the hypervisor connection
1677
* @ids: array to collect the list of IDs of active domains
1678
* @maxids: size of @ids
1679
*
1680
* Collect the list of active domains, and store their ID in @maxids
1681
*
1682
* Returns the number of domain found or -1 in case of error
1683
*/
1684
int
1685
virConnectListDomains(virConnectPtr conn, int *ids, int maxids)
1686
{
1687
DEBUG("conn=%p, ids=%p, maxids=%d", conn, ids, maxids);
1688
1689
virResetLastError();
1690
1691
if (!VIR_IS_CONNECT(conn)) {
1692
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1693
virDispatchError(NULL);
1694
return -1;
1695
}
1696
1697
if ((ids == NULL) || (maxids < 0)) {
1698
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
1699
goto error;
1700
}
1701
1702
if (conn->driver->listDomains) {
1703
int ret = conn->driver->listDomains (conn, ids, maxids);
1704
if (ret < 0)
1705
goto error;
1706
return ret;
1707
}
1708
1709
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
1710
error:
1711
virDispatchError(conn);
1712
return -1;
1713
}
1714
1715
/**
1716
* virConnectNumOfDomains:
1717
* @conn: pointer to the hypervisor connection
1718
*
1719
* Provides the number of active domains.
1720
*
1721
* Returns the number of domain found or -1 in case of error
1722
*/
1723
int
1724
virConnectNumOfDomains(virConnectPtr conn)
1725
{
1726
DEBUG("conn=%p", conn);
1727
1728
virResetLastError();
1729
1730
if (!VIR_IS_CONNECT(conn)) {
1731
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1732
virDispatchError(NULL);
1733
return -1;
1734
}
1735
1736
if (conn->driver->numOfDomains) {
1737
int ret = conn->driver->numOfDomains (conn);
1738
if (ret < 0)
1739
goto error;
1740
return ret;
1741
}
1742
1743
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
1744
error:
1745
virDispatchError(conn);
1746
return -1;
1747
}
1748
1749
/**
1750
* virDomainGetConnect:
1751
* @dom: pointer to a domain
1752
*
1753
* Provides the connection pointer associated with a domain. The
1754
* reference counter on the connection is not increased by this
1755
* call.
1756
*
1757
* WARNING: When writing libvirt bindings in other languages, do
1758
* not use this function. Instead, store the connection and
1759
* the domain object together.
1760
*
1761
* Returns the virConnectPtr or NULL in case of failure.
1762
*/
1763
virConnectPtr
1764
virDomainGetConnect (virDomainPtr dom)
1765
{
1766
VIR_DOMAIN_DEBUG0(dom);
1767
1768
virResetLastError();
1769
1770
if (!VIR_IS_CONNECTED_DOMAIN (dom)) {
1771
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
1772
virDispatchError(NULL);
1773
return NULL;
1774
}
1775
return dom->conn;
1776
}
1777
1778
/**
1779
* virDomainCreateXML:
1780
* @conn: pointer to the hypervisor connection
1781
* @xmlDesc: string containing an XML description of the domain
1782
* @flags: bitwise-or of supported virDomainCreateFlags
1783
*
1784
* Launch a new guest domain, based on an XML description similar
1785
* to the one returned by virDomainGetXMLDesc()
1786
* This function may requires privileged access to the hypervisor.
1787
* The domain is not persistent, so its definition will disappear when it
1788
* is destroyed, or if the host is restarted (see virDomainDefineXML() to
1789
* define persistent domains).
1790
*
1791
* Returns a new domain object or NULL in case of failure
1792
*/
1793
virDomainPtr
1794
virDomainCreateXML(virConnectPtr conn, const char *xmlDesc,
1795
unsigned int flags)
1796
{
1797
DEBUG("conn=%p, xmlDesc=%s, flags=%d", conn, xmlDesc, flags);
1798
1799
virResetLastError();
1800
1801
if (!VIR_IS_CONNECT(conn)) {
1802
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1803
virDispatchError(NULL);
1804
return NULL;
1805
}
1806
if (xmlDesc == NULL) {
1807
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
1808
goto error;
1809
}
1810
if (conn->flags & VIR_CONNECT_RO) {
1811
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
1812
goto error;
1813
}
1814
1815
if (conn->driver->domainCreateXML) {
1816
virDomainPtr ret;
1817
ret = conn->driver->domainCreateXML (conn, xmlDesc, flags);
1818
if (!ret)
1819
goto error;
1820
return ret;
1821
}
1822
1823
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
1824
error:
1825
virDispatchError(conn);
1826
return NULL;
1827
}
1828
1829
/**
1830
* virDomainCreateLinux:
1831
* @conn: pointer to the hypervisor connection
1832
* @xmlDesc: string containing an XML description of the domain
1833
* @flags: callers should always pass 0
1834
*
1835
* Deprecated after 0.4.6.
1836
* Renamed to virDomainCreateXML() providing identical functionality.
1837
* This existing name will left indefinitely for API compatibility.
1838
*
1839
* Returns a new domain object or NULL in case of failure
1840
*/
1841
virDomainPtr
1842
virDomainCreateLinux(virConnectPtr conn, const char *xmlDesc,
1843
unsigned int flags)
1844
{
1845
return virDomainCreateXML(conn, xmlDesc, flags);
1846
}
1847
1848
/**
1849
* virDomainLookupByID:
1850
* @conn: pointer to the hypervisor connection
1851
* @id: the domain ID number
1852
*
1853
* Try to find a domain based on the hypervisor ID number
1854
* Note that this won't work for inactive domains which have an ID of -1,
1855
* in that case a lookup based on the Name or UUId need to be done instead.
1856
*
1857
* Returns a new domain object or NULL in case of failure. If the
1858
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
1859
*/
1860
virDomainPtr
1861
virDomainLookupByID(virConnectPtr conn, int id)
1862
{
1863
DEBUG("conn=%p, id=%d", conn, id);
1864
1865
virResetLastError();
1866
1867
if (!VIR_IS_CONNECT(conn)) {
1868
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1869
virDispatchError(NULL);
1870
return NULL;
1871
}
1872
if (id < 0) {
1873
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
1874
goto error;
1875
}
1876
1877
if (conn->driver->domainLookupByID) {
1878
virDomainPtr ret;
1879
ret = conn->driver->domainLookupByID (conn, id);
1880
if (!ret)
1881
goto error;
1882
return ret;
1883
}
1884
1885
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
1886
1887
error:
1888
virDispatchError(conn);
1889
return NULL;
1890
}
1891
1892
/**
1893
* virDomainLookupByUUID:
1894
* @conn: pointer to the hypervisor connection
1895
* @uuid: the raw UUID for the domain
1896
*
1897
* Try to lookup a domain on the given hypervisor based on its UUID.
1898
*
1899
* Returns a new domain object or NULL in case of failure. If the
1900
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
1901
*/
1902
virDomainPtr
1903
virDomainLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
1904
{
1905
char uuidstr[VIR_UUID_STRING_BUFLEN];
1906
virUUIDFormat(uuid, uuidstr);
1907
1908
DEBUG("conn=%p, uuid=%s", conn, uuidstr);
1909
1910
virResetLastError();
1911
1912
if (!VIR_IS_CONNECT(conn)) {
1913
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1914
virDispatchError(NULL);
1915
return NULL;
1916
}
1917
if (uuid == NULL) {
1918
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
1919
goto error;
1920
}
1921
1922
if (conn->driver->domainLookupByUUID) {
1923
virDomainPtr ret;
1924
ret = conn->driver->domainLookupByUUID (conn, uuid);
1925
if (!ret)
1926
goto error;
1927
return ret;
1928
}
1929
1930
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
1931
1932
error:
1933
virDispatchError(conn);
1934
return NULL;
1935
}
1936
1937
/**
1938
* virDomainLookupByUUIDString:
1939
* @conn: pointer to the hypervisor connection
1940
* @uuidstr: the string UUID for the domain
1941
*
1942
* Try to lookup a domain on the given hypervisor based on its UUID.
1943
*
1944
* Returns a new domain object or NULL in case of failure. If the
1945
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
1946
*/
1947
virDomainPtr
1948
virDomainLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
1949
{
1950
unsigned char uuid[VIR_UUID_BUFLEN];
1951
DEBUG("conn=%p, uuidstr=%s", conn, uuidstr);
1952
1953
virResetLastError();
1954
1955
if (!VIR_IS_CONNECT(conn)) {
1956
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1957
virDispatchError(NULL);
1958
return NULL;
1959
}
1960
if (uuidstr == NULL) {
1961
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
1962
goto error;
1963
}
1964
1965
if (virUUIDParse(uuidstr, uuid) < 0) {
1966
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
1967
goto error;
1968
}
1969
1970
return virDomainLookupByUUID(conn, &uuid[0]);
1971
1972
error:
1973
virDispatchError(conn);
1974
return NULL;
1975
}
1976
1977
/**
1978
* virDomainLookupByName:
1979
* @conn: pointer to the hypervisor connection
1980
* @name: name for the domain
1981
*
1982
* Try to lookup a domain on the given hypervisor based on its name.
1983
*
1984
* Returns a new domain object or NULL in case of failure. If the
1985
* domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised.
1986
*/
1987
virDomainPtr
1988
virDomainLookupByName(virConnectPtr conn, const char *name)
1989
{
1990
DEBUG("conn=%p, name=%s", conn, name);
1991
1992
virResetLastError();
1993
1994
if (!VIR_IS_CONNECT(conn)) {
1995
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
1996
virDispatchError(NULL);
1997
return NULL;
1998
}
1999
if (name == NULL) {
2000
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
2001
goto error;
2002
}
2003
2004
if (conn->driver->domainLookupByName) {
2005
virDomainPtr dom;
2006
dom = conn->driver->domainLookupByName (conn, name);
2007
if (!dom)
2008
goto error;
2009
return dom;
2010
}
2011
2012
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2013
2014
error:
2015
virDispatchError(conn);
2016
return NULL;
2017
}
2018
2019
/**
2020
* virDomainDestroy:
2021
* @domain: a domain object
2022
*
2023
* Destroy the domain object. The running instance is shutdown if not down
2024
* already and all resources used by it are given back to the hypervisor. This
2025
* does not free the associated virDomainPtr object.
2026
* This function may require privileged access
2027
*
2028
* Returns 0 in case of success and -1 in case of failure.
2029
*/
2030
int
2031
virDomainDestroy(virDomainPtr domain)
2032
{
2033
virConnectPtr conn;
2034
2035
VIR_DOMAIN_DEBUG0(domain);
2036
2037
virResetLastError();
2038
2039
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2040
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2041
virDispatchError(NULL);
2042
return -1;
2043
}
2044
2045
conn = domain->conn;
2046
if (conn->flags & VIR_CONNECT_RO) {
2047
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2048
goto error;
2049
}
2050
2051
if (conn->driver->domainDestroy) {
2052
int ret;
2053
ret = conn->driver->domainDestroy (domain);
2054
if (ret < 0)
2055
goto error;
2056
return ret;
2057
}
2058
2059
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2060
2061
error:
2062
virDispatchError(conn);
2063
return -1;
2064
}
2065
2066
/**
2067
* virDomainFree:
2068
* @domain: a domain object
2069
*
2070
* Free the domain object. The running instance is kept alive.
2071
* The data structure is freed and should not be used thereafter.
2072
*
2073
* Returns 0 in case of success and -1 in case of failure.
2074
*/
2075
int
2076
virDomainFree(virDomainPtr domain)
2077
{
2078
VIR_DOMAIN_DEBUG0(domain);
2079
2080
virResetLastError();
2081
2082
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2083
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2084
virDispatchError(NULL);
2085
return -1;
2086
}
2087
if (virUnrefDomain(domain) < 0) {
2088
virDispatchError(NULL);
2089
return -1;
2090
}
2091
return 0;
2092
}
2093
2094
/**
2095
* virDomainRef:
2096
* @domain: the domain to hold a reference on
2097
*
2098
* Increment the reference count on the domain. For each
2099
* additional call to this method, there shall be a corresponding
2100
* call to virDomainFree to release the reference count, once
2101
* the caller no longer needs the reference to this object.
2102
*
2103
* This method is typically useful for applications where multiple
2104
* threads are using a connection, and it is required that the
2105
* connection remain open until all threads have finished using
2106
* it. ie, each new thread using a domain would increment
2107
* the reference count.
2108
*
2109
* Returns 0 in case of success and -1 in case of failure.
2110
*/
2111
int
2112
virDomainRef(virDomainPtr domain)
2113
{
2114
if ((!VIR_IS_CONNECTED_DOMAIN(domain))) {
2115
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
2116
virDispatchError(NULL);
2117
return -1;
2118
}
2119
virMutexLock(&domain->conn->lock);
2120
VIR_DOMAIN_DEBUG(domain, "refs=%d", domain->refs);
2121
domain->refs++;
2122
virMutexUnlock(&domain->conn->lock);
2123
return 0;
2124
}
2125
2126
2127
/**
2128
* virDomainSuspend:
2129
* @domain: a domain object
2130
*
2131
* Suspends an active domain, the process is frozen without further access
2132
* to CPU resources and I/O but the memory used by the domain at the
2133
* hypervisor level will stay allocated. Use virDomainResume() to reactivate
2134
* the domain.
2135
* This function may requires privileged access.
2136
*
2137
* Returns 0 in case of success and -1 in case of failure.
2138
*/
2139
int
2140
virDomainSuspend(virDomainPtr domain)
2141
{
2142
virConnectPtr conn;
2143
2144
VIR_DOMAIN_DEBUG0(domain);
2145
2146
virResetLastError();
2147
2148
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2149
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2150
virDispatchError(NULL);
2151
return -1;
2152
}
2153
if (domain->conn->flags & VIR_CONNECT_RO) {
2154
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2155
goto error;
2156
}
2157
2158
conn = domain->conn;
2159
2160
if (conn->driver->domainSuspend) {
2161
int ret;
2162
ret = conn->driver->domainSuspend (domain);
2163
if (ret < 0)
2164
goto error;
2165
return ret;
2166
}
2167
2168
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2169
2170
error:
2171
virDispatchError(domain->conn);
2172
return -1;
2173
}
2174
2175
/**
2176
* virDomainResume:
2177
* @domain: a domain object
2178
*
2179
* Resume a suspended domain, the process is restarted from the state where
2180
* it was frozen by calling virSuspendDomain().
2181
* This function may requires privileged access
2182
*
2183
* Returns 0 in case of success and -1 in case of failure.
2184
*/
2185
int
2186
virDomainResume(virDomainPtr domain)
2187
{
2188
virConnectPtr conn;
2189
2190
VIR_DOMAIN_DEBUG0(domain);
2191
2192
virResetLastError();
2193
2194
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2195
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2196
virDispatchError(NULL);
2197
return -1;
2198
}
2199
if (domain->conn->flags & VIR_CONNECT_RO) {
2200
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2201
goto error;
2202
}
2203
2204
conn = domain->conn;
2205
2206
if (conn->driver->domainResume) {
2207
int ret;
2208
ret = conn->driver->domainResume (domain);
2209
if (ret < 0)
2210
goto error;
2211
return ret;
2212
}
2213
2214
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2215
2216
error:
2217
virDispatchError(domain->conn);
2218
return -1;
2219
}
2220
2221
/**
2222
* virDomainSave:
2223
* @domain: a domain object
2224
* @to: path for the output file
2225
*
2226
* This method will suspend a domain and save its memory contents to
2227
* a file on disk. After the call, if successful, the domain is not
2228
* listed as running anymore (this may be a problem).
2229
* Use virDomainRestore() to restore a domain after saving.
2230
*
2231
* Returns 0 in case of success and -1 in case of failure.
2232
*/
2233
int
2234
virDomainSave(virDomainPtr domain, const char *to)
2235
{
2236
char filepath[4096];
2237
virConnectPtr conn;
2238
2239
VIR_DOMAIN_DEBUG(domain, "to=%s", to);
2240
2241
virResetLastError();
2242
2243
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2244
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2245
virDispatchError(NULL);
2246
return -1;
2247
}
2248
if (domain->conn->flags & VIR_CONNECT_RO) {
2249
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2250
goto error;
2251
}
2252
conn = domain->conn;
2253
if (to == NULL) {
2254
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
2255
goto error;
2256
}
2257
2258
/*
2259
* We must absolutize the file path as the save is done out of process
2260
* TODO: check for URI when libxml2 is linked in.
2261
*/
2262
if (to[0] != '/') {
2263
unsigned int len, t;
2264
2265
t = strlen(to);
2266
if (getcwd(filepath, sizeof(filepath) - (t + 3)) == NULL)
2267
return -1;
2268
len = strlen(filepath);
2269
/* that should be covered by getcwd() semantic, but be 100% sure */
2270
if (len > sizeof(filepath) - (t + 3))
2271
return -1;
2272
filepath[len] = '/';
2273
strcpy(&filepath[len + 1], to);
2274
to = &filepath[0];
2275
2276
}
2277
2278
if (conn->driver->domainSave) {
2279
int ret;
2280
ret = conn->driver->domainSave (domain, to);
2281
if (ret < 0)
2282
goto error;
2283
return ret;
2284
}
2285
2286
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2287
2288
error:
2289
virDispatchError(domain->conn);
2290
return -1;
2291
}
2292
2293
/**
2294
* virDomainRestore:
2295
* @conn: pointer to the hypervisor connection
2296
* @from: path to the
2297
*
2298
* This method will restore a domain saved to disk by virDomainSave().
2299
*
2300
* Returns 0 in case of success and -1 in case of failure.
2301
*/
2302
int
2303
virDomainRestore(virConnectPtr conn, const char *from)
2304
{
2305
char filepath[4096];
2306
DEBUG("conn=%p, from=%s", conn, from);
2307
2308
virResetLastError();
2309
2310
if (!VIR_IS_CONNECT(conn)) {
2311
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
2312
virDispatchError(NULL);
2313
return -1;
2314
}
2315
if (conn->flags & VIR_CONNECT_RO) {
2316
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2317
goto error;
2318
}
2319
if (from == NULL) {
2320
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
2321
goto error;
2322
}
2323
2324
/*
2325
* We must absolutize the file path as the restore is done out of process
2326
* TODO: check for URI when libxml2 is linked in.
2327
*/
2328
if (from[0] != '/') {
2329
unsigned int len, t;
2330
2331
t = strlen(from);
2332
if (getcwd(filepath, sizeof(filepath) - (t + 3)) == NULL) {
2333
virLibConnError(VIR_ERR_SYSTEM_ERROR,
2334
_("cannot get working directory"));
2335
goto error;
2336
}
2337
len = strlen(filepath);
2338
/* that should be covered by getcwd() semantic, but be 100% sure */
2339
if (len > sizeof(filepath) - (t + 3)) {
2340
virLibConnError(VIR_ERR_INTERNAL_ERROR,
2341
_("path too long"));
2342
goto error;
2343
}
2344
filepath[len] = '/';
2345
strcpy(&filepath[len + 1], from);
2346
from = &filepath[0];
2347
}
2348
2349
if (conn->driver->domainRestore) {
2350
int ret;
2351
ret = conn->driver->domainRestore (conn, from);
2352
if (ret < 0)
2353
goto error;
2354
return ret;
2355
}
2356
2357
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2358
2359
error:
2360
virDispatchError(conn);
2361
return -1;
2362
}
2363
2364
/**
2365
* virDomainCoreDump:
2366
* @domain: a domain object
2367
* @to: path for the core file
2368
* @flags: extra flags, currently unused
2369
*
2370
* This method will dump the core of a domain on a given file for analysis.
2371
* Note that for remote Xen Daemon the file path will be interpreted in
2372
* the remote host.
2373
*
2374
* Returns 0 in case of success and -1 in case of failure.
2375
*/
2376
int
2377
virDomainCoreDump(virDomainPtr domain, const char *to, int flags)
2378
{
2379
char filepath[4096];
2380
virConnectPtr conn;
2381
2382
VIR_DOMAIN_DEBUG(domain, "to=%s, flags=%d", to, flags);
2383
2384
virResetLastError();
2385
2386
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2387
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2388
virDispatchError(NULL);
2389
return -1;
2390
}
2391
if (domain->conn->flags & VIR_CONNECT_RO) {
2392
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2393
goto error;
2394
}
2395
conn = domain->conn;
2396
if (to == NULL) {
2397
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
2398
goto error;
2399
}
2400
2401
/*
2402
* We must absolutize the file path as the save is done out of process
2403
* TODO: check for URI when libxml2 is linked in.
2404
*/
2405
if (to[0] != '/') {
2406
unsigned int len, t;
2407
2408
t = strlen(to);
2409
if (getcwd(filepath, sizeof(filepath) - (t + 3)) == NULL) {
2410
virLibDomainError(VIR_ERR_SYSTEM_ERROR,
2411
_("cannot get current directory"));
2412
goto error;
2413
}
2414
len = strlen(filepath);
2415
/* that should be covered by getcwd() semantic, but be 100% sure */
2416
if (len > sizeof(filepath) - (t + 3)) {
2417
virLibDomainError(VIR_ERR_INTERNAL_ERROR,
2418
_("path too long"));
2419
goto error;
2420
}
2421
filepath[len] = '/';
2422
strcpy(&filepath[len + 1], to);
2423
to = &filepath[0];
2424
2425
}
2426
2427
if (conn->driver->domainCoreDump) {
2428
int ret;
2429
ret = conn->driver->domainCoreDump (domain, to, flags);
2430
if (ret < 0)
2431
goto error;
2432
return ret;
2433
}
2434
2435
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2436
2437
error:
2438
virDispatchError(domain->conn);
2439
return -1;
2440
}
2441
2442
/**
2443
* virDomainShutdown:
2444
* @domain: a domain object
2445
*
2446
* Shutdown a domain, the domain object is still usable there after but
2447
* the domain OS is being stopped. Note that the guest OS may ignore the
2448
* request.
2449
*
2450
* TODO: should we add an option for reboot, knowing it may not be doable
2451
* in the general case ?
2452
*
2453
* Returns 0 in case of success and -1 in case of failure.
2454
*/
2455
int
2456
virDomainShutdown(virDomainPtr domain)
2457
{
2458
virConnectPtr conn;
2459
2460
VIR_DOMAIN_DEBUG0(domain);
2461
2462
virResetLastError();
2463
2464
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2465
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2466
virDispatchError(NULL);
2467
return -1;
2468
}
2469
if (domain->conn->flags & VIR_CONNECT_RO) {
2470
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2471
goto error;
2472
}
2473
2474
conn = domain->conn;
2475
2476
if (conn->driver->domainShutdown) {
2477
int ret;
2478
ret = conn->driver->domainShutdown (domain);
2479
if (ret < 0)
2480
goto error;
2481
return ret;
2482
}
2483
2484
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2485
2486
error:
2487
virDispatchError(domain->conn);
2488
return -1;
2489
}
2490
2491
/**
2492
* virDomainReboot:
2493
* @domain: a domain object
2494
* @flags: extra flags for the reboot operation, not used yet
2495
*
2496
* Reboot a domain, the domain object is still usable there after but
2497
* the domain OS is being stopped for a restart.
2498
* Note that the guest OS may ignore the request.
2499
*
2500
* Returns 0 in case of success and -1 in case of failure.
2501
*/
2502
int
2503
virDomainReboot(virDomainPtr domain, unsigned int flags)
2504
{
2505
virConnectPtr conn;
2506
2507
VIR_DOMAIN_DEBUG(domain, "flags=%u", flags);
2508
2509
virResetLastError();
2510
2511
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2512
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2513
virDispatchError(NULL);
2514
return -1;
2515
}
2516
if (domain->conn->flags & VIR_CONNECT_RO) {
2517
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2518
goto error;
2519
}
2520
2521
conn = domain->conn;
2522
2523
if (conn->driver->domainReboot) {
2524
int ret;
2525
ret = conn->driver->domainReboot (domain, flags);
2526
if (ret < 0)
2527
goto error;
2528
return ret;
2529
}
2530
2531
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2532
2533
error:
2534
virDispatchError(domain->conn);
2535
return -1;
2536
}
2537
2538
/**
2539
* virDomainGetName:
2540
* @domain: a domain object
2541
*
2542
* Get the public name for that domain
2543
*
2544
* Returns a pointer to the name or NULL, the string need not be deallocated
2545
* its lifetime will be the same as the domain object.
2546
*/
2547
const char *
2548
virDomainGetName(virDomainPtr domain)
2549
{
2550
DEBUG("domain=%p", domain);
2551
2552
virResetLastError();
2553
2554
if (!VIR_IS_DOMAIN(domain)) {
2555
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2556
virDispatchError(NULL);
2557
return NULL;
2558
}
2559
return domain->name;
2560
}
2561
2562
/**
2563
* virDomainGetUUID:
2564
* @domain: a domain object
2565
* @uuid: pointer to a VIR_UUID_BUFLEN bytes array
2566
*
2567
* Get the UUID for a domain
2568
*
2569
* Returns -1 in case of error, 0 in case of success
2570
*/
2571
int
2572
virDomainGetUUID(virDomainPtr domain, unsigned char *uuid)
2573
{
2574
VIR_DOMAIN_DEBUG(domain, "uuid=%p", uuid);
2575
2576
virResetLastError();
2577
2578
if (!VIR_IS_DOMAIN(domain)) {
2579
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2580
virDispatchError(NULL);
2581
return -1;
2582
}
2583
if (uuid == NULL) {
2584
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
2585
virDispatchError(domain->conn);
2586
return -1;
2587
}
2588
2589
memcpy(uuid, &domain->uuid[0], VIR_UUID_BUFLEN);
2590
2591
return 0;
2592
}
2593
2594
/**
2595
* virDomainGetUUIDString:
2596
* @domain: a domain object
2597
* @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
2598
*
2599
* Get the UUID for a domain as string. For more information about
2600
* UUID see RFC4122.
2601
*
2602
* Returns -1 in case of error, 0 in case of success
2603
*/
2604
int
2605
virDomainGetUUIDString(virDomainPtr domain, char *buf)
2606
{
2607
unsigned char uuid[VIR_UUID_BUFLEN];
2608
2609
VIR_DOMAIN_DEBUG(domain, "buf=%p", buf);
2610
2611
virResetLastError();
2612
2613
if (!VIR_IS_DOMAIN(domain)) {
2614
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2615
virDispatchError(NULL);
2616
return -1;
2617
}
2618
if (buf == NULL) {
2619
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
2620
goto error;
2621
}
2622
2623
if (virDomainGetUUID(domain, &uuid[0]))
2624
goto error;
2625
2626
virUUIDFormat(uuid, buf);
2627
return 0;
2628
2629
error:
2630
virDispatchError(domain->conn);
2631
return -1;
2632
}
2633
2634
/**
2635
* virDomainGetID:
2636
* @domain: a domain object
2637
*
2638
* Get the hypervisor ID number for the domain
2639
*
2640
* Returns the domain ID number or (unsigned int) -1 in case of error
2641
*/
2642
unsigned int
2643
virDomainGetID(virDomainPtr domain)
2644
{
2645
VIR_DOMAIN_DEBUG0(domain);
2646
2647
virResetLastError();
2648
2649
if (!VIR_IS_DOMAIN(domain)) {
2650
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2651
virDispatchError(NULL);
2652
return (unsigned int)-1;
2653
}
2654
return domain->id;
2655
}
2656
2657
/**
2658
* virDomainGetOSType:
2659
* @domain: a domain object
2660
*
2661
* Get the type of domain operation system.
2662
*
2663
* Returns the new string or NULL in case of error, the string must be
2664
* freed by the caller.
2665
*/
2666
char *
2667
virDomainGetOSType(virDomainPtr domain)
2668
{
2669
virConnectPtr conn;
2670
2671
VIR_DOMAIN_DEBUG0(domain);
2672
2673
virResetLastError();
2674
2675
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2676
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2677
virDispatchError(NULL);
2678
return NULL;
2679
}
2680
2681
conn = domain->conn;
2682
2683
if (conn->driver->domainGetOSType) {
2684
char *ret;
2685
ret = conn->driver->domainGetOSType (domain);
2686
if (!ret)
2687
goto error;
2688
return ret;
2689
}
2690
2691
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2692
2693
error:
2694
virDispatchError(domain->conn);
2695
return NULL;
2696
}
2697
2698
/**
2699
* virDomainGetMaxMemory:
2700
* @domain: a domain object or NULL
2701
*
2702
* Retrieve the maximum amount of physical memory allocated to a
2703
* domain. If domain is NULL, then this get the amount of memory reserved
2704
* to Domain0 i.e. the domain where the application runs.
2705
*
2706
* Returns the memory size in kilobytes or 0 in case of error.
2707
*/
2708
unsigned long
2709
virDomainGetMaxMemory(virDomainPtr domain)
2710
{
2711
virConnectPtr conn;
2712
2713
VIR_DOMAIN_DEBUG0(domain);
2714
2715
virResetLastError();
2716
2717
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2718
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2719
virDispatchError(NULL);
2720
return 0;
2721
}
2722
2723
conn = domain->conn;
2724
2725
if (conn->driver->domainGetMaxMemory) {
2726
unsigned long ret;
2727
ret = conn->driver->domainGetMaxMemory (domain);
2728
if (ret == 0)
2729
goto error;
2730
return ret;
2731
}
2732
2733
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2734
2735
error:
2736
virDispatchError(domain->conn);
2737
return 0;
2738
}
2739
2740
/**
2741
* virDomainSetMaxMemory:
2742
* @domain: a domain object or NULL
2743
* @memory: the memory size in kilobytes
2744
*
2745
* Dynamically change the maximum amount of physical memory allocated to a
2746
* domain. If domain is NULL, then this change the amount of memory reserved
2747
* to Domain0 i.e. the domain where the application runs.
2748
* This function requires privileged access to the hypervisor.
2749
*
2750
* This command only changes the runtime configuration of the domain,
2751
* so can only be called on an active domain.
2752
*
2753
* Returns 0 in case of success and -1 in case of failure.
2754
*/
2755
int
2756
virDomainSetMaxMemory(virDomainPtr domain, unsigned long memory)
2757
{
2758
virConnectPtr conn;
2759
2760
VIR_DOMAIN_DEBUG(domain, "memory=%lu", memory);
2761
2762
virResetLastError();
2763
2764
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2765
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2766
virDispatchError(NULL);
2767
return -1;
2768
}
2769
if (domain->conn->flags & VIR_CONNECT_RO) {
2770
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2771
goto error;
2772
}
2773
if (memory < 4096) {
2774
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
2775
goto error;
2776
}
2777
conn = domain->conn;
2778
2779
if (conn->driver->domainSetMaxMemory) {
2780
int ret;
2781
ret = conn->driver->domainSetMaxMemory (domain, memory);
2782
if (ret < 0)
2783
goto error;
2784
return ret;
2785
}
2786
2787
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2788
2789
error:
2790
virDispatchError(domain->conn);
2791
return -1;
2792
}
2793
2794
/**
2795
* virDomainSetMemory:
2796
* @domain: a domain object or NULL
2797
* @memory: the memory size in kilobytes
2798
*
2799
* Dynamically change the target amount of physical memory allocated to a
2800
* domain. If domain is NULL, then this change the amount of memory reserved
2801
* to Domain0 i.e. the domain where the application runs.
2802
* This function may requires privileged access to the hypervisor.
2803
*
2804
* This command only changes the runtime configuration of the domain,
2805
* so can only be called on an active domain.
2806
*
2807
* Returns 0 in case of success and -1 in case of failure.
2808
*/
2809
int
2810
virDomainSetMemory(virDomainPtr domain, unsigned long memory)
2811
{
2812
virConnectPtr conn;
2813
2814
VIR_DOMAIN_DEBUG(domain, "memory=%lu", memory);
2815
2816
virResetLastError();
2817
2818
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2819
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2820
virDispatchError(NULL);
2821
return -1;
2822
}
2823
if (domain->conn->flags & VIR_CONNECT_RO) {
2824
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2825
goto error;
2826
}
2827
if (memory < 4096) {
2828
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
2829
goto error;
2830
}
2831
2832
conn = domain->conn;
2833
2834
if (conn->driver->domainSetMemory) {
2835
int ret;
2836
ret = conn->driver->domainSetMemory (domain, memory);
2837
if (ret < 0)
2838
goto error;
2839
return ret;
2840
}
2841
2842
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2843
2844
error:
2845
virDispatchError(domain->conn);
2846
return -1;
2847
}
2848
2849
/**
2850
* virDomainSetMemoryParameters:
2851
* @domain: pointer to domain object
2852
* @params: pointer to memory parameter objects
2853
* @nparams: number of memory parameter (this value should be same or
2854
* less than the number of parameters supported)
2855
* @flags: currently unused, for future extension
2856
*
2857
* Change the memory tunables
2858
* This function requires privileged access to the hypervisor.
2859
*
2860
* Returns -1 in case of error, 0 in case of success.
2861
*/
2862
int
2863
virDomainSetMemoryParameters(virDomainPtr domain,
2864
virMemoryParameterPtr params,
2865
int nparams, unsigned int flags)
2866
{
2867
virConnectPtr conn;
2868
2869
VIR_DOMAIN_DEBUG(domain, "params=%p, nparams=%d, flags=%u",
2870
params, nparams, flags);
2871
2872
virResetLastError();
2873
2874
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2875
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2876
virDispatchError(NULL);
2877
return -1;
2878
}
2879
if (domain->conn->flags & VIR_CONNECT_RO) {
2880
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
2881
goto error;
2882
}
2883
if ((nparams <= 0) || (params == NULL)) {
2884
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
2885
goto error;
2886
}
2887
conn = domain->conn;
2888
2889
if (conn->driver->domainSetMemoryParameters) {
2890
int ret;
2891
ret = conn->driver->domainSetMemoryParameters (domain, params, nparams, flags);
2892
if (ret < 0)
2893
goto error;
2894
return ret;
2895
}
2896
2897
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2898
2899
error:
2900
virDispatchError(domain->conn);
2901
return -1;
2902
}
2903
2904
/**
2905
* virDomainGetMemoryParameters:
2906
* @domain: pointer to domain object
2907
* @params: pointer to memory parameter object
2908
* (return value, allocated by the caller)
2909
* @nparams: pointer to number of memory parameters
2910
* @flags: currently unused, for future extension
2911
*
2912
* Get the memory parameters, the @params array will be filled with the values
2913
* equal to the number of parameters suggested by @nparams
2914
*
2915
* As the value of @nparams is dynamic, call the API setting @nparams to 0 and
2916
* @params as NULL, the API returns the number of parameters supported by the
2917
* HV by updating @nparams on SUCCESS. The caller should then allocate @params
2918
* array, i.e. (sizeof(@virMemoryParameter) * @nparams) bytes and call the API
2919
* again.
2920
*
2921
* Here is the sample code snippet:
2922
*
2923
* if ((virDomainGetMemoryParameters(dom, NULL, &nparams, 0) == 0) &&
2924
* (nparams != 0)) {
2925
* params = vshMalloc(ctl, sizeof(virMemoryParameter) * nparams);
2926
* memset(params, 0, sizeof(virMemoryParameter) * nparams);
2927
* if (virDomainGetMemoryParameters(dom, params, &nparams, 0)) {
2928
* vshError(ctl, "%s", _("Unable to get memory parameters"));
2929
* goto error;
2930
* }
2931
* }
2932
*
2933
* This function requires privileged access to the hypervisor. This function
2934
* expects the caller to allocate the @params.
2935
*
2936
* Returns -1 in case of error, 0 in case of success.
2937
*/
2938
int
2939
virDomainGetMemoryParameters(virDomainPtr domain,
2940
virMemoryParameterPtr params,
2941
int *nparams, unsigned int flags)
2942
{
2943
virConnectPtr conn;
2944
2945
VIR_DOMAIN_DEBUG(domain, "params=%p, nparams=%d, flags=%u",
2946
params, (nparams) ? *nparams : -1, flags);
2947
2948
virResetLastError();
2949
2950
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2951
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2952
virDispatchError(NULL);
2953
return -1;
2954
}
2955
if ((nparams == NULL) || (*nparams < 0)) {
2956
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
2957
goto error;
2958
}
2959
conn = domain->conn;
2960
2961
if (conn->driver->domainGetMemoryParameters) {
2962
int ret;
2963
ret = conn->driver->domainGetMemoryParameters (domain, params, nparams, flags);
2964
if (ret < 0)
2965
goto error;
2966
return ret;
2967
}
2968
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
2969
2970
error:
2971
virDispatchError(domain->conn);
2972
return -1;
2973
}
2974
2975
/**
2976
* virDomainGetInfo:
2977
* @domain: a domain object
2978
* @info: pointer to a virDomainInfo structure allocated by the user
2979
*
2980
* Extract information about a domain. Note that if the connection
2981
* used to get the domain is limited only a partial set of the information
2982
* can be extracted.
2983
*
2984
* Returns 0 in case of success and -1 in case of failure.
2985
*/
2986
int
2987
virDomainGetInfo(virDomainPtr domain, virDomainInfoPtr info)
2988
{
2989
virConnectPtr conn;
2990
2991
VIR_DOMAIN_DEBUG(domain, "info=%p", info);
2992
2993
virResetLastError();
2994
2995
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
2996
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
2997
virDispatchError(NULL);
2998
return -1;
2999
}
3000
if (info == NULL) {
3001
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
3002
goto error;
3003
}
3004
3005
memset(info, 0, sizeof(virDomainInfo));
3006
3007
conn = domain->conn;
3008
3009
if (conn->driver->domainGetInfo) {
3010
int ret;
3011
ret = conn->driver->domainGetInfo (domain, info);
3012
if (ret < 0)
3013
goto error;
3014
return ret;
3015
}
3016
3017
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3018
3019
error:
3020
virDispatchError(domain->conn);
3021
return -1;
3022
}
3023
3024
/**
3025
* virDomainGetXMLDesc:
3026
* @domain: a domain object
3027
* @flags: an OR'ed set of virDomainXMLFlags
3028
*
3029
* Provide an XML description of the domain. The description may be reused
3030
* later to relaunch the domain with virDomainCreateXML().
3031
*
3032
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
3033
* the caller must free() the returned value.
3034
*/
3035
char *
3036
virDomainGetXMLDesc(virDomainPtr domain, int flags)
3037
{
3038
virConnectPtr conn;
3039
3040
VIR_DOMAIN_DEBUG(domain, "flags=%d", flags);
3041
3042
virResetLastError();
3043
3044
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
3045
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
3046
virDispatchError(NULL);
3047
return NULL;
3048
}
3049
3050
conn = domain->conn;
3051
3052
if ((conn->flags & VIR_CONNECT_RO) && (flags & VIR_DOMAIN_XML_SECURE)) {
3053
virLibConnError(VIR_ERR_OPERATION_DENIED,
3054
_("virDomainGetXMLDesc with secure flag"));
3055
goto error;
3056
}
3057
3058
flags &= VIR_DOMAIN_XML_FLAGS_MASK;
3059
3060
if (conn->driver->domainDumpXML) {
3061
char *ret;
3062
ret = conn->driver->domainDumpXML (domain, flags);
3063
if (!ret)
3064
goto error;
3065
return ret;
3066
}
3067
3068
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3069
3070
error:
3071
virDispatchError(domain->conn);
3072
return NULL;
3073
}
3074
3075
/**
3076
* virConnectDomainXMLFromNative:
3077
* @conn: a connection object
3078
* @nativeFormat: configuration format importing from
3079
* @nativeConfig: the configuration data to import
3080
* @flags: currently unused, pass 0
3081
*
3082
* Reads native configuration data describing a domain, and
3083
* generates libvirt domain XML. The format of the native
3084
* data is hypervisor dependant.
3085
*
3086
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
3087
* the caller must free() the returned value.
3088
*/
3089
char *virConnectDomainXMLFromNative(virConnectPtr conn,
3090
const char *nativeFormat,
3091
const char *nativeConfig,
3092
unsigned int flags)
3093
{
3094
DEBUG("conn=%p, format=%s config=%s flags=%u", conn, nativeFormat, nativeConfig, flags);
3095
3096
virResetLastError();
3097
3098
if (!VIR_IS_CONNECT(conn)) {
3099
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
3100
virDispatchError(NULL);
3101
return NULL;
3102
}
3103
3104
if (nativeFormat == NULL || nativeConfig == NULL) {
3105
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
3106
goto error;
3107
}
3108
3109
if (conn->driver->domainXMLFromNative) {
3110
char *ret;
3111
ret = conn->driver->domainXMLFromNative (conn,
3112
nativeFormat,
3113
nativeConfig,
3114
flags);
3115
if (!ret)
3116
goto error;
3117
return ret;
3118
}
3119
3120
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3121
3122
error:
3123
virDispatchError(conn);
3124
return NULL;
3125
}
3126
3127
/**
3128
* virConnectDomainXMLToNative:
3129
* @conn: a connection object
3130
* @nativeFormat: configuration format exporting to
3131
* @domainXml: the domain configuration to export
3132
* @flags: currently unused, pass 0
3133
*
3134
* Reads a domain XML configuration document, and generates
3135
* a native configuration file describing the domain.
3136
* The format of the native data is hypervisor dependant.
3137
*
3138
* Returns a 0 terminated UTF-8 encoded native config datafile, or NULL in case of error.
3139
* the caller must free() the returned value.
3140
*/
3141
char *virConnectDomainXMLToNative(virConnectPtr conn,
3142
const char *nativeFormat,
3143
const char *domainXml,
3144
unsigned int flags)
3145
{
3146
DEBUG("conn=%p, format=%s xml=%s flags=%u", conn, nativeFormat, domainXml, flags);
3147
3148
virResetLastError();
3149
3150
if (!VIR_IS_CONNECT(conn)) {
3151
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
3152
virDispatchError(NULL);
3153
return NULL;
3154
}
3155
3156
if (nativeFormat == NULL || domainXml == NULL) {
3157
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
3158
goto error;
3159
}
3160
3161
if (conn->driver->domainXMLToNative) {
3162
char *ret;
3163
ret = conn->driver->domainXMLToNative(conn,
3164
nativeFormat,
3165
domainXml,
3166
flags);
3167
if (!ret)
3168
goto error;
3169
return ret;
3170
}
3171
3172
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3173
3174
error:
3175
virDispatchError(conn);
3176
return NULL;
3177
}
3178
3179
3180
static virDomainPtr
3181
virDomainMigrateVersion1 (virDomainPtr domain,
3182
virConnectPtr dconn,
3183
unsigned long flags,
3184
const char *dname,
3185
const char *uri,
3186
unsigned long bandwidth)
3187
{
3188
virDomainPtr ddomain = NULL;
3189
char *uri_out = NULL;
3190
char *cookie = NULL;
3191
int cookielen = 0, ret;
3192
virDomainInfo info;
3193
3194
ret = virDomainGetInfo (domain, &info);
3195
if (ret == 0 && info.state == VIR_DOMAIN_PAUSED) {
3196
flags |= VIR_MIGRATE_PAUSED;
3197
}
3198
3199
/* Prepare the migration.
3200
*
3201
* The destination host may return a cookie, or leave cookie as
3202
* NULL.
3203
*
3204
* The destination host MUST set uri_out if uri_in is NULL.
3205
*
3206
* If uri_in is non-NULL, then the destination host may modify
3207
* the URI by setting uri_out. If it does not wish to modify
3208
* the URI, it should leave uri_out as NULL.
3209
*/
3210
if (dconn->driver->domainMigratePrepare
3211
(dconn, &cookie, &cookielen, uri, &uri_out, flags, dname,
3212
bandwidth) == -1)
3213
goto done;
3214
3215
if (uri == NULL && uri_out == NULL) {
3216
virLibConnError(VIR_ERR_INTERNAL_ERROR,
3217
_("domainMigratePrepare did not set uri"));
3218
goto done;
3219
}
3220
if (uri_out)
3221
uri = uri_out; /* Did domainMigratePrepare change URI? */
3222
assert (uri != NULL);
3223
3224
/* Perform the migration. The driver isn't supposed to return
3225
* until the migration is complete.
3226
*/
3227
if (domain->conn->driver->domainMigratePerform
3228
(domain, cookie, cookielen, uri, flags, dname, bandwidth) == -1)
3229
goto done;
3230
3231
/* Get the destination domain and return it or error.
3232
* 'domain' no longer actually exists at this point
3233
* (or so we hope), but we still use the object in memory
3234
* in order to get the name.
3235
*/
3236
dname = dname ? dname : domain->name;
3237
if (dconn->driver->domainMigrateFinish)
3238
ddomain = dconn->driver->domainMigrateFinish
3239
(dconn, dname, cookie, cookielen, uri, flags);
3240
else
3241
ddomain = virDomainLookupByName (dconn, dname);
3242
3243
done:
3244
VIR_FREE (uri_out);
3245
VIR_FREE (cookie);
3246
return ddomain;
3247
}
3248
3249
static virDomainPtr
3250
virDomainMigrateVersion2 (virDomainPtr domain,
3251
virConnectPtr dconn,
3252
unsigned long flags,
3253
const char *dname,
3254
const char *uri,
3255
unsigned long bandwidth)
3256
{
3257
virDomainPtr ddomain = NULL;
3258
char *uri_out = NULL;
3259
char *cookie = NULL;
3260
char *dom_xml = NULL;
3261
int cookielen = 0, ret;
3262
virDomainInfo info;
3263
virErrorPtr orig_err = NULL;
3264
3265
/* Prepare the migration.
3266
*
3267
* The destination host may return a cookie, or leave cookie as
3268
* NULL.
3269
*
3270
* The destination host MUST set uri_out if uri_in is NULL.
3271
*
3272
* If uri_in is non-NULL, then the destination host may modify
3273
* the URI by setting uri_out. If it does not wish to modify
3274
* the URI, it should leave uri_out as NULL.
3275
*/
3276
3277
/* In version 2 of the protocol, the prepare step is slightly
3278
* different. We fetch the domain XML of the source domain
3279
* and pass it to Prepare2.
3280
*/
3281
if (!domain->conn->driver->domainDumpXML) {
3282
virLibConnError(VIR_ERR_INTERNAL_ERROR, __FUNCTION__);
3283
virDispatchError(domain->conn);
3284
return NULL;
3285
}
3286
dom_xml = domain->conn->driver->domainDumpXML (domain,
3287
VIR_DOMAIN_XML_SECURE |
3288
VIR_DOMAIN_XML_UPDATE_CPU);
3289
if (!dom_xml)
3290
return NULL;
3291
3292
ret = virDomainGetInfo (domain, &info);
3293
if (ret == 0 && info.state == VIR_DOMAIN_PAUSED) {
3294
flags |= VIR_MIGRATE_PAUSED;
3295
}
3296
3297
ret = dconn->driver->domainMigratePrepare2
3298
(dconn, &cookie, &cookielen, uri, &uri_out, flags, dname,
3299
bandwidth, dom_xml);
3300
VIR_FREE (dom_xml);
3301
if (ret == -1)
3302
goto done;
3303
3304
if (uri == NULL && uri_out == NULL) {
3305
virLibConnError(VIR_ERR_INTERNAL_ERROR,
3306
_("domainMigratePrepare2 did not set uri"));
3307
virDispatchError(domain->conn);
3308
goto done;
3309
}
3310
if (uri_out)
3311
uri = uri_out; /* Did domainMigratePrepare2 change URI? */
3312
assert (uri != NULL);
3313
3314
/* Perform the migration. The driver isn't supposed to return
3315
* until the migration is complete.
3316
*/
3317
ret = domain->conn->driver->domainMigratePerform
3318
(domain, cookie, cookielen, uri, flags, dname, bandwidth);
3319
3320
/* Perform failed. Make sure Finish doesn't overwrite the error */
3321
if (ret < 0)
3322
orig_err = virSaveLastError();
3323
3324
/* In version 2 of the migration protocol, we pass the
3325
* status code from the sender to the destination host,
3326
* so it can do any cleanup if the migration failed.
3327
*/
3328
dname = dname ? dname : domain->name;
3329
ddomain = dconn->driver->domainMigrateFinish2
3330
(dconn, dname, cookie, cookielen, uri, flags, ret);
3331
3332
done:
3333
if (orig_err) {
3334
virSetError(orig_err);
3335
virFreeError(orig_err);
3336
}
3337
VIR_FREE (uri_out);
3338
VIR_FREE (cookie);
3339
return ddomain;
3340
}
3341
3342
3343
/*
3344
* This is sort of a migration v3
3345
*
3346
* In this version, the client does not talk to the destination
3347
* libvirtd. The source libvirtd will still try to talk to the
3348
* destination libvirtd though, and will do the prepare/perform/finish
3349
* steps.
3350
*/
3351
static int
3352
virDomainMigratePeer2Peer (virDomainPtr domain,
3353
unsigned long flags,
3354
const char *dname,
3355
const char *uri,
3356
unsigned long bandwidth)
3357
{
3358
xmlURIPtr tempuri = NULL;
3359
3360
if (!domain->conn->driver->domainMigratePerform) {
3361
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3362
virDispatchError(domain->conn);
3363
return -1;
3364
}
3365
3366
tempuri = xmlParseURI(uri);
3367
if (!tempuri) {
3368
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
3369
virDispatchError(domain->conn);
3370
return -1;
3371
}
3372
3373
if (!tempuri->server || STRPREFIX(tempuri->server, "localhost")) {
3374
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
3375
virDispatchError(domain->conn);
3376
xmlFreeURI(tempuri);
3377
return -1;
3378
}
3379
xmlFreeURI(tempuri);
3380
3381
/* Perform the migration. The driver isn't supposed to return
3382
* until the migration is complete.
3383
*/
3384
return domain->conn->driver->domainMigratePerform(domain,
3385
NULL, /* cookie */
3386
0, /* cookielen */
3387
uri,
3388
flags,
3389
dname,
3390
bandwidth);
3391
}
3392
3393
3394
/*
3395
* This is a variation on v1 & 2 migration
3396
*
3397
* This is for hypervisors which can directly handshake
3398
* without any libvirtd involvement on destination either
3399
* from client, or source libvirt.
3400
*
3401
* eg, XenD can talk direct to XenD, so libvirtd on dest
3402
* does not need to be involved at all, or even running
3403
*/
3404
static int
3405
virDomainMigrateDirect (virDomainPtr domain,
3406
unsigned long flags,
3407
const char *dname,
3408
const char *uri,
3409
unsigned long bandwidth)
3410
{
3411
if (!domain->conn->driver->domainMigratePerform) {
3412
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3413
virDispatchError(domain->conn);
3414
return -1;
3415
}
3416
3417
/* Perform the migration. The driver isn't supposed to return
3418
* until the migration is complete.
3419
*/
3420
return domain->conn->driver->domainMigratePerform(domain,
3421
NULL, /* cookie */
3422
0, /* cookielen */
3423
uri,
3424
flags,
3425
dname,
3426
bandwidth);
3427
}
3428
3429
3430
/**
3431
* virDomainMigrate:
3432
* @domain: a domain object
3433
* @dconn: destination host (a connection object)
3434
* @flags: flags
3435
* @dname: (optional) rename domain to this at destination
3436
* @uri: (optional) dest hostname/URI as seen from the source host
3437
* @bandwidth: (optional) specify migration bandwidth limit in Mbps
3438
*
3439
* Migrate the domain object from its current host to the destination
3440
* host given by dconn (a connection to the destination host).
3441
*
3442
* Flags may be one of more of the following:
3443
* VIR_MIGRATE_LIVE Do not pause the VM during migration
3444
* VIR_MIGRATE_PEER2PEER Direct connection between source & destination hosts
3445
* VIR_MIGRATE_TUNNELLED Tunnel migration data over the libvirt RPC channel
3446
* VIR_MIGRATE_PERSIST_DEST If the migration is successful, persist the domain
3447
* on the destination host.
3448
* VIR_MIGRATE_UNDEFINE_SOURCE If the migration is successful, undefine the
3449
* domain on the source host.
3450
* VIR_MIGRATE_PAUSED Leave the domain suspended on the remote side.
3451
*
3452
* VIR_MIGRATE_TUNNELLED requires that VIR_MIGRATE_PEER2PEER be set.
3453
* Applications using the VIR_MIGRATE_PEER2PEER flag will probably
3454
* prefer to invoke virDomainMigrateToURI, avoiding the need to
3455
* open connection to the destination host themselves.
3456
*
3457
* If a hypervisor supports renaming domains during migration,
3458
* then you may set the dname parameter to the new name (otherwise
3459
* it keeps the same name). If this is not supported by the
3460
* hypervisor, dname must be NULL or else you will get an error.
3461
*
3462
* If the VIR_MIGRATE_PEER2PEER flag is set, the uri parameter
3463
* must be a valid libvirt connection URI, by which the source
3464
* libvirt driver can connect to the destination libvirt. If
3465
* omitted, the dconn connection object will be queried for its
3466
* current URI.
3467
*
3468
* If the VIR_MIGRATE_PEER2PEER flag is NOT set, the URI parameter
3469
* takes a hypervisor specific format. The hypervisor capabilities
3470
* XML includes details of the support URI schemes. If omitted
3471
* the dconn will be asked for a default URI.
3472
*
3473
* In either case it is typically only necessary to specify a
3474
* URI if the destination host has multiple interfaces and a
3475
* specific interface is required to transmit migration data.
3476
*
3477
* The maximum bandwidth (in Mbps) that will be used to do migration
3478
* can be specified with the bandwidth parameter. If set to 0,
3479
* libvirt will choose a suitable default. Some hypervisors do
3480
* not support this feature and will return an error if bandwidth
3481
* is not 0.
3482
*
3483
* To see which features are supported by the current hypervisor,
3484
* see virConnectGetCapabilities, /capabilities/host/migration_features.
3485
*
3486
* There are many limitations on migration imposed by the underlying
3487
* technology - for example it may not be possible to migrate between
3488
* different processors even with the same architecture, or between
3489
* different types of hypervisor.
3490
*
3491
* Returns the new domain object if the migration was successful,
3492
* or NULL in case of error. Note that the new domain object
3493
* exists in the scope of the destination connection (dconn).
3494
*/
3495
virDomainPtr
3496
virDomainMigrate (virDomainPtr domain,
3497
virConnectPtr dconn,
3498
unsigned long flags,
3499
const char *dname,
3500
const char *uri,
3501
unsigned long bandwidth)
3502
{
3503
virDomainPtr ddomain = NULL;
3504
3505
VIR_DOMAIN_DEBUG(domain, "dconn=%p, flags=%lu, dname=%s, uri=%s, bandwidth=%lu",
3506
dconn, flags, NULLSTR(dname), NULLSTR(uri), bandwidth);
3507
3508
virResetLastError();
3509
3510
/* First checkout the source */
3511
if (!VIR_IS_CONNECTED_DOMAIN (domain)) {
3512
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
3513
virDispatchError(NULL);
3514
return NULL;
3515
}
3516
if (domain->conn->flags & VIR_CONNECT_RO) {
3517
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
3518
goto error;
3519
}
3520
3521
/* Now checkout the destination */
3522
if (!VIR_IS_CONNECT(dconn)) {
3523
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
3524
goto error;
3525
}
3526
if (dconn->flags & VIR_CONNECT_RO) {
3527
/* NB, deliberately report error against source object, not dest */
3528
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
3529
goto error;
3530
}
3531
3532
if (flags & VIR_MIGRATE_PEER2PEER) {
3533
if (VIR_DRV_SUPPORTS_FEATURE (domain->conn->driver, domain->conn,
3534
VIR_DRV_FEATURE_MIGRATION_P2P)) {
3535
char *dstURI = NULL;
3536
if (uri == NULL) {
3537
dstURI = virConnectGetURI(dconn);
3538
if (!dstURI)
3539
return NULL;
3540
}
3541
3542
if (virDomainMigratePeer2Peer(domain, flags, dname, uri ? uri : dstURI, bandwidth) < 0) {
3543
VIR_FREE(dstURI);
3544
goto error;
3545
}
3546
VIR_FREE(dstURI);
3547
3548
ddomain = virDomainLookupByName (dconn, dname ? dname : domain->name);
3549
} else {
3550
/* This driver does not support peer to peer migration */
3551
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3552
goto error;
3553
}
3554
} else {
3555
if (flags & VIR_MIGRATE_TUNNELLED) {
3556
virLibConnError(VIR_ERR_OPERATION_INVALID,
3557
_("cannot perform tunnelled migration without using peer2peer flag"));
3558
goto error;
3559
}
3560
3561
/* Check that migration is supported by both drivers. */
3562
if (VIR_DRV_SUPPORTS_FEATURE(domain->conn->driver, domain->conn,
3563
VIR_DRV_FEATURE_MIGRATION_V1) &&
3564
VIR_DRV_SUPPORTS_FEATURE(dconn->driver, dconn,
3565
VIR_DRV_FEATURE_MIGRATION_V1))
3566
ddomain = virDomainMigrateVersion1(domain, dconn, flags, dname, uri, bandwidth);
3567
else if (VIR_DRV_SUPPORTS_FEATURE(domain->conn->driver, domain->conn,
3568
VIR_DRV_FEATURE_MIGRATION_V2) &&
3569
VIR_DRV_SUPPORTS_FEATURE(dconn->driver, dconn,
3570
VIR_DRV_FEATURE_MIGRATION_V2))
3571
ddomain = virDomainMigrateVersion2(domain, dconn, flags, dname, uri, bandwidth);
3572
else {
3573
/* This driver does not support any migration method */
3574
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3575
goto error;
3576
}
3577
}
3578
3579
if (ddomain == NULL)
3580
goto error;
3581
3582
return ddomain;
3583
3584
error:
3585
virDispatchError(domain->conn);
3586
return NULL;
3587
}
3588
3589
3590
/**
3591
* virDomainMigrateToURI:
3592
* @domain: a domain object
3593
* @duri: mandatory URI for the destination host
3594
* @flags: flags
3595
* @dname: (optional) rename domain to this at destination
3596
* @bandwidth: (optional) specify migration bandwidth limit in Mbps
3597
*
3598
* Migrate the domain object from its current host to the destination
3599
* host given by duri.
3600
*
3601
* Flags may be one of more of the following:
3602
* VIR_MIGRATE_LIVE Do not pause the VM during migration
3603
* VIR_MIGRATE_PEER2PEER Direct connection between source & destination hosts
3604
* VIR_MIGRATE_TUNNELLED Tunnel migration data over the libvirt RPC channel
3605
* VIR_MIGRATE_PERSIST_DEST If the migration is successful, persist the domain
3606
* on the destination host.
3607
* VIR_MIGRATE_UNDEFINE_SOURCE If the migration is successful, undefine the
3608
* domain on the source host.
3609
*
3610
* The operation of this API hinges on the VIR_MIGRATE_PEER2PEER flag.
3611
* If the VIR_MIGRATE_PEER2PEER flag is NOT set, the duri parameter
3612
* takes a hypervisor specific format. The uri_transports element of the
3613
* hypervisor capabilities XML includes details of the supported URI
3614
* schemes. Not all hypervisors will support this mode of migration, so
3615
* if the VIR_MIGRATE_PEER2PEER flag is not set, then it may be necessary
3616
* to use the alternative virDomainMigrate API providing and explicit
3617
* virConnectPtr for the destination host.
3618
*
3619
* If the VIR_MIGRATE_PEER2PEER flag IS set, the duri parameter
3620
* must be a valid libvirt connection URI, by which the source
3621
* libvirt driver can connect to the destination libvirt.
3622
*
3623
* VIR_MIGRATE_TUNNELLED requires that VIR_MIGRATE_PEER2PEER be set.
3624
*
3625
* If a hypervisor supports renaming domains during migration,
3626
* the dname parameter specifies the new name for the domain.
3627
* Setting dname to NULL keeps the domain name the same. If domain
3628
* renaming is not supported by the hypervisor, dname must be NULL or
3629
* else an error will be returned.
3630
*
3631
* The maximum bandwidth (in Mbps) that will be used to do migration
3632
* can be specified with the bandwidth parameter. If set to 0,
3633
* libvirt will choose a suitable default. Some hypervisors do
3634
* not support this feature and will return an error if bandwidth
3635
* is not 0.
3636
*
3637
* To see which features are supported by the current hypervisor,
3638
* see virConnectGetCapabilities, /capabilities/host/migration_features.
3639
*
3640
* There are many limitations on migration imposed by the underlying
3641
* technology - for example it may not be possible to migrate between
3642
* different processors even with the same architecture, or between
3643
* different types of hypervisor.
3644
*
3645
* Returns 0 if the migration succeeded, -1 upon error.
3646
*/
3647
int
3648
virDomainMigrateToURI (virDomainPtr domain,
3649
const char *duri,
3650
unsigned long flags,
3651
const char *dname,
3652
unsigned long bandwidth)
3653
{
3654
VIR_DOMAIN_DEBUG(domain, "duri=%p, flags=%lu, dname=%s, bandwidth=%lu",
3655
NULLSTR(duri), flags, NULLSTR(dname), bandwidth);
3656
3657
virResetLastError();
3658
3659
/* First checkout the source */
3660
if (!VIR_IS_CONNECTED_DOMAIN (domain)) {
3661
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
3662
virDispatchError(NULL);
3663
return -1;
3664
}
3665
if (domain->conn->flags & VIR_CONNECT_RO) {
3666
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
3667
goto error;
3668
}
3669
3670
if (duri == NULL) {
3671
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
3672
goto error;
3673
}
3674
3675
if (flags & VIR_MIGRATE_PEER2PEER) {
3676
if (VIR_DRV_SUPPORTS_FEATURE (domain->conn->driver, domain->conn,
3677
VIR_DRV_FEATURE_MIGRATION_P2P)) {
3678
if (virDomainMigratePeer2Peer (domain, flags, dname, duri, bandwidth) < 0)
3679
goto error;
3680
} else {
3681
/* No peer to peer migration supported */
3682
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3683
goto error;
3684
}
3685
} else {
3686
if (VIR_DRV_SUPPORTS_FEATURE (domain->conn->driver, domain->conn,
3687
VIR_DRV_FEATURE_MIGRATION_DIRECT)) {
3688
if (virDomainMigrateDirect (domain, flags, dname, duri, bandwidth) < 0)
3689
goto error;
3690
} else {
3691
/* Cannot do a migration with only the perform step */
3692
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3693
goto error;
3694
}
3695
}
3696
3697
return 0;
3698
3699
error:
3700
virDispatchError(domain->conn);
3701
return -1;
3702
}
3703
3704
3705
/*
3706
* Not for public use. This function is part of the internal
3707
* implementation of migration in the remote case.
3708
*/
3709
int
3710
virDomainMigratePrepare (virConnectPtr dconn,
3711
char **cookie,
3712
int *cookielen,
3713
const char *uri_in,
3714
char **uri_out,
3715
unsigned long flags,
3716
const char *dname,
3717
unsigned long bandwidth)
3718
{
3719
VIR_DEBUG("dconn=%p, cookie=%p, cookielen=%p, uri_in=%s, uri_out=%p, "
3720
"flags=%lu, dname=%s, bandwidth=%lu", dconn, cookie, cookielen,
3721
NULLSTR(uri_in), uri_out, flags, NULLSTR(dname), bandwidth);
3722
3723
virResetLastError();
3724
3725
if (!VIR_IS_CONNECT (dconn)) {
3726
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
3727
virDispatchError(NULL);
3728
return -1;
3729
}
3730
3731
if (dconn->flags & VIR_CONNECT_RO) {
3732
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
3733
goto error;
3734
}
3735
3736
if (dconn->driver->domainMigratePrepare) {
3737
int ret;
3738
ret = dconn->driver->domainMigratePrepare (dconn, cookie, cookielen,
3739
uri_in, uri_out,
3740
flags, dname, bandwidth);
3741
if (ret < 0)
3742
goto error;
3743
return ret;
3744
}
3745
3746
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3747
3748
error:
3749
virDispatchError(dconn);
3750
return -1;
3751
}
3752
3753
/*
3754
* Not for public use. This function is part of the internal
3755
* implementation of migration in the remote case.
3756
*/
3757
int
3758
virDomainMigratePerform (virDomainPtr domain,
3759
const char *cookie,
3760
int cookielen,
3761
const char *uri,
3762
unsigned long flags,
3763
const char *dname,
3764
unsigned long bandwidth)
3765
{
3766
virConnectPtr conn;
3767
3768
VIR_DOMAIN_DEBUG(domain, "cookie=%p, cookielen=%d, uri=%s, flags=%lu, "
3769
"dname=%s, bandwidth=%lu", cookie, cookielen, uri, flags,
3770
NULLSTR(dname), bandwidth);
3771
3772
virResetLastError();
3773
3774
if (!VIR_IS_CONNECTED_DOMAIN (domain)) {
3775
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
3776
virDispatchError(NULL);
3777
return -1;
3778
}
3779
conn = domain->conn;
3780
3781
if (domain->conn->flags & VIR_CONNECT_RO) {
3782
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
3783
goto error;
3784
}
3785
3786
if (conn->driver->domainMigratePerform) {
3787
int ret;
3788
ret = conn->driver->domainMigratePerform (domain, cookie, cookielen,
3789
uri,
3790
flags, dname, bandwidth);
3791
if (ret < 0)
3792
goto error;
3793
return ret;
3794
}
3795
3796
virLibDomainError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3797
3798
error:
3799
virDispatchError(domain->conn);
3800
return -1;
3801
}
3802
3803
/*
3804
* Not for public use. This function is part of the internal
3805
* implementation of migration in the remote case.
3806
*/
3807
virDomainPtr
3808
virDomainMigrateFinish (virConnectPtr dconn,
3809
const char *dname,
3810
const char *cookie,
3811
int cookielen,
3812
const char *uri,
3813
unsigned long flags)
3814
{
3815
VIR_DEBUG("dconn=%p, dname=%s, cookie=%p, cookielen=%d, uri=%s, "
3816
"flags=%lu", dconn, NULLSTR(dname), cookie, cookielen,
3817
uri, flags);
3818
3819
virResetLastError();
3820
3821
if (!VIR_IS_CONNECT (dconn)) {
3822
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
3823
virDispatchError(NULL);
3824
return NULL;
3825
}
3826
3827
if (dconn->flags & VIR_CONNECT_RO) {
3828
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
3829
goto error;
3830
}
3831
3832
if (dconn->driver->domainMigrateFinish) {
3833
virDomainPtr ret;
3834
ret = dconn->driver->domainMigrateFinish (dconn, dname,
3835
cookie, cookielen,
3836
uri, flags);
3837
if (!ret)
3838
goto error;
3839
return ret;
3840
}
3841
3842
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3843
3844
error:
3845
virDispatchError(dconn);
3846
return NULL;
3847
}
3848
3849
3850
/*
3851
* Not for public use. This function is part of the internal
3852
* implementation of migration in the remote case.
3853
*/
3854
int
3855
virDomainMigratePrepare2 (virConnectPtr dconn,
3856
char **cookie,
3857
int *cookielen,
3858
const char *uri_in,
3859
char **uri_out,
3860
unsigned long flags,
3861
const char *dname,
3862
unsigned long bandwidth,
3863
const char *dom_xml)
3864
{
3865
VIR_DEBUG("dconn=%p, cookie=%p, cookielen=%p, uri_in=%s, uri_out=%p,"
3866
"flags=%lu, dname=%s, bandwidth=%lu, dom_xml=%s", dconn,
3867
cookie, cookielen, uri_in, uri_out, flags, NULLSTR(dname),
3868
bandwidth, dom_xml);
3869
3870
virResetLastError();
3871
3872
if (!VIR_IS_CONNECT (dconn)) {
3873
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
3874
virDispatchError(NULL);
3875
return -1;
3876
}
3877
3878
if (dconn->flags & VIR_CONNECT_RO) {
3879
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
3880
goto error;
3881
}
3882
3883
if (dconn->driver->domainMigratePrepare2) {
3884
int ret;
3885
ret = dconn->driver->domainMigratePrepare2 (dconn, cookie, cookielen,
3886
uri_in, uri_out,
3887
flags, dname, bandwidth,
3888
dom_xml);
3889
if (ret < 0)
3890
goto error;
3891
return ret;
3892
}
3893
3894
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3895
3896
error:
3897
virDispatchError(dconn);
3898
return -1;
3899
}
3900
3901
/*
3902
* Not for public use. This function is part of the internal
3903
* implementation of migration in the remote case.
3904
*/
3905
virDomainPtr
3906
virDomainMigrateFinish2 (virConnectPtr dconn,
3907
const char *dname,
3908
const char *cookie,
3909
int cookielen,
3910
const char *uri,
3911
unsigned long flags,
3912
int retcode)
3913
{
3914
VIR_DEBUG("dconn=%p, dname=%s, cookie=%p, cookielen=%d, uri=%s, "
3915
"flags=%lu, retcode=%d", dconn, NULLSTR(dname), cookie,
3916
cookielen, uri, flags, retcode);
3917
3918
virResetLastError();
3919
3920
if (!VIR_IS_CONNECT (dconn)) {
3921
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
3922
virDispatchError(NULL);
3923
return NULL;
3924
}
3925
3926
if (dconn->flags & VIR_CONNECT_RO) {
3927
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
3928
goto error;
3929
}
3930
3931
if (dconn->driver->domainMigrateFinish2) {
3932
virDomainPtr ret;
3933
ret = dconn->driver->domainMigrateFinish2 (dconn, dname,
3934
cookie, cookielen,
3935
uri, flags,
3936
retcode);
3937
if (!ret)
3938
goto error;
3939
return ret;
3940
}
3941
3942
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3943
3944
error:
3945
virDispatchError(dconn);
3946
return NULL;
3947
}
3948
3949
3950
/*
3951
* Not for public use. This function is part of the internal
3952
* implementation of migration in the remote case.
3953
*/
3954
int
3955
virDomainMigratePrepareTunnel(virConnectPtr conn,
3956
virStreamPtr st,
3957
unsigned long flags,
3958
const char *dname,
3959
unsigned long bandwidth,
3960
const char *dom_xml)
3961
3962
{
3963
VIR_DEBUG("conn=%p, stream=%p, flags=%lu, dname=%s, "
3964
"bandwidth=%lu, dom_xml=%s", conn, st, flags,
3965
NULLSTR(dname), bandwidth, dom_xml);
3966
3967
virResetLastError();
3968
3969
if (!VIR_IS_CONNECT(conn)) {
3970
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
3971
virDispatchError(NULL);
3972
return -1;
3973
}
3974
3975
if (conn->flags & VIR_CONNECT_RO) {
3976
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
3977
goto error;
3978
}
3979
3980
if (conn != st->conn) {
3981
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
3982
goto error;
3983
}
3984
3985
if (conn->driver->domainMigratePrepareTunnel) {
3986
int rv = conn->driver->domainMigratePrepareTunnel(conn, st,
3987
flags, dname,
3988
bandwidth, dom_xml);
3989
if (rv < 0)
3990
goto error;
3991
return rv;
3992
}
3993
3994
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
3995
3996
error:
3997
virDispatchError(conn);
3998
return -1;
3999
}
4000
4001
4002
/**
4003
* virNodeGetInfo:
4004
* @conn: pointer to the hypervisor connection
4005
* @info: pointer to a virNodeInfo structure allocated by the user
4006
*
4007
* Extract hardware information about the node.
4008
*
4009
* Returns 0 in case of success and -1 in case of failure.
4010
*/
4011
int
4012
virNodeGetInfo(virConnectPtr conn, virNodeInfoPtr info)
4013
{
4014
DEBUG("conn=%p, info=%p", conn, info);
4015
4016
virResetLastError();
4017
4018
if (!VIR_IS_CONNECT(conn)) {
4019
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
4020
virDispatchError(NULL);
4021
return -1;
4022
}
4023
if (info == NULL) {
4024
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
4025
goto error;
4026
}
4027
4028
if (conn->driver->nodeGetInfo) {
4029
int ret;
4030
ret = conn->driver->nodeGetInfo (conn, info);
4031
if (ret < 0)
4032
goto error;
4033
return ret;
4034
}
4035
4036
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4037
4038
error:
4039
virDispatchError(conn);
4040
return -1;
4041
}
4042
4043
/**
4044
* virConnectGetCapabilities:
4045
* @conn: pointer to the hypervisor connection
4046
*
4047
* Provides capabilities of the hypervisor / driver.
4048
*
4049
* Returns NULL in case of error, or an XML string
4050
* defining the capabilities.
4051
* The client must free the returned string after use.
4052
*/
4053
char *
4054
virConnectGetCapabilities (virConnectPtr conn)
4055
{
4056
DEBUG("conn=%p", conn);
4057
4058
virResetLastError();
4059
4060
if (!VIR_IS_CONNECT (conn)) {
4061
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
4062
virDispatchError(NULL);
4063
return NULL;
4064
}
4065
4066
if (conn->driver->getCapabilities) {
4067
char *ret;
4068
ret = conn->driver->getCapabilities (conn);
4069
if (!ret)
4070
goto error;
4071
DEBUG("conn=%p ret=%s", conn, ret);
4072
return ret;
4073
}
4074
4075
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4076
4077
error:
4078
virDispatchError(conn);
4079
return NULL;
4080
}
4081
4082
/**
4083
* virNodeGetFreeMemory:
4084
* @conn: pointer to the hypervisor connection
4085
*
4086
* provides the free memory available on the Node
4087
* Note: most libvirt APIs provide memory sizes in kilobytes, but in this
4088
* function the returned value is in bytes. Divide by 1024 as necessary.
4089
*
4090
* Returns the available free memory in bytes or 0 in case of error
4091
*/
4092
unsigned long long
4093
virNodeGetFreeMemory(virConnectPtr conn)
4094
{
4095
DEBUG("conn=%p", conn);
4096
4097
virResetLastError();
4098
4099
if (!VIR_IS_CONNECT (conn)) {
4100
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
4101
virDispatchError(NULL);
4102
return 0;
4103
}
4104
4105
if (conn->driver->getFreeMemory) {
4106
unsigned long long ret;
4107
ret = conn->driver->getFreeMemory (conn);
4108
if (ret == 0)
4109
goto error;
4110
return ret;
4111
}
4112
4113
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4114
4115
error:
4116
virDispatchError(conn);
4117
return 0;
4118
}
4119
4120
/**
4121
* virDomainGetSchedulerType:
4122
* @domain: pointer to domain object
4123
* @nparams: number of scheduler parameters(return value)
4124
*
4125
* Get the scheduler type.
4126
*
4127
* Returns NULL in case of error. The caller must free the returned string.
4128
*/
4129
char *
4130
virDomainGetSchedulerType(virDomainPtr domain, int *nparams)
4131
{
4132
virConnectPtr conn;
4133
char *schedtype;
4134
4135
VIR_DOMAIN_DEBUG(domain, "nparams=%p", nparams);
4136
4137
virResetLastError();
4138
4139
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
4140
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4141
virDispatchError(NULL);
4142
return NULL;
4143
}
4144
conn = domain->conn;
4145
4146
if (conn->driver->domainGetSchedulerType){
4147
schedtype = conn->driver->domainGetSchedulerType (domain, nparams);
4148
if (!schedtype)
4149
goto error;
4150
return schedtype;
4151
}
4152
4153
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4154
4155
error:
4156
virDispatchError(domain->conn);
4157
return NULL;
4158
}
4159
4160
4161
/**
4162
* virDomainGetSchedulerParameters:
4163
* @domain: pointer to domain object
4164
* @params: pointer to scheduler parameter object
4165
* (return value)
4166
* @nparams: pointer to number of scheduler parameter
4167
* (this value should be same than the returned value
4168
* nparams of virDomainGetSchedulerType)
4169
*
4170
* Get the scheduler parameters, the @params array will be filled with the
4171
* values.
4172
*
4173
* Returns -1 in case of error, 0 in case of success.
4174
*/
4175
int
4176
virDomainGetSchedulerParameters(virDomainPtr domain,
4177
virSchedParameterPtr params, int *nparams)
4178
{
4179
virConnectPtr conn;
4180
4181
VIR_DOMAIN_DEBUG(domain, "params=%p, nparams=%p", params, nparams);
4182
4183
virResetLastError();
4184
4185
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
4186
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4187
virDispatchError(NULL);
4188
return -1;
4189
}
4190
conn = domain->conn;
4191
4192
if (conn->driver->domainGetSchedulerParameters) {
4193
int ret;
4194
ret = conn->driver->domainGetSchedulerParameters (domain, params, nparams);
4195
if (ret < 0)
4196
goto error;
4197
return ret;
4198
}
4199
4200
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4201
4202
error:
4203
virDispatchError(domain->conn);
4204
return -1;
4205
}
4206
4207
/**
4208
* virDomainSetSchedulerParameters:
4209
* @domain: pointer to domain object
4210
* @params: pointer to scheduler parameter objects
4211
* @nparams: number of scheduler parameter
4212
* (this value should be same or less than the returned value
4213
* nparams of virDomainGetSchedulerType)
4214
*
4215
* Change the scheduler parameters
4216
*
4217
* Returns -1 in case of error, 0 in case of success.
4218
*/
4219
int
4220
virDomainSetSchedulerParameters(virDomainPtr domain,
4221
virSchedParameterPtr params, int nparams)
4222
{
4223
virConnectPtr conn;
4224
4225
VIR_DOMAIN_DEBUG(domain, "params=%p, nparams=%d", params, nparams);
4226
4227
virResetLastError();
4228
4229
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
4230
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4231
virDispatchError(NULL);
4232
return -1;
4233
}
4234
if (domain->conn->flags & VIR_CONNECT_RO) {
4235
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
4236
goto error;
4237
}
4238
conn = domain->conn;
4239
4240
if (conn->driver->domainSetSchedulerParameters) {
4241
int ret;
4242
ret = conn->driver->domainSetSchedulerParameters (domain, params, nparams);
4243
if (ret < 0)
4244
goto error;
4245
return ret;
4246
}
4247
4248
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4249
4250
error:
4251
virDispatchError(domain->conn);
4252
return -1;
4253
}
4254
4255
4256
/**
4257
* virDomainBlockStats:
4258
* @dom: pointer to the domain object
4259
* @path: path to the block device
4260
* @stats: block device stats (returned)
4261
* @size: size of stats structure
4262
*
4263
* This function returns block device (disk) stats for block
4264
* devices attached to the domain.
4265
*
4266
* The path parameter is the name of the block device. Get this
4267
* by calling virDomainGetXMLDesc and finding the <target dev='...'>
4268
* attribute within //domain/devices/disk. (For example, "xvda").
4269
*
4270
* Domains may have more than one block device. To get stats for
4271
* each you should make multiple calls to this function.
4272
*
4273
* Individual fields within the stats structure may be returned
4274
* as -1, which indicates that the hypervisor does not support
4275
* that particular statistic.
4276
*
4277
* Returns: 0 in case of success or -1 in case of failure.
4278
*/
4279
int
4280
virDomainBlockStats (virDomainPtr dom, const char *path,
4281
virDomainBlockStatsPtr stats, size_t size)
4282
{
4283
virConnectPtr conn;
4284
struct _virDomainBlockStats stats2 = { -1, -1, -1, -1, -1 };
4285
4286
VIR_DOMAIN_DEBUG(dom, "path=%s, stats=%p, size=%zi", path, stats, size);
4287
4288
virResetLastError();
4289
4290
if (!VIR_IS_CONNECTED_DOMAIN (dom)) {
4291
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4292
virDispatchError(NULL);
4293
return -1;
4294
}
4295
if (!path || !stats || size > sizeof stats2) {
4296
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
4297
goto error;
4298
}
4299
conn = dom->conn;
4300
4301
if (conn->driver->domainBlockStats) {
4302
if (conn->driver->domainBlockStats (dom, path, &stats2) == -1)
4303
goto error;
4304
4305
memcpy (stats, &stats2, size);
4306
return 0;
4307
}
4308
4309
virLibDomainError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4310
4311
error:
4312
virDispatchError(dom->conn);
4313
return -1;
4314
}
4315
4316
/**
4317
* virDomainInterfaceStats:
4318
* @dom: pointer to the domain object
4319
* @path: path to the interface
4320
* @stats: network interface stats (returned)
4321
* @size: size of stats structure
4322
*
4323
* This function returns network interface stats for interfaces
4324
* attached to the domain.
4325
*
4326
* The path parameter is the name of the network interface.
4327
*
4328
* Domains may have more than one network interface. To get stats for
4329
* each you should make multiple calls to this function.
4330
*
4331
* Individual fields within the stats structure may be returned
4332
* as -1, which indicates that the hypervisor does not support
4333
* that particular statistic.
4334
*
4335
* Returns: 0 in case of success or -1 in case of failure.
4336
*/
4337
int
4338
virDomainInterfaceStats (virDomainPtr dom, const char *path,
4339
virDomainInterfaceStatsPtr stats, size_t size)
4340
{
4341
virConnectPtr conn;
4342
struct _virDomainInterfaceStats stats2 = { -1, -1, -1, -1,
4343
-1, -1, -1, -1 };
4344
4345
VIR_DOMAIN_DEBUG(dom, "path=%s, stats=%p, size=%zi",
4346
path, stats, size);
4347
4348
virResetLastError();
4349
4350
if (!VIR_IS_CONNECTED_DOMAIN (dom)) {
4351
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4352
virDispatchError(NULL);
4353
return -1;
4354
}
4355
if (!path || !stats || size > sizeof stats2) {
4356
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
4357
goto error;
4358
}
4359
conn = dom->conn;
4360
4361
if (conn->driver->domainInterfaceStats) {
4362
if (conn->driver->domainInterfaceStats (dom, path, &stats2) == -1)
4363
goto error;
4364
4365
memcpy (stats, &stats2, size);
4366
return 0;
4367
}
4368
4369
virLibDomainError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4370
4371
error:
4372
virDispatchError(dom->conn);
4373
return -1;
4374
}
4375
4376
/**
4377
* virDomainMemoryStats:
4378
* @dom: pointer to the domain object
4379
* @stats: nr_stats-sized array of stat structures (returned)
4380
* @nr_stats: number of memory statistics requested
4381
* @flags: unused, always pass 0
4382
*
4383
* This function provides memory statistics for the domain.
4384
*
4385
* Up to 'nr_stats' elements of 'stats' will be populated with memory statistics
4386
* from the domain. Only statistics supported by the domain, the driver, and
4387
* this version of libvirt will be returned.
4388
*
4389
* Memory Statistics:
4390
*
4391
* VIR_DOMAIN_MEMORY_STAT_SWAP_IN:
4392
* The total amount of data read from swap space (in kb).
4393
* VIR_DOMAIN_MEMORY_STAT_SWAP_OUT:
4394
* The total amount of memory written out to swap space (in kb).
4395
* VIR_DOMAIN_MEMORY_STAT_MAJOR_FAULT:
4396
* The number of page faults that required disk IO to service.
4397
* VIR_DOMAIN_MEMORY_STAT_MINOR_FAULT:
4398
* The number of page faults serviced without disk IO.
4399
* VIR_DOMAIN_MEMORY_STAT_UNUSED:
4400
* The amount of memory which is not being used for any purpose (in kb).
4401
* VIR_DOMAIN_MEMORY_STAT_AVAILABLE:
4402
* The total amount of memory available to the domain's OS (in kb).
4403
*
4404
* Returns: The number of stats provided or -1 in case of failure.
4405
*/
4406
int virDomainMemoryStats (virDomainPtr dom, virDomainMemoryStatPtr stats,
4407
unsigned int nr_stats, unsigned int flags)
4408
{
4409
virConnectPtr conn;
4410
unsigned long nr_stats_ret = 0;
4411
4412
VIR_DOMAIN_DEBUG(dom, "stats=%p, nr_stats=%u", stats, nr_stats);
4413
4414
virResetLastError();
4415
4416
if (!VIR_IS_CONNECTED_DOMAIN (dom)) {
4417
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4418
virDispatchError(NULL);
4419
return -1;
4420
}
4421
if (flags != 0) {
4422
virLibDomainError(VIR_ERR_INVALID_ARG,
4423
_("flags must be zero"));
4424
goto error;
4425
}
4426
4427
if (!stats || nr_stats == 0)
4428
return 0;
4429
4430
if (nr_stats > VIR_DOMAIN_MEMORY_STAT_NR)
4431
nr_stats = VIR_DOMAIN_MEMORY_STAT_NR;
4432
4433
conn = dom->conn;
4434
if (conn->driver->domainMemoryStats) {
4435
nr_stats_ret = conn->driver->domainMemoryStats (dom, stats, nr_stats);
4436
if (nr_stats_ret == -1)
4437
goto error;
4438
return nr_stats_ret;
4439
}
4440
4441
virLibDomainError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4442
4443
error:
4444
virDispatchError(dom->conn);
4445
return -1;
4446
}
4447
4448
/**
4449
* virDomainBlockPeek:
4450
* @dom: pointer to the domain object
4451
* @path: path to the block device
4452
* @offset: offset within block device
4453
* @size: size to read
4454
* @buffer: return buffer (must be at least size bytes)
4455
* @flags: unused, always pass 0
4456
*
4457
* This function allows you to read the contents of a domain's
4458
* disk device.
4459
*
4460
* Typical uses for this are to determine if the domain has
4461
* written a Master Boot Record (indicating that the domain
4462
* has completed installation), or to try to work out the state
4463
* of the domain's filesystems.
4464
*
4465
* (Note that in the local case you might try to open the
4466
* block device or file directly, but that won't work in the
4467
* remote case, nor if you don't have sufficient permission.
4468
* Hence the need for this call).
4469
*
4470
* 'path' must be a device or file corresponding to the domain.
4471
* In other words it must be the precise string returned in
4472
* a <disk><source dev='...'/></disk> from
4473
* virDomainGetXMLDesc.
4474
*
4475
* 'offset' and 'size' represent an area which must lie entirely
4476
* within the device or file. 'size' may be 0 to test if the
4477
* call would succeed.
4478
*
4479
* 'buffer' is the return buffer and must be at least 'size' bytes.
4480
*
4481
* NB. The remote driver imposes a 64K byte limit on 'size'.
4482
* For your program to be able to work reliably over a remote
4483
* connection you should split large requests to <= 65536 bytes.
4484
*
4485
* Returns: 0 in case of success or -1 in case of failure.
4486
*/
4487
int
4488
virDomainBlockPeek (virDomainPtr dom,
4489
const char *path,
4490
unsigned long long offset /* really 64 bits */,
4491
size_t size,
4492
void *buffer,
4493
unsigned int flags)
4494
{
4495
virConnectPtr conn;
4496
4497
VIR_DOMAIN_DEBUG(dom, "path=%s, offset=%lld, size=%zi, buffer=%p",
4498
path, offset, size, buffer);
4499
4500
virResetLastError();
4501
4502
if (!VIR_IS_CONNECTED_DOMAIN (dom)) {
4503
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4504
virDispatchError(NULL);
4505
return -1;
4506
}
4507
conn = dom->conn;
4508
4509
if (dom->conn->flags & VIR_CONNECT_RO) {
4510
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
4511
goto error;
4512
}
4513
4514
if (!path) {
4515
virLibDomainError(VIR_ERR_INVALID_ARG,
4516
_("path is NULL"));
4517
goto error;
4518
}
4519
4520
if (flags != 0) {
4521
virLibDomainError(VIR_ERR_INVALID_ARG,
4522
_("flags must be zero"));
4523
goto error;
4524
}
4525
4526
/* Allow size == 0 as an access test. */
4527
if (size > 0 && !buffer) {
4528
virLibDomainError(VIR_ERR_INVALID_ARG,
4529
_("buffer is NULL"));
4530
goto error;
4531
}
4532
4533
if (conn->driver->domainBlockPeek) {
4534
int ret;
4535
ret =conn->driver->domainBlockPeek (dom, path, offset, size,
4536
buffer, flags);
4537
if (ret < 0)
4538
goto error;
4539
return ret;
4540
}
4541
4542
virLibDomainError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4543
4544
error:
4545
virDispatchError(dom->conn);
4546
return -1;
4547
}
4548
4549
/**
4550
* virDomainMemoryPeek:
4551
* @dom: pointer to the domain object
4552
* @start: start of memory to peek
4553
* @size: size of memory to peek
4554
* @buffer: return buffer (must be at least size bytes)
4555
* @flags: flags, see below
4556
*
4557
* This function allows you to read the contents of a domain's
4558
* memory.
4559
*
4560
* The memory which is read is controlled by the 'start', 'size'
4561
* and 'flags' parameters.
4562
*
4563
* If 'flags' is VIR_MEMORY_VIRTUAL then the 'start' and 'size'
4564
* parameters are interpreted as virtual memory addresses for
4565
* whichever task happens to be running on the domain at the
4566
* moment. Although this sounds haphazard it is in fact what
4567
* you want in order to read Linux kernel state, because it
4568
* ensures that pointers in the kernel image can be interpreted
4569
* coherently.
4570
*
4571
* 'buffer' is the return buffer and must be at least 'size' bytes.
4572
* 'size' may be 0 to test if the call would succeed.
4573
*
4574
* NB. The remote driver imposes a 64K byte limit on 'size'.
4575
* For your program to be able to work reliably over a remote
4576
* connection you should split large requests to <= 65536 bytes.
4577
*
4578
* Returns: 0 in case of success or -1 in case of failure.
4579
*/
4580
int
4581
virDomainMemoryPeek (virDomainPtr dom,
4582
unsigned long long start /* really 64 bits */,
4583
size_t size,
4584
void *buffer,
4585
unsigned int flags)
4586
{
4587
virConnectPtr conn;
4588
4589
VIR_DOMAIN_DEBUG(dom, "start=%lld, size=%zi, buffer=%p, flags=%d",
4590
start, size, buffer, flags);
4591
4592
virResetLastError();
4593
4594
if (!VIR_IS_CONNECTED_DOMAIN (dom)) {
4595
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4596
virDispatchError(NULL);
4597
return -1;
4598
}
4599
conn = dom->conn;
4600
4601
if (dom->conn->flags & VIR_CONNECT_RO) {
4602
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
4603
goto error;
4604
}
4605
4606
/* Note on access to physical memory: A VIR_MEMORY_PHYSICAL flag is
4607
* a possibility. However it isn't really useful unless the caller
4608
* can also access registers, particularly CR3 on x86 in order to
4609
* get the Page Table Directory. Since registers are different on
4610
* every architecture, that would imply another call to get the
4611
* machine registers.
4612
*
4613
* The QEMU driver handles VIR_MEMORY_VIRTUAL, mapping it
4614
* to the qemu 'memsave' command which does the virtual to physical
4615
* mapping inside qemu.
4616
*
4617
* The QEMU driver also handles VIR_MEMORY_PHYSICAL, mapping it
4618
* to the qemu 'pmemsave' command.
4619
*
4620
* At time of writing there is no Xen driver. However the Xen
4621
* hypervisor only lets you map physical pages from other domains,
4622
* and so the Xen driver would have to do the virtual to physical
4623
* mapping by chasing 2, 3 or 4-level page tables from the PTD.
4624
* There is example code in libxc (xc_translate_foreign_address)
4625
* which does this, although we cannot copy this code directly
4626
* because of incompatible licensing.
4627
*/
4628
4629
if (flags != VIR_MEMORY_VIRTUAL && flags != VIR_MEMORY_PHYSICAL) {
4630
virLibDomainError(VIR_ERR_INVALID_ARG,
4631
_("flags parameter must be VIR_MEMORY_VIRTUAL or VIR_MEMORY_PHYSICAL"));
4632
goto error;
4633
}
4634
4635
/* Allow size == 0 as an access test. */
4636
if (size > 0 && !buffer) {
4637
virLibDomainError(VIR_ERR_INVALID_ARG,
4638
_("buffer is NULL but size is non-zero"));
4639
goto error;
4640
}
4641
4642
if (conn->driver->domainMemoryPeek) {
4643
int ret;
4644
ret = conn->driver->domainMemoryPeek (dom, start, size,
4645
buffer, flags);
4646
if (ret < 0)
4647
goto error;
4648
return ret;
4649
}
4650
4651
virLibDomainError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4652
4653
error:
4654
virDispatchError(dom->conn);
4655
return -1;
4656
}
4657
4658
4659
/**
4660
* virDomainGetBlockInfo:
4661
* @domain: a domain object
4662
* @path: path to the block device or file
4663
* @info: pointer to a virDomainBlockInfo structure allocated by the user
4664
* @flags: currently unused, pass zero
4665
*
4666
* Extract information about a domain's block device.
4667
*
4668
* Returns 0 in case of success and -1 in case of failure.
4669
*/
4670
int
4671
virDomainGetBlockInfo(virDomainPtr domain, const char *path, virDomainBlockInfoPtr info, unsigned int flags)
4672
{
4673
virConnectPtr conn;
4674
4675
VIR_DOMAIN_DEBUG(domain, "info=%p flags=%u", info, flags);
4676
4677
virResetLastError();
4678
4679
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
4680
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4681
virDispatchError(NULL);
4682
return -1;
4683
}
4684
if (info == NULL) {
4685
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
4686
goto error;
4687
}
4688
4689
memset(info, 0, sizeof(virDomainBlockInfo));
4690
4691
conn = domain->conn;
4692
4693
if (conn->driver->domainGetBlockInfo) {
4694
int ret;
4695
ret = conn->driver->domainGetBlockInfo (domain, path, info, flags);
4696
if (ret < 0)
4697
goto error;
4698
return ret;
4699
}
4700
4701
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4702
4703
error:
4704
virDispatchError(domain->conn);
4705
return -1;
4706
}
4707
4708
4709
/************************************************************************
4710
* *
4711
* Handling of defined but not running domains *
4712
* *
4713
************************************************************************/
4714
4715
/**
4716
* virDomainDefineXML:
4717
* @conn: pointer to the hypervisor connection
4718
* @xml: the XML description for the domain, preferably in UTF-8
4719
*
4720
* Define a domain, but does not start it.
4721
* This definition is persistent, until explicitly undefined with
4722
* virDomainUndefine(). A previous definition for this domain would be
4723
* overriden if it already exists.
4724
*
4725
* Returns NULL in case of error, a pointer to the domain otherwise
4726
*/
4727
virDomainPtr
4728
virDomainDefineXML(virConnectPtr conn, const char *xml) {
4729
DEBUG("conn=%p, xml=%s", conn, xml);
4730
4731
virResetLastError();
4732
4733
if (!VIR_IS_CONNECT(conn)) {
4734
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
4735
virDispatchError(NULL);
4736
return NULL;
4737
}
4738
if (conn->flags & VIR_CONNECT_RO) {
4739
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
4740
goto error;
4741
}
4742
if (xml == NULL) {
4743
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
4744
goto error;
4745
}
4746
4747
if (conn->driver->domainDefineXML) {
4748
virDomainPtr ret;
4749
ret = conn->driver->domainDefineXML (conn, xml);
4750
if (!ret)
4751
goto error;
4752
return ret;
4753
}
4754
4755
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4756
4757
error:
4758
virDispatchError(conn);
4759
return NULL;
4760
}
4761
4762
/**
4763
* virDomainUndefine:
4764
* @domain: pointer to a defined domain
4765
*
4766
* Undefine a domain but does not stop it if it is running
4767
*
4768
* Returns 0 in case of success, -1 in case of error
4769
*/
4770
int
4771
virDomainUndefine(virDomainPtr domain) {
4772
virConnectPtr conn;
4773
4774
VIR_DOMAIN_DEBUG0(domain);
4775
4776
virResetLastError();
4777
4778
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
4779
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4780
virDispatchError(NULL);
4781
return -1;
4782
}
4783
conn = domain->conn;
4784
if (conn->flags & VIR_CONNECT_RO) {
4785
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
4786
goto error;
4787
}
4788
4789
if (conn->driver->domainUndefine) {
4790
int ret;
4791
ret = conn->driver->domainUndefine (domain);
4792
if (ret < 0)
4793
goto error;
4794
return ret;
4795
}
4796
4797
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4798
4799
error:
4800
virDispatchError(domain->conn);
4801
return -1;
4802
}
4803
4804
/**
4805
* virConnectNumOfDefinedDomains:
4806
* @conn: pointer to the hypervisor connection
4807
*
4808
* Provides the number of defined but inactive domains.
4809
*
4810
* Returns the number of domain found or -1 in case of error
4811
*/
4812
int
4813
virConnectNumOfDefinedDomains(virConnectPtr conn)
4814
{
4815
DEBUG("conn=%p", conn);
4816
4817
virResetLastError();
4818
4819
if (!VIR_IS_CONNECT(conn)) {
4820
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
4821
virDispatchError(NULL);
4822
return -1;
4823
}
4824
4825
if (conn->driver->numOfDefinedDomains) {
4826
int ret;
4827
ret = conn->driver->numOfDefinedDomains (conn);
4828
if (ret < 0)
4829
goto error;
4830
return ret;
4831
}
4832
4833
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4834
4835
error:
4836
virDispatchError(conn);
4837
return -1;
4838
}
4839
4840
/**
4841
* virConnectListDefinedDomains:
4842
* @conn: pointer to the hypervisor connection
4843
* @names: pointer to an array to store the names
4844
* @maxnames: size of the array
4845
*
4846
* list the defined but inactive domains, stores the pointers to the names
4847
* in @names
4848
*
4849
* Returns the number of names provided in the array or -1 in case of error
4850
*/
4851
int
4852
virConnectListDefinedDomains(virConnectPtr conn, char **const names,
4853
int maxnames) {
4854
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
4855
4856
virResetLastError();
4857
4858
if (!VIR_IS_CONNECT(conn)) {
4859
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
4860
virDispatchError(NULL);
4861
return -1;
4862
}
4863
4864
if ((names == NULL) || (maxnames < 0)) {
4865
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
4866
goto error;
4867
}
4868
4869
if (conn->driver->listDefinedDomains) {
4870
int ret;
4871
ret = conn->driver->listDefinedDomains (conn, names, maxnames);
4872
if (ret < 0)
4873
goto error;
4874
return ret;
4875
}
4876
4877
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4878
4879
error:
4880
virDispatchError(conn);
4881
return -1;
4882
}
4883
4884
/**
4885
* virDomainCreate:
4886
* @domain: pointer to a defined domain
4887
*
4888
* Launch a defined domain. If the call succeeds the domain moves from the
4889
* defined to the running domains pools.
4890
*
4891
* Returns 0 in case of success, -1 in case of error
4892
*/
4893
int
4894
virDomainCreate(virDomainPtr domain) {
4895
virConnectPtr conn;
4896
4897
VIR_DOMAIN_DEBUG0(domain);
4898
4899
virResetLastError();
4900
4901
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
4902
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4903
virDispatchError(NULL);
4904
return -1;
4905
}
4906
conn = domain->conn;
4907
if (conn->flags & VIR_CONNECT_RO) {
4908
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
4909
goto error;
4910
}
4911
4912
if (conn->driver->domainCreate) {
4913
int ret;
4914
ret = conn->driver->domainCreate (domain);
4915
if (ret < 0)
4916
goto error;
4917
return ret;
4918
}
4919
4920
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4921
4922
error:
4923
virDispatchError(domain->conn);
4924
return -1;
4925
}
4926
4927
/**
4928
* virDomainCreateWithFlags:
4929
* @domain: pointer to a defined domain
4930
* @flags: bitwise-or of supported virDomainCreateFlags
4931
*
4932
* Launch a defined domain. If the call succeeds the domain moves from the
4933
* defined to the running domains pools.
4934
*
4935
* Returns 0 in case of success, -1 in case of error
4936
*/
4937
int
4938
virDomainCreateWithFlags(virDomainPtr domain, unsigned int flags) {
4939
virConnectPtr conn;
4940
4941
VIR_DOMAIN_DEBUG(domain, "flags=%d", flags);
4942
4943
virResetLastError();
4944
4945
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
4946
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4947
virDispatchError(NULL);
4948
return -1;
4949
}
4950
conn = domain->conn;
4951
if (conn->flags & VIR_CONNECT_RO) {
4952
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
4953
goto error;
4954
}
4955
4956
if (conn->driver->domainCreateWithFlags) {
4957
int ret;
4958
ret = conn->driver->domainCreateWithFlags (domain, flags);
4959
if (ret < 0)
4960
goto error;
4961
return ret;
4962
}
4963
4964
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
4965
4966
error:
4967
virDispatchError(domain->conn);
4968
return -1;
4969
}
4970
4971
/**
4972
* virDomainGetAutostart:
4973
* @domain: a domain object
4974
* @autostart: the value returned
4975
*
4976
* Provides a boolean value indicating whether the domain
4977
* configured to be automatically started when the host
4978
* machine boots.
4979
*
4980
* Returns -1 in case of error, 0 in case of success
4981
*/
4982
int
4983
virDomainGetAutostart(virDomainPtr domain,
4984
int *autostart)
4985
{
4986
virConnectPtr conn;
4987
4988
VIR_DOMAIN_DEBUG(domain, "autostart=%p", autostart);
4989
4990
virResetLastError();
4991
4992
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
4993
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
4994
virDispatchError(NULL);
4995
return -1;
4996
}
4997
if (!autostart) {
4998
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
4999
goto error;
5000
}
5001
5002
conn = domain->conn;
5003
5004
if (conn->driver->domainGetAutostart) {
5005
int ret;
5006
ret = conn->driver->domainGetAutostart (domain, autostart);
5007
if (ret < 0)
5008
goto error;
5009
return ret;
5010
}
5011
5012
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5013
5014
error:
5015
virDispatchError(domain->conn);
5016
return -1;
5017
}
5018
5019
/**
5020
* virDomainSetAutostart:
5021
* @domain: a domain object
5022
* @autostart: whether the domain should be automatically started 0 or 1
5023
*
5024
* Configure the domain to be automatically started
5025
* when the host machine boots.
5026
*
5027
* Returns -1 in case of error, 0 in case of success
5028
*/
5029
int
5030
virDomainSetAutostart(virDomainPtr domain,
5031
int autostart)
5032
{
5033
virConnectPtr conn;
5034
5035
VIR_DOMAIN_DEBUG(domain, "autostart=%d", autostart);
5036
5037
virResetLastError();
5038
5039
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5040
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5041
virDispatchError(NULL);
5042
return -1;
5043
}
5044
5045
conn = domain->conn;
5046
5047
if (domain->conn->flags & VIR_CONNECT_RO) {
5048
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
5049
goto error;
5050
}
5051
5052
if (conn->driver->domainSetAutostart) {
5053
int ret;
5054
ret = conn->driver->domainSetAutostart (domain, autostart);
5055
if (ret < 0)
5056
goto error;
5057
return ret;
5058
}
5059
5060
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5061
5062
error:
5063
virDispatchError(domain->conn);
5064
return -1;
5065
}
5066
5067
/**
5068
* virDomainSetVcpus:
5069
* @domain: pointer to domain object, or NULL for Domain0
5070
* @nvcpus: the new number of virtual CPUs for this domain
5071
*
5072
* Dynamically change the number of virtual CPUs used by the domain.
5073
* Note that this call may fail if the underlying virtualization hypervisor
5074
* does not support it or if growing the number is arbitrary limited.
5075
* This function requires privileged access to the hypervisor.
5076
*
5077
* This command only changes the runtime configuration of the domain,
5078
* so can only be called on an active domain. It is hypervisor-dependent
5079
* whether it also affects persistent configuration; for more control,
5080
* use virDomainSetVcpusFlags().
5081
*
5082
* Returns 0 in case of success, -1 in case of failure.
5083
*/
5084
5085
int
5086
virDomainSetVcpus(virDomainPtr domain, unsigned int nvcpus)
5087
{
5088
virConnectPtr conn;
5089
5090
VIR_DOMAIN_DEBUG(domain, "nvcpus=%u", nvcpus);
5091
5092
virResetLastError();
5093
5094
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5095
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5096
virDispatchError(NULL);
5097
return -1;
5098
}
5099
if (domain->conn->flags & VIR_CONNECT_RO) {
5100
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
5101
goto error;
5102
}
5103
5104
if (nvcpus < 1) {
5105
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
5106
goto error;
5107
}
5108
conn = domain->conn;
5109
5110
if (conn->driver->domainSetVcpus) {
5111
int ret;
5112
ret = conn->driver->domainSetVcpus (domain, nvcpus);
5113
if (ret < 0)
5114
goto error;
5115
return ret;
5116
}
5117
5118
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5119
5120
error:
5121
virDispatchError(domain->conn);
5122
return -1;
5123
}
5124
5125
/**
5126
* virDomainSetVcpusFlags:
5127
* @domain: pointer to domain object, or NULL for Domain0
5128
* @nvcpus: the new number of virtual CPUs for this domain, must be at least 1
5129
* @flags: an OR'ed set of virDomainVcpuFlags
5130
*
5131
* Dynamically change the number of virtual CPUs used by the domain.
5132
* Note that this call may fail if the underlying virtualization hypervisor
5133
* does not support it or if growing the number is arbitrary limited.
5134
* This function requires privileged access to the hypervisor.
5135
*
5136
* @flags must include VIR_DOMAIN_VCPU_LIVE to affect a running
5137
* domain (which may fail if domain is not active), or
5138
* VIR_DOMAIN_VCPU_CONFIG to affect the next boot via the XML
5139
* description of the domain. Both flags may be set.
5140
*
5141
* If @flags includes VIR_DOMAIN_VCPU_MAXIMUM, then
5142
* VIR_DOMAIN_VCPU_LIVE must be clear, and only the maximum virtual
5143
* CPU limit is altered; generally, this value must be less than or
5144
* equal to virConnectGetMaxVcpus(). Otherwise, this call affects the
5145
* current virtual CPU limit, which must be less than or equal to the
5146
* maximum limit.
5147
*
5148
* Returns 0 in case of success, -1 in case of failure.
5149
*/
5150
5151
int
5152
virDomainSetVcpusFlags(virDomainPtr domain, unsigned int nvcpus,
5153
unsigned int flags)
5154
{
5155
virConnectPtr conn;
5156
5157
VIR_DOMAIN_DEBUG(domain, "nvcpus=%u, flags=%u", nvcpus, flags);
5158
5159
virResetLastError();
5160
5161
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5162
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5163
virDispatchError(NULL);
5164
return -1;
5165
}
5166
if (domain->conn->flags & VIR_CONNECT_RO) {
5167
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
5168
goto error;
5169
}
5170
5171
/* Perform some argument validation common to all implementations. */
5172
if (nvcpus < 1 || (unsigned short) nvcpus != nvcpus ||
5173
(flags & (VIR_DOMAIN_VCPU_LIVE | VIR_DOMAIN_VCPU_CONFIG)) == 0) {
5174
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
5175
goto error;
5176
}
5177
conn = domain->conn;
5178
5179
if (conn->driver->domainSetVcpusFlags) {
5180
int ret;
5181
ret = conn->driver->domainSetVcpusFlags (domain, nvcpus, flags);
5182
if (ret < 0)
5183
goto error;
5184
return ret;
5185
}
5186
5187
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5188
5189
error:
5190
virDispatchError(domain->conn);
5191
return -1;
5192
}
5193
5194
/**
5195
* virDomainGetVcpusFlags:
5196
* @domain: pointer to domain object, or NULL for Domain0
5197
* @flags: an OR'ed set of virDomainVcpuFlags
5198
*
5199
* Query the number of virtual CPUs used by the domain. Note that
5200
* this call may fail if the underlying virtualization hypervisor does
5201
* not support it. This function requires privileged access to the
5202
* hypervisor.
5203
*
5204
* @flags must include either VIR_DOMAIN_VCPU_ACTIVE to query a
5205
* running domain (which will fail if domain is not active), or
5206
* VIR_DOMAIN_VCPU_PERSISTENT to query the XML description of the
5207
* domain. It is an error to set both flags.
5208
*
5209
* If @flags includes VIR_DOMAIN_VCPU_MAXIMUM, then the maximum
5210
* virtual CPU limit is queried. Otherwise, this call queries the
5211
* current virtual CPU limit.
5212
*
5213
* Returns 0 in case of success, -1 in case of failure.
5214
*/
5215
5216
int
5217
virDomainGetVcpusFlags(virDomainPtr domain, unsigned int flags)
5218
{
5219
virConnectPtr conn;
5220
5221
VIR_DOMAIN_DEBUG(domain, "flags=%u", flags);
5222
5223
virResetLastError();
5224
5225
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5226
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5227
virDispatchError(NULL);
5228
return -1;
5229
}
5230
5231
/* Exactly one of these two flags should be set. */
5232
if (!(flags & VIR_DOMAIN_VCPU_LIVE) == !(flags & VIR_DOMAIN_VCPU_CONFIG)) {
5233
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
5234
goto error;
5235
}
5236
conn = domain->conn;
5237
5238
if (conn->driver->domainGetVcpusFlags) {
5239
int ret;
5240
ret = conn->driver->domainGetVcpusFlags (domain, flags);
5241
if (ret < 0)
5242
goto error;
5243
return ret;
5244
}
5245
5246
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5247
5248
error:
5249
virDispatchError(domain->conn);
5250
return -1;
5251
}
5252
5253
/**
5254
* virDomainPinVcpu:
5255
* @domain: pointer to domain object, or NULL for Domain0
5256
* @vcpu: virtual CPU number
5257
* @cpumap: pointer to a bit map of real CPUs (in 8-bit bytes) (IN)
5258
* Each bit set to 1 means that corresponding CPU is usable.
5259
* Bytes are stored in little-endian order: CPU0-7, 8-15...
5260
* In each byte, lowest CPU number is least significant bit.
5261
* @maplen: number of bytes in cpumap, from 1 up to size of CPU map in
5262
* underlying virtualization system (Xen...).
5263
* If maplen < size, missing bytes are set to zero.
5264
* If maplen > size, failure code is returned.
5265
*
5266
* Dynamically change the real CPUs which can be allocated to a virtual CPU.
5267
* This function requires privileged access to the hypervisor.
5268
*
5269
* This command only changes the runtime configuration of the domain,
5270
* so can only be called on an active domain.
5271
*
5272
* Returns 0 in case of success, -1 in case of failure.
5273
*/
5274
int
5275
virDomainPinVcpu(virDomainPtr domain, unsigned int vcpu,
5276
unsigned char *cpumap, int maplen)
5277
{
5278
virConnectPtr conn;
5279
5280
VIR_DOMAIN_DEBUG(domain, "vcpu=%u, cpumap=%p, maplen=%d",
5281
vcpu, cpumap, maplen);
5282
5283
virResetLastError();
5284
5285
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5286
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5287
virDispatchError(NULL);
5288
return -1;
5289
}
5290
if (domain->conn->flags & VIR_CONNECT_RO) {
5291
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
5292
goto error;
5293
}
5294
5295
if ((vcpu > 32000) || (cpumap == NULL) || (maplen < 1)) {
5296
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
5297
goto error;
5298
}
5299
5300
conn = domain->conn;
5301
5302
if (conn->driver->domainPinVcpu) {
5303
int ret;
5304
ret = conn->driver->domainPinVcpu (domain, vcpu, cpumap, maplen);
5305
if (ret < 0)
5306
goto error;
5307
return ret;
5308
}
5309
5310
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5311
5312
error:
5313
virDispatchError(domain->conn);
5314
return -1;
5315
}
5316
5317
/**
5318
* virDomainGetVcpus:
5319
* @domain: pointer to domain object, or NULL for Domain0
5320
* @info: pointer to an array of virVcpuInfo structures (OUT)
5321
* @maxinfo: number of structures in info array
5322
* @cpumaps: pointer to a bit map of real CPUs for all vcpus of this
5323
* domain (in 8-bit bytes) (OUT)
5324
* If cpumaps is NULL, then no cpumap information is returned by the API.
5325
* It's assumed there is <maxinfo> cpumap in cpumaps array.
5326
* The memory allocated to cpumaps must be (maxinfo * maplen) bytes
5327
* (ie: calloc(maxinfo, maplen)).
5328
* One cpumap inside cpumaps has the format described in
5329
* virDomainPinVcpu() API.
5330
* @maplen: number of bytes in one cpumap, from 1 up to size of CPU map in
5331
* underlying virtualization system (Xen...).
5332
* Must be zero when cpumaps is NULL and positive when it is non-NULL.
5333
*
5334
* Extract information about virtual CPUs of domain, store it in info array
5335
* and also in cpumaps if this pointer isn't NULL.
5336
*
5337
* Returns the number of info filled in case of success, -1 in case of failure.
5338
*/
5339
int
5340
virDomainGetVcpus(virDomainPtr domain, virVcpuInfoPtr info, int maxinfo,
5341
unsigned char *cpumaps, int maplen)
5342
{
5343
virConnectPtr conn;
5344
5345
VIR_DOMAIN_DEBUG(domain, "info=%p, maxinfo=%d, cpumaps=%p, maplen=%d",
5346
info, maxinfo, cpumaps, maplen);
5347
5348
virResetLastError();
5349
5350
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5351
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5352
virDispatchError(NULL);
5353
return -1;
5354
}
5355
if ((info == NULL) || (maxinfo < 1)) {
5356
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
5357
goto error;
5358
}
5359
5360
/* Ensure that domainGetVcpus (aka remoteDomainGetVcpus) does not
5361
try to memcpy anything into a NULL pointer. */
5362
if ((cpumaps == NULL && maplen != 0)
5363
|| (cpumaps && maplen <= 0)) {
5364
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
5365
goto error;
5366
}
5367
5368
conn = domain->conn;
5369
5370
if (conn->driver->domainGetVcpus) {
5371
int ret;
5372
ret = conn->driver->domainGetVcpus (domain, info, maxinfo,
5373
cpumaps, maplen);
5374
if (ret < 0)
5375
goto error;
5376
return ret;
5377
}
5378
5379
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5380
5381
error:
5382
virDispatchError(domain->conn);
5383
return -1;
5384
}
5385
5386
/**
5387
* virDomainGetMaxVcpus:
5388
* @domain: pointer to domain object
5389
*
5390
* Provides the maximum number of virtual CPUs supported for
5391
* the guest VM. If the guest is inactive, this is basically
5392
* the same as virConnectGetMaxVcpus(). If the guest is running
5393
* this will reflect the maximum number of virtual CPUs the
5394
* guest was booted with. For more details, see virDomainGetVcpusFlags().
5395
*
5396
* Returns the maximum of virtual CPU or -1 in case of error.
5397
*/
5398
int
5399
virDomainGetMaxVcpus(virDomainPtr domain)
5400
{
5401
virConnectPtr conn;
5402
5403
VIR_DOMAIN_DEBUG0(domain);
5404
5405
virResetLastError();
5406
5407
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5408
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5409
virDispatchError(NULL);
5410
return -1;
5411
}
5412
5413
conn = domain->conn;
5414
5415
if (conn->driver->domainGetMaxVcpus) {
5416
int ret;
5417
ret = conn->driver->domainGetMaxVcpus (domain);
5418
if (ret < 0)
5419
goto error;
5420
return ret;
5421
}
5422
5423
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5424
5425
error:
5426
virDispatchError(domain->conn);
5427
return -1;
5428
}
5429
5430
/**
5431
* virDomainGetSecurityLabel:
5432
* @domain: a domain object
5433
* @seclabel: pointer to a virSecurityLabel structure
5434
*
5435
* Extract security label of an active domain. The 'label' field
5436
* in the @seclabel argument will be initialized to the empty
5437
* string if the domain is not running under a security model.
5438
*
5439
* Returns 0 in case of success, -1 in case of failure
5440
*/
5441
int
5442
virDomainGetSecurityLabel(virDomainPtr domain, virSecurityLabelPtr seclabel)
5443
{
5444
virConnectPtr conn;
5445
5446
VIR_DOMAIN_DEBUG(domain, "seclabel=%p", seclabel);
5447
5448
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5449
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5450
virDispatchError(NULL);
5451
return -1;
5452
}
5453
5454
if (seclabel == NULL) {
5455
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
5456
goto error;
5457
}
5458
5459
conn = domain->conn;
5460
5461
if (conn->driver->domainGetSecurityLabel) {
5462
int ret;
5463
ret = conn->driver->domainGetSecurityLabel(domain, seclabel);
5464
if (ret < 0)
5465
goto error;
5466
return ret;
5467
}
5468
5469
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5470
5471
error:
5472
virDispatchError(domain->conn);
5473
return -1;
5474
}
5475
5476
/**
5477
* virNodeGetSecurityModel:
5478
* @conn: a connection object
5479
* @secmodel: pointer to a virSecurityModel structure
5480
*
5481
* Extract the security model of a hypervisor. The 'model' field
5482
* in the @secmodel argument may be initialized to the empty
5483
* string if the driver has not activated a security model.
5484
*
5485
* Returns 0 in case of success, -1 in case of failure
5486
*/
5487
int
5488
virNodeGetSecurityModel(virConnectPtr conn, virSecurityModelPtr secmodel)
5489
{
5490
DEBUG("conn=%p secmodel=%p", conn, secmodel);
5491
5492
if (!VIR_IS_CONNECT(conn)) {
5493
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
5494
virDispatchError(NULL);
5495
return -1;
5496
}
5497
5498
if (secmodel == NULL) {
5499
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
5500
goto error;
5501
}
5502
5503
if (conn->driver->nodeGetSecurityModel) {
5504
int ret;
5505
ret = conn->driver->nodeGetSecurityModel(conn, secmodel);
5506
if (ret < 0)
5507
goto error;
5508
return ret;
5509
}
5510
5511
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5512
5513
error:
5514
virDispatchError(conn);
5515
return -1;
5516
}
5517
5518
/**
5519
* virDomainAttachDevice:
5520
* @domain: pointer to domain object
5521
* @xml: pointer to XML description of one device
5522
*
5523
* Create a virtual device attachment to backend. This function,
5524
* having hotplug semantics, is only allowed on an active domain.
5525
*
5526
* For compatibility, this method can also be used to change the media
5527
* in an existing CDROM/Floppy device, however, applications are
5528
* recommended to use the virDomainUpdateDeviceFlag method instead.
5529
*
5530
* Returns 0 in case of success, -1 in case of failure.
5531
*/
5532
int
5533
virDomainAttachDevice(virDomainPtr domain, const char *xml)
5534
{
5535
virConnectPtr conn;
5536
5537
VIR_DOMAIN_DEBUG(domain, "xml=%s", xml);
5538
5539
virResetLastError();
5540
5541
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5542
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5543
virDispatchError(NULL);
5544
return -1;
5545
}
5546
if (domain->conn->flags & VIR_CONNECT_RO) {
5547
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
5548
goto error;
5549
}
5550
conn = domain->conn;
5551
5552
if (conn->driver->domainAttachDevice) {
5553
int ret;
5554
ret = conn->driver->domainAttachDevice (domain, xml);
5555
if (ret < 0)
5556
goto error;
5557
return ret;
5558
}
5559
5560
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5561
5562
error:
5563
virDispatchError(domain->conn);
5564
return -1;
5565
}
5566
5567
/**
5568
* virDomainAttachDeviceFlags:
5569
* @domain: pointer to domain object
5570
* @xml: pointer to XML description of one device
5571
* @flags: an OR'ed set of virDomainDeviceModifyFlags
5572
*
5573
* Attach a virtual device to a domain, using the flags parameter
5574
* to control how the device is attached. VIR_DOMAIN_DEVICE_MODIFY_CURRENT
5575
* specifies that the device allocation is made based on current domain
5576
* state. VIR_DOMAIN_DEVICE_MODIFY_LIVE specifies that the device shall be
5577
* allocated to the active domain instance only and is not added to the
5578
* persisted domain configuration. VIR_DOMAIN_DEVICE_MODIFY_CONFIG
5579
* specifies that the device shall be allocated to the persisted domain
5580
* configuration only. Note that the target hypervisor must return an
5581
* error if unable to satisfy flags. E.g. the hypervisor driver will
5582
* return failure if LIVE is specified but it only supports modifying the
5583
* persisted device allocation.
5584
*
5585
* For compatibility, this method can also be used to change the media
5586
* in an existing CDROM/Floppy device, however, applications are
5587
* recommended to use the virDomainUpdateDeviceFlag method instead.
5588
*
5589
* Returns 0 in case of success, -1 in case of failure.
5590
*/
5591
int
5592
virDomainAttachDeviceFlags(virDomainPtr domain,
5593
const char *xml, unsigned int flags)
5594
{
5595
virConnectPtr conn;
5596
5597
VIR_DOMAIN_DEBUG(domain, "xml=%s, flags=%d", xml, flags);
5598
5599
virResetLastError();
5600
5601
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5602
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5603
virDispatchError(NULL);
5604
return -1;
5605
}
5606
if (domain->conn->flags & VIR_CONNECT_RO) {
5607
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
5608
goto error;
5609
}
5610
conn = domain->conn;
5611
5612
if (conn->driver->domainAttachDeviceFlags) {
5613
int ret;
5614
ret = conn->driver->domainAttachDeviceFlags(domain, xml, flags);
5615
if (ret < 0)
5616
goto error;
5617
return ret;
5618
}
5619
5620
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5621
5622
error:
5623
virDispatchError(domain->conn);
5624
return -1;
5625
}
5626
5627
/**
5628
* virDomainDetachDevice:
5629
* @domain: pointer to domain object
5630
* @xml: pointer to XML description of one device
5631
*
5632
* Destroy a virtual device attachment to backend. This function,
5633
* having hot-unplug semantics, is only allowed on an active domain.
5634
*
5635
* Returns 0 in case of success, -1 in case of failure.
5636
*/
5637
int
5638
virDomainDetachDevice(virDomainPtr domain, const char *xml)
5639
{
5640
virConnectPtr conn;
5641
5642
VIR_DOMAIN_DEBUG(domain, "xml=%s", xml);
5643
5644
virResetLastError();
5645
5646
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5647
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5648
virDispatchError(NULL);
5649
return -1;
5650
}
5651
if (domain->conn->flags & VIR_CONNECT_RO) {
5652
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
5653
goto error;
5654
}
5655
conn = domain->conn;
5656
5657
if (conn->driver->domainDetachDevice) {
5658
int ret;
5659
ret = conn->driver->domainDetachDevice (domain, xml);
5660
if (ret < 0)
5661
goto error;
5662
return ret;
5663
}
5664
5665
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5666
5667
error:
5668
virDispatchError(domain->conn);
5669
return -1;
5670
}
5671
5672
/**
5673
* virDomainDetachDeviceFlags:
5674
* @domain: pointer to domain object
5675
* @xml: pointer to XML description of one device
5676
* @flags: an OR'ed set of virDomainDeviceModifyFlags
5677
*
5678
* Detach a virtual device from a domain, using the flags parameter
5679
* to control how the device is detached. VIR_DOMAIN_DEVICE_MODIFY_CURRENT
5680
* specifies that the device allocation is removed based on current domain
5681
* state. VIR_DOMAIN_DEVICE_MODIFY_LIVE specifies that the device shall be
5682
* deallocated from the active domain instance only and is not from the
5683
* persisted domain configuration. VIR_DOMAIN_DEVICE_MODIFY_CONFIG
5684
* specifies that the device shall be deallocated from the persisted domain
5685
* configuration only. Note that the target hypervisor must return an
5686
* error if unable to satisfy flags. E.g. the hypervisor driver will
5687
* return failure if LIVE is specified but it only supports removing the
5688
* persisted device allocation.
5689
*
5690
* Returns 0 in case of success, -1 in case of failure.
5691
*/
5692
int
5693
virDomainDetachDeviceFlags(virDomainPtr domain,
5694
const char *xml, unsigned int flags)
5695
{
5696
virConnectPtr conn;
5697
5698
VIR_DOMAIN_DEBUG(domain, "xml=%s, flags=%d", xml, flags);
5699
5700
virResetLastError();
5701
5702
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5703
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5704
virDispatchError(NULL);
5705
return -1;
5706
}
5707
if (domain->conn->flags & VIR_CONNECT_RO) {
5708
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
5709
goto error;
5710
}
5711
conn = domain->conn;
5712
5713
if (conn->driver->domainDetachDeviceFlags) {
5714
int ret;
5715
ret = conn->driver->domainDetachDeviceFlags(domain, xml, flags);
5716
if (ret < 0)
5717
goto error;
5718
return ret;
5719
}
5720
5721
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5722
5723
error:
5724
virDispatchError(domain->conn);
5725
return -1;
5726
}
5727
5728
/**
5729
* virDomainUpdateDeviceFlags:
5730
* @domain: pointer to domain object
5731
* @xml: pointer to XML description of one device
5732
* @flags: an OR'ed set of virDomainDeviceModifyFlags
5733
*
5734
* Change a virtual device on a domain, using the flags parameter
5735
* to control how the device is changed. VIR_DOMAIN_DEVICE_MODIFY_CURRENT
5736
* specifies that the device change is made based on current domain
5737
* state. VIR_DOMAIN_DEVICE_MODIFY_LIVE specifies that the device shall be
5738
* changed on the active domain instance only and is not added to the
5739
* persisted domain configuration. VIR_DOMAIN_DEVICE_MODIFY_CONFIG
5740
* specifies that the device shall be changed on the persisted domain
5741
* configuration only. Note that the target hypervisor must return an
5742
* error if unable to satisfy flags. E.g. the hypervisor driver will
5743
* return failure if LIVE is specified but it only supports modifying the
5744
* persisted device allocation.
5745
*
5746
* This method is used for actions such changing CDROM/Floppy device
5747
* media, altering the graphics configuration such as password,
5748
* reconfiguring the NIC device backend connectivity, etc.
5749
*
5750
* Returns 0 in case of success, -1 in case of failure.
5751
*/
5752
int
5753
virDomainUpdateDeviceFlags(virDomainPtr domain,
5754
const char *xml, unsigned int flags)
5755
{
5756
virConnectPtr conn;
5757
5758
VIR_DOMAIN_DEBUG(domain, "xml=%s, flags=%d", xml, flags);
5759
5760
virResetLastError();
5761
5762
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
5763
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
5764
virDispatchError(NULL);
5765
return -1;
5766
}
5767
if (domain->conn->flags & VIR_CONNECT_RO) {
5768
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
5769
goto error;
5770
}
5771
conn = domain->conn;
5772
5773
if (conn->driver->domainUpdateDeviceFlags) {
5774
int ret;
5775
ret = conn->driver->domainUpdateDeviceFlags(domain, xml, flags);
5776
if (ret < 0)
5777
goto error;
5778
return ret;
5779
}
5780
5781
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5782
5783
error:
5784
virDispatchError(domain->conn);
5785
return -1;
5786
}
5787
5788
/**
5789
* virNodeGetCellsFreeMemory:
5790
* @conn: pointer to the hypervisor connection
5791
* @freeMems: pointer to the array of unsigned long long
5792
* @startCell: index of first cell to return freeMems info on.
5793
* @maxCells: Maximum number of cells for which freeMems information can
5794
* be returned.
5795
*
5796
* This call returns the amount of free memory in one or more NUMA cells.
5797
* The @freeMems array must be allocated by the caller and will be filled
5798
* with the amount of free memory in bytes for each cell requested,
5799
* starting with startCell (in freeMems[0]), up to either
5800
* (startCell + maxCells), or the number of additional cells in the node,
5801
* whichever is smaller.
5802
*
5803
* Returns the number of entries filled in freeMems, or -1 in case of error.
5804
*/
5805
5806
int
5807
virNodeGetCellsFreeMemory(virConnectPtr conn, unsigned long long *freeMems,
5808
int startCell, int maxCells)
5809
{
5810
DEBUG("conn=%p, freeMems=%p, startCell=%d, maxCells=%d",
5811
conn, freeMems, startCell, maxCells);
5812
5813
virResetLastError();
5814
5815
if (!VIR_IS_CONNECT(conn)) {
5816
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
5817
virDispatchError(NULL);
5818
return -1;
5819
}
5820
5821
if ((freeMems == NULL) || (maxCells <= 0) || (startCell < 0)) {
5822
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
5823
goto error;
5824
}
5825
5826
if (conn->driver->nodeGetCellsFreeMemory) {
5827
int ret;
5828
ret = conn->driver->nodeGetCellsFreeMemory (conn, freeMems, startCell, maxCells);
5829
if (ret < 0)
5830
goto error;
5831
return ret;
5832
}
5833
5834
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5835
5836
error:
5837
virDispatchError(conn);
5838
return -1;
5839
}
5840
5841
/**
5842
* virNetworkGetConnect:
5843
* @net: pointer to a network
5844
*
5845
* Provides the connection pointer associated with a network. The
5846
* reference counter on the connection is not increased by this
5847
* call.
5848
*
5849
* WARNING: When writing libvirt bindings in other languages, do
5850
* not use this function. Instead, store the connection and
5851
* the network object together.
5852
*
5853
* Returns the virConnectPtr or NULL in case of failure.
5854
*/
5855
virConnectPtr
5856
virNetworkGetConnect (virNetworkPtr net)
5857
{
5858
DEBUG("net=%p", net);
5859
5860
virResetLastError();
5861
5862
if (!VIR_IS_CONNECTED_NETWORK (net)) {
5863
virLibNetworkError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
5864
virDispatchError(NULL);
5865
return NULL;
5866
}
5867
return net->conn;
5868
}
5869
5870
/**
5871
* virConnectNumOfNetworks:
5872
* @conn: pointer to the hypervisor connection
5873
*
5874
* Provides the number of active networks.
5875
*
5876
* Returns the number of network found or -1 in case of error
5877
*/
5878
int
5879
virConnectNumOfNetworks(virConnectPtr conn)
5880
{
5881
DEBUG("conn=%p", conn);
5882
5883
virResetLastError();
5884
5885
if (!VIR_IS_CONNECT(conn)) {
5886
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
5887
virDispatchError(NULL);
5888
return -1;
5889
}
5890
5891
if (conn->networkDriver && conn->networkDriver->numOfNetworks) {
5892
int ret;
5893
ret = conn->networkDriver->numOfNetworks (conn);
5894
if (ret < 0)
5895
goto error;
5896
return ret;
5897
}
5898
5899
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5900
5901
error:
5902
virDispatchError(conn);
5903
return -1;
5904
}
5905
5906
/**
5907
* virConnectListNetworks:
5908
* @conn: pointer to the hypervisor connection
5909
* @names: array to collect the list of names of active networks
5910
* @maxnames: size of @names
5911
*
5912
* Collect the list of active networks, and store their names in @names
5913
*
5914
* Returns the number of networks found or -1 in case of error
5915
*/
5916
int
5917
virConnectListNetworks(virConnectPtr conn, char **const names, int maxnames)
5918
{
5919
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
5920
5921
virResetLastError();
5922
5923
if (!VIR_IS_CONNECT(conn)) {
5924
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
5925
virDispatchError(NULL);
5926
return -1;
5927
}
5928
5929
if ((names == NULL) || (maxnames < 0)) {
5930
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
5931
goto error;
5932
}
5933
5934
if (conn->networkDriver && conn->networkDriver->listNetworks) {
5935
int ret;
5936
ret = conn->networkDriver->listNetworks (conn, names, maxnames);
5937
if (ret < 0)
5938
goto error;
5939
return ret;
5940
}
5941
5942
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5943
5944
error:
5945
virDispatchError(conn);
5946
return -1;
5947
}
5948
5949
/**
5950
* virConnectNumOfDefinedNetworks:
5951
* @conn: pointer to the hypervisor connection
5952
*
5953
* Provides the number of inactive networks.
5954
*
5955
* Returns the number of networks found or -1 in case of error
5956
*/
5957
int
5958
virConnectNumOfDefinedNetworks(virConnectPtr conn)
5959
{
5960
DEBUG("conn=%p", conn);
5961
5962
virResetLastError();
5963
5964
if (!VIR_IS_CONNECT(conn)) {
5965
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
5966
virDispatchError(NULL);
5967
return -1;
5968
}
5969
5970
if (conn->networkDriver && conn->networkDriver->numOfDefinedNetworks) {
5971
int ret;
5972
ret = conn->networkDriver->numOfDefinedNetworks (conn);
5973
if (ret < 0)
5974
goto error;
5975
return ret;
5976
}
5977
5978
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
5979
5980
error:
5981
virDispatchError(conn);
5982
return -1;
5983
}
5984
5985
/**
5986
* virConnectListDefinedNetworks:
5987
* @conn: pointer to the hypervisor connection
5988
* @names: pointer to an array to store the names
5989
* @maxnames: size of the array
5990
*
5991
* list the inactive networks, stores the pointers to the names in @names
5992
*
5993
* Returns the number of names provided in the array or -1 in case of error
5994
*/
5995
int
5996
virConnectListDefinedNetworks(virConnectPtr conn, char **const names,
5997
int maxnames)
5998
{
5999
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
6000
6001
virResetLastError();
6002
6003
if (!VIR_IS_CONNECT(conn)) {
6004
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
6005
virDispatchError(NULL);
6006
return -1;
6007
}
6008
6009
if ((names == NULL) || (maxnames < 0)) {
6010
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6011
goto error;
6012
}
6013
6014
if (conn->networkDriver && conn->networkDriver->listDefinedNetworks) {
6015
int ret;
6016
ret = conn->networkDriver->listDefinedNetworks (conn,
6017
names, maxnames);
6018
if (ret < 0)
6019
goto error;
6020
return ret;
6021
}
6022
6023
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6024
6025
error:
6026
virDispatchError(conn);
6027
return -1;
6028
}
6029
6030
/**
6031
* virNetworkLookupByName:
6032
* @conn: pointer to the hypervisor connection
6033
* @name: name for the network
6034
*
6035
* Try to lookup a network on the given hypervisor based on its name.
6036
*
6037
* Returns a new network object or NULL in case of failure. If the
6038
* network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
6039
*/
6040
virNetworkPtr
6041
virNetworkLookupByName(virConnectPtr conn, const char *name)
6042
{
6043
DEBUG("conn=%p, name=%s", conn, name);
6044
6045
virResetLastError();
6046
6047
if (!VIR_IS_CONNECT(conn)) {
6048
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
6049
virDispatchError(NULL);
6050
return NULL;
6051
}
6052
if (name == NULL) {
6053
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6054
goto error;
6055
}
6056
6057
if (conn->networkDriver && conn->networkDriver->networkLookupByName) {
6058
virNetworkPtr ret;
6059
ret = conn->networkDriver->networkLookupByName (conn, name);
6060
if (!ret)
6061
goto error;
6062
return ret;
6063
}
6064
6065
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6066
6067
error:
6068
virDispatchError(conn);
6069
return NULL;
6070
}
6071
6072
/**
6073
* virNetworkLookupByUUID:
6074
* @conn: pointer to the hypervisor connection
6075
* @uuid: the raw UUID for the network
6076
*
6077
* Try to lookup a network on the given hypervisor based on its UUID.
6078
*
6079
* Returns a new network object or NULL in case of failure. If the
6080
* network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
6081
*/
6082
virNetworkPtr
6083
virNetworkLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
6084
{
6085
char uuidstr[VIR_UUID_STRING_BUFLEN];
6086
virUUIDFormat(uuid, uuidstr);
6087
6088
DEBUG("conn=%p, uuid=%s", conn, uuidstr);
6089
6090
virResetLastError();
6091
6092
if (!VIR_IS_CONNECT(conn)) {
6093
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
6094
virDispatchError(NULL);
6095
return NULL;
6096
}
6097
if (uuid == NULL) {
6098
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6099
goto error;
6100
}
6101
6102
if (conn->networkDriver && conn->networkDriver->networkLookupByUUID){
6103
virNetworkPtr ret;
6104
ret = conn->networkDriver->networkLookupByUUID (conn, uuid);
6105
if (!ret)
6106
goto error;
6107
return ret;
6108
}
6109
6110
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6111
6112
error:
6113
virDispatchError(conn);
6114
return NULL;
6115
}
6116
6117
/**
6118
* virNetworkLookupByUUIDString:
6119
* @conn: pointer to the hypervisor connection
6120
* @uuidstr: the string UUID for the network
6121
*
6122
* Try to lookup a network on the given hypervisor based on its UUID.
6123
*
6124
* Returns a new network object or NULL in case of failure. If the
6125
* network cannot be found, then VIR_ERR_NO_NETWORK error is raised.
6126
*/
6127
virNetworkPtr
6128
virNetworkLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
6129
{
6130
unsigned char uuid[VIR_UUID_BUFLEN];
6131
DEBUG("conn=%p, uuidstr=%s", conn, uuidstr);
6132
6133
virResetLastError();
6134
6135
if (!VIR_IS_CONNECT(conn)) {
6136
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
6137
virDispatchError(NULL);
6138
return NULL;
6139
}
6140
if (uuidstr == NULL) {
6141
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6142
goto error;
6143
}
6144
6145
if (virUUIDParse(uuidstr, uuid) < 0) {
6146
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6147
goto error;
6148
}
6149
6150
return virNetworkLookupByUUID(conn, &uuid[0]);
6151
6152
error:
6153
virDispatchError(conn);
6154
return NULL;
6155
}
6156
6157
/**
6158
* virNetworkCreateXML:
6159
* @conn: pointer to the hypervisor connection
6160
* @xmlDesc: an XML description of the network
6161
*
6162
* Create and start a new virtual network, based on an XML description
6163
* similar to the one returned by virNetworkGetXMLDesc()
6164
*
6165
* Returns a new network object or NULL in case of failure
6166
*/
6167
virNetworkPtr
6168
virNetworkCreateXML(virConnectPtr conn, const char *xmlDesc)
6169
{
6170
DEBUG("conn=%p, xmlDesc=%s", conn, xmlDesc);
6171
6172
virResetLastError();
6173
6174
if (!VIR_IS_CONNECT(conn)) {
6175
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
6176
virDispatchError(NULL);
6177
return NULL;
6178
}
6179
if (xmlDesc == NULL) {
6180
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6181
goto error;
6182
}
6183
if (conn->flags & VIR_CONNECT_RO) {
6184
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
6185
goto error;
6186
}
6187
6188
if (conn->networkDriver && conn->networkDriver->networkCreateXML) {
6189
virNetworkPtr ret;
6190
ret = conn->networkDriver->networkCreateXML (conn, xmlDesc);
6191
if (!ret)
6192
goto error;
6193
return ret;
6194
}
6195
6196
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6197
6198
error:
6199
virDispatchError(conn);
6200
return NULL;
6201
}
6202
6203
/**
6204
* virNetworkDefineXML:
6205
* @conn: pointer to the hypervisor connection
6206
* @xml: the XML description for the network, preferably in UTF-8
6207
*
6208
* Define a network, but does not create it
6209
*
6210
* Returns NULL in case of error, a pointer to the network otherwise
6211
*/
6212
virNetworkPtr
6213
virNetworkDefineXML(virConnectPtr conn, const char *xml)
6214
{
6215
DEBUG("conn=%p, xml=%s", conn, xml);
6216
6217
virResetLastError();
6218
6219
if (!VIR_IS_CONNECT(conn)) {
6220
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
6221
virDispatchError(NULL);
6222
return NULL;
6223
}
6224
if (conn->flags & VIR_CONNECT_RO) {
6225
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
6226
goto error;
6227
}
6228
if (xml == NULL) {
6229
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6230
goto error;
6231
}
6232
6233
if (conn->networkDriver && conn->networkDriver->networkDefineXML) {
6234
virNetworkPtr ret;
6235
ret = conn->networkDriver->networkDefineXML (conn, xml);
6236
if (!ret)
6237
goto error;
6238
return ret;
6239
}
6240
6241
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6242
6243
error:
6244
virDispatchError(conn);
6245
return NULL;
6246
}
6247
6248
/**
6249
* virNetworkUndefine:
6250
* @network: pointer to a defined network
6251
*
6252
* Undefine a network but does not stop it if it is running
6253
*
6254
* Returns 0 in case of success, -1 in case of error
6255
*/
6256
int
6257
virNetworkUndefine(virNetworkPtr network) {
6258
virConnectPtr conn;
6259
DEBUG("network=%p", network);
6260
6261
virResetLastError();
6262
6263
if (!VIR_IS_CONNECTED_NETWORK(network)) {
6264
virLibNetworkError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
6265
virDispatchError(NULL);
6266
return -1;
6267
}
6268
conn = network->conn;
6269
if (conn->flags & VIR_CONNECT_RO) {
6270
virLibNetworkError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
6271
goto error;
6272
}
6273
6274
if (conn->networkDriver && conn->networkDriver->networkUndefine) {
6275
int ret;
6276
ret = conn->networkDriver->networkUndefine (network);
6277
if (ret < 0)
6278
goto error;
6279
return ret;
6280
}
6281
6282
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6283
6284
error:
6285
virDispatchError(network->conn);
6286
return -1;
6287
}
6288
6289
/**
6290
* virNetworkCreate:
6291
* @network: pointer to a defined network
6292
*
6293
* Create and start a defined network. If the call succeed the network
6294
* moves from the defined to the running networks pools.
6295
*
6296
* Returns 0 in case of success, -1 in case of error
6297
*/
6298
int
6299
virNetworkCreate(virNetworkPtr network)
6300
{
6301
virConnectPtr conn;
6302
DEBUG("network=%p", network);
6303
6304
virResetLastError();
6305
6306
if (!VIR_IS_CONNECTED_NETWORK(network)) {
6307
virLibNetworkError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
6308
virDispatchError(NULL);
6309
return -1;
6310
}
6311
conn = network->conn;
6312
if (conn->flags & VIR_CONNECT_RO) {
6313
virLibNetworkError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
6314
goto error;
6315
}
6316
6317
if (conn->networkDriver && conn->networkDriver->networkCreate) {
6318
int ret;
6319
ret = conn->networkDriver->networkCreate (network);
6320
if (ret < 0)
6321
goto error;
6322
return ret;
6323
}
6324
6325
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6326
6327
error:
6328
virDispatchError(network->conn);
6329
return -1;
6330
}
6331
6332
/**
6333
* virNetworkDestroy:
6334
* @network: a network object
6335
*
6336
* Destroy the network object. The running instance is shutdown if not down
6337
* already and all resources used by it are given back to the hypervisor. This
6338
* does not free the associated virNetworkPtr object.
6339
* This function may require privileged access
6340
*
6341
* Returns 0 in case of success and -1 in case of failure.
6342
*/
6343
int
6344
virNetworkDestroy(virNetworkPtr network)
6345
{
6346
virConnectPtr conn;
6347
DEBUG("network=%p", network);
6348
6349
virResetLastError();
6350
6351
if (!VIR_IS_CONNECTED_NETWORK(network)) {
6352
virLibNetworkError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
6353
virDispatchError(NULL);
6354
return -1;
6355
}
6356
6357
conn = network->conn;
6358
if (conn->flags & VIR_CONNECT_RO) {
6359
virLibNetworkError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
6360
goto error;
6361
}
6362
6363
if (conn->networkDriver && conn->networkDriver->networkDestroy) {
6364
int ret;
6365
ret = conn->networkDriver->networkDestroy (network);
6366
if (ret < 0)
6367
goto error;
6368
return ret;
6369
}
6370
6371
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6372
6373
error:
6374
virDispatchError(network->conn);
6375
return -1;
6376
}
6377
6378
/**
6379
* virNetworkFree:
6380
* @network: a network object
6381
*
6382
* Free the network object. The running instance is kept alive.
6383
* The data structure is freed and should not be used thereafter.
6384
*
6385
* Returns 0 in case of success and -1 in case of failure.
6386
*/
6387
int
6388
virNetworkFree(virNetworkPtr network)
6389
{
6390
DEBUG("network=%p", network);
6391
6392
virResetLastError();
6393
6394
if (!VIR_IS_CONNECTED_NETWORK(network)) {
6395
virLibNetworkError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
6396
virDispatchError(NULL);
6397
return -1;
6398
}
6399
if (virUnrefNetwork(network) < 0) {
6400
virDispatchError(NULL);
6401
return -1;
6402
}
6403
return 0;
6404
}
6405
6406
/**
6407
* virNetworkRef:
6408
* @network: the network to hold a reference on
6409
*
6410
* Increment the reference count on the network. For each
6411
* additional call to this method, there shall be a corresponding
6412
* call to virNetworkFree to release the reference count, once
6413
* the caller no longer needs the reference to this object.
6414
*
6415
* This method is typically useful for applications where multiple
6416
* threads are using a connection, and it is required that the
6417
* connection remain open until all threads have finished using
6418
* it. ie, each new thread using a network would increment
6419
* the reference count.
6420
*
6421
* Returns 0 in case of success, -1 in case of failure.
6422
*/
6423
int
6424
virNetworkRef(virNetworkPtr network)
6425
{
6426
if ((!VIR_IS_CONNECTED_NETWORK(network))) {
6427
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6428
virDispatchError(NULL);
6429
return -1;
6430
}
6431
virMutexLock(&network->conn->lock);
6432
DEBUG("network=%p refs=%d", network, network->refs);
6433
network->refs++;
6434
virMutexUnlock(&network->conn->lock);
6435
return 0;
6436
}
6437
6438
/**
6439
* virNetworkGetName:
6440
* @network: a network object
6441
*
6442
* Get the public name for that network
6443
*
6444
* Returns a pointer to the name or NULL, the string need not be deallocated
6445
* its lifetime will be the same as the network object.
6446
*/
6447
const char *
6448
virNetworkGetName(virNetworkPtr network)
6449
{
6450
DEBUG("network=%p", network);
6451
6452
virResetLastError();
6453
6454
if (!VIR_IS_NETWORK(network)) {
6455
virLibNetworkError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
6456
virDispatchError(NULL);
6457
return NULL;
6458
}
6459
return network->name;
6460
}
6461
6462
/**
6463
* virNetworkGetUUID:
6464
* @network: a network object
6465
* @uuid: pointer to a VIR_UUID_BUFLEN bytes array
6466
*
6467
* Get the UUID for a network
6468
*
6469
* Returns -1 in case of error, 0 in case of success
6470
*/
6471
int
6472
virNetworkGetUUID(virNetworkPtr network, unsigned char *uuid)
6473
{
6474
DEBUG("network=%p, uuid=%p", network, uuid);
6475
6476
virResetLastError();
6477
6478
if (!VIR_IS_NETWORK(network)) {
6479
virLibNetworkError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
6480
virDispatchError(NULL);
6481
return -1;
6482
}
6483
if (uuid == NULL) {
6484
virLibNetworkError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6485
goto error;
6486
}
6487
6488
memcpy(uuid, &network->uuid[0], VIR_UUID_BUFLEN);
6489
6490
return 0;
6491
6492
error:
6493
virDispatchError(network->conn);
6494
return -1;
6495
}
6496
6497
/**
6498
* virNetworkGetUUIDString:
6499
* @network: a network object
6500
* @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
6501
*
6502
* Get the UUID for a network as string. For more information about
6503
* UUID see RFC4122.
6504
*
6505
* Returns -1 in case of error, 0 in case of success
6506
*/
6507
int
6508
virNetworkGetUUIDString(virNetworkPtr network, char *buf)
6509
{
6510
unsigned char uuid[VIR_UUID_BUFLEN];
6511
DEBUG("network=%p, buf=%p", network, buf);
6512
6513
virResetLastError();
6514
6515
if (!VIR_IS_NETWORK(network)) {
6516
virLibNetworkError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
6517
virDispatchError(NULL);
6518
return -1;
6519
}
6520
if (buf == NULL) {
6521
virLibNetworkError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6522
goto error;
6523
}
6524
6525
if (virNetworkGetUUID(network, &uuid[0]))
6526
goto error;
6527
6528
virUUIDFormat(uuid, buf);
6529
return 0;
6530
6531
error:
6532
virDispatchError(network->conn);
6533
return -1;
6534
}
6535
6536
/**
6537
* virNetworkGetXMLDesc:
6538
* @network: a network object
6539
* @flags: an OR'ed set of extraction flags, not used yet
6540
*
6541
* Provide an XML description of the network. The description may be reused
6542
* later to relaunch the network with virNetworkCreateXML().
6543
*
6544
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
6545
* the caller must free() the returned value.
6546
*/
6547
char *
6548
virNetworkGetXMLDesc(virNetworkPtr network, int flags)
6549
{
6550
virConnectPtr conn;
6551
DEBUG("network=%p, flags=%d", network, flags);
6552
6553
virResetLastError();
6554
6555
if (!VIR_IS_CONNECTED_NETWORK(network)) {
6556
virLibNetworkError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
6557
virDispatchError(NULL);
6558
return NULL;
6559
}
6560
if (flags != 0) {
6561
virLibNetworkError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6562
goto error;
6563
}
6564
6565
conn = network->conn;
6566
6567
if (conn->networkDriver && conn->networkDriver->networkDumpXML) {
6568
char *ret;
6569
ret = conn->networkDriver->networkDumpXML (network, flags);
6570
if (!ret)
6571
goto error;
6572
return ret;
6573
}
6574
6575
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6576
6577
error:
6578
virDispatchError(network->conn);
6579
return NULL;
6580
}
6581
6582
/**
6583
* virNetworkGetBridgeName:
6584
* @network: a network object
6585
*
6586
* Provides a bridge interface name to which a domain may connect
6587
* a network interface in order to join the network.
6588
*
6589
* Returns a 0 terminated interface name, or NULL in case of error.
6590
* the caller must free() the returned value.
6591
*/
6592
char *
6593
virNetworkGetBridgeName(virNetworkPtr network)
6594
{
6595
virConnectPtr conn;
6596
DEBUG("network=%p", network);
6597
6598
virResetLastError();
6599
6600
if (!VIR_IS_CONNECTED_NETWORK(network)) {
6601
virLibNetworkError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
6602
virDispatchError(NULL);
6603
return NULL;
6604
}
6605
6606
conn = network->conn;
6607
6608
if (conn->networkDriver && conn->networkDriver->networkGetBridgeName) {
6609
char *ret;
6610
ret = conn->networkDriver->networkGetBridgeName (network);
6611
if (!ret)
6612
goto error;
6613
return ret;
6614
}
6615
6616
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6617
6618
error:
6619
virDispatchError(network->conn);
6620
return NULL;
6621
}
6622
6623
/**
6624
* virNetworkGetAutostart:
6625
* @network: a network object
6626
* @autostart: the value returned
6627
*
6628
* Provides a boolean value indicating whether the network
6629
* configured to be automatically started when the host
6630
* machine boots.
6631
*
6632
* Returns -1 in case of error, 0 in case of success
6633
*/
6634
int
6635
virNetworkGetAutostart(virNetworkPtr network,
6636
int *autostart)
6637
{
6638
virConnectPtr conn;
6639
DEBUG("network=%p, autostart=%p", network, autostart);
6640
6641
virResetLastError();
6642
6643
if (!VIR_IS_CONNECTED_NETWORK(network)) {
6644
virLibNetworkError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
6645
virDispatchError(NULL);
6646
return -1;
6647
}
6648
if (!autostart) {
6649
virLibNetworkError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6650
goto error;
6651
}
6652
6653
conn = network->conn;
6654
6655
if (conn->networkDriver && conn->networkDriver->networkGetAutostart) {
6656
int ret;
6657
ret = conn->networkDriver->networkGetAutostart (network, autostart);
6658
if (ret < 0)
6659
goto error;
6660
return ret;
6661
}
6662
6663
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6664
6665
error:
6666
virDispatchError(network->conn);
6667
return -1;
6668
}
6669
6670
/**
6671
* virNetworkSetAutostart:
6672
* @network: a network object
6673
* @autostart: whether the network should be automatically started 0 or 1
6674
*
6675
* Configure the network to be automatically started
6676
* when the host machine boots.
6677
*
6678
* Returns -1 in case of error, 0 in case of success
6679
*/
6680
int
6681
virNetworkSetAutostart(virNetworkPtr network,
6682
int autostart)
6683
{
6684
virConnectPtr conn;
6685
DEBUG("network=%p, autostart=%d", network, autostart);
6686
6687
virResetLastError();
6688
6689
if (!VIR_IS_CONNECTED_NETWORK(network)) {
6690
virLibNetworkError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
6691
virDispatchError(NULL);
6692
return -1;
6693
}
6694
6695
if (network->conn->flags & VIR_CONNECT_RO) {
6696
virLibNetworkError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
6697
goto error;
6698
}
6699
6700
conn = network->conn;
6701
6702
if (conn->networkDriver && conn->networkDriver->networkSetAutostart) {
6703
int ret;
6704
ret = conn->networkDriver->networkSetAutostart (network, autostart);
6705
if (ret < 0)
6706
goto error;
6707
return ret;
6708
}
6709
6710
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6711
6712
error:
6713
virDispatchError(network->conn);
6714
return -1;
6715
}
6716
6717
/**
6718
* virInterfaceGetConnect:
6719
* @iface: pointer to an interface
6720
*
6721
* Provides the connection pointer associated with an interface. The
6722
* reference counter on the connection is not increased by this
6723
* call.
6724
*
6725
* WARNING: When writing libvirt bindings in other languages, do
6726
* not use this function. Instead, store the connection and
6727
* the interface object together.
6728
*
6729
* Returns the virConnectPtr or NULL in case of failure.
6730
*/
6731
virConnectPtr
6732
virInterfaceGetConnect (virInterfacePtr iface)
6733
{
6734
DEBUG("iface=%p", iface);
6735
6736
virResetLastError();
6737
6738
if (!VIR_IS_CONNECTED_INTERFACE (iface)) {
6739
virLibInterfaceError(VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
6740
virDispatchError(NULL);
6741
return NULL;
6742
}
6743
return iface->conn;
6744
}
6745
6746
/**
6747
* virConnectNumOfInterfaces:
6748
* @conn: pointer to the hypervisor connection
6749
*
6750
* Provides the number of active interfaces on the physical host.
6751
*
6752
* Returns the number of active interfaces found or -1 in case of error
6753
*/
6754
int
6755
virConnectNumOfInterfaces(virConnectPtr conn)
6756
{
6757
DEBUG("conn=%p", conn);
6758
6759
virResetLastError();
6760
6761
if (!VIR_IS_CONNECT(conn)) {
6762
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
6763
virDispatchError(NULL);
6764
return -1;
6765
}
6766
6767
if (conn->interfaceDriver && conn->interfaceDriver->numOfInterfaces) {
6768
int ret;
6769
ret = conn->interfaceDriver->numOfInterfaces (conn);
6770
if (ret < 0)
6771
goto error;
6772
return ret;
6773
}
6774
6775
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6776
6777
error:
6778
virDispatchError(conn);
6779
return -1;
6780
}
6781
6782
/**
6783
* virConnectListInterfaces:
6784
* @conn: pointer to the hypervisor connection
6785
* @names: array to collect the list of names of interfaces
6786
* @maxnames: size of @names
6787
*
6788
* Collect the list of active physical host interfaces,
6789
* and store their names in @names
6790
*
6791
* Returns the number of interfaces found or -1 in case of error
6792
*/
6793
int
6794
virConnectListInterfaces(virConnectPtr conn, char **const names, int maxnames)
6795
{
6796
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
6797
6798
virResetLastError();
6799
6800
if (!VIR_IS_CONNECT(conn)) {
6801
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
6802
virDispatchError(NULL);
6803
return -1;
6804
}
6805
6806
if ((names == NULL) || (maxnames < 0)) {
6807
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6808
goto error;
6809
}
6810
6811
if (conn->interfaceDriver && conn->interfaceDriver->listInterfaces) {
6812
int ret;
6813
ret = conn->interfaceDriver->listInterfaces (conn, names, maxnames);
6814
if (ret < 0)
6815
goto error;
6816
return ret;
6817
}
6818
6819
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6820
6821
error:
6822
virDispatchError(conn);
6823
return -1;
6824
}
6825
6826
/**
6827
* virConnectNumOfDefinedInterfaces:
6828
* @conn: pointer to the hypervisor connection
6829
*
6830
* Provides the number of defined (inactive) interfaces on the physical host.
6831
*
6832
* Returns the number of defined interface found or -1 in case of error
6833
*/
6834
int
6835
virConnectNumOfDefinedInterfaces(virConnectPtr conn)
6836
{
6837
DEBUG("conn=%p", conn);
6838
6839
virResetLastError();
6840
6841
if (!VIR_IS_CONNECT(conn)) {
6842
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
6843
virDispatchError(NULL);
6844
return -1;
6845
}
6846
6847
if (conn->interfaceDriver && conn->interfaceDriver->numOfDefinedInterfaces) {
6848
int ret;
6849
ret = conn->interfaceDriver->numOfDefinedInterfaces (conn);
6850
if (ret < 0)
6851
goto error;
6852
return ret;
6853
}
6854
6855
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6856
6857
error:
6858
virDispatchError(conn);
6859
return -1;
6860
}
6861
6862
/**
6863
* virConnectListDefinedInterfaces:
6864
* @conn: pointer to the hypervisor connection
6865
* @names: array to collect the list of names of interfaces
6866
* @maxnames: size of @names
6867
*
6868
* Collect the list of defined (inactive) physical host interfaces,
6869
* and store their names in @names.
6870
*
6871
* Returns the number of interfaces found or -1 in case of error
6872
*/
6873
int
6874
virConnectListDefinedInterfaces(virConnectPtr conn,
6875
char **const names,
6876
int maxnames)
6877
{
6878
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
6879
6880
virResetLastError();
6881
6882
if (!VIR_IS_CONNECT(conn)) {
6883
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
6884
virDispatchError(NULL);
6885
return -1;
6886
}
6887
6888
if ((names == NULL) || (maxnames < 0)) {
6889
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6890
goto error;
6891
}
6892
6893
if (conn->interfaceDriver && conn->interfaceDriver->listDefinedInterfaces) {
6894
int ret;
6895
ret = conn->interfaceDriver->listDefinedInterfaces (conn, names, maxnames);
6896
if (ret < 0)
6897
goto error;
6898
return ret;
6899
}
6900
6901
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6902
6903
error:
6904
virDispatchError(conn);
6905
return -1;
6906
}
6907
6908
/**
6909
* virInterfaceLookupByName:
6910
* @conn: pointer to the hypervisor connection
6911
* @name: name for the interface
6912
*
6913
* Try to lookup an interface on the given hypervisor based on its name.
6914
*
6915
* Returns a new interface object or NULL in case of failure. If the
6916
* interface cannot be found, then VIR_ERR_NO_INTERFACE error is raised.
6917
*/
6918
virInterfacePtr
6919
virInterfaceLookupByName(virConnectPtr conn, const char *name)
6920
{
6921
DEBUG("conn=%p, name=%s", conn, name);
6922
6923
virResetLastError();
6924
6925
if (!VIR_IS_CONNECT(conn)) {
6926
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
6927
virDispatchError(NULL);
6928
return NULL;
6929
}
6930
if (name == NULL) {
6931
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6932
goto error;
6933
}
6934
6935
if (conn->interfaceDriver && conn->interfaceDriver->interfaceLookupByName) {
6936
virInterfacePtr ret;
6937
ret = conn->interfaceDriver->interfaceLookupByName (conn, name);
6938
if (!ret)
6939
goto error;
6940
return ret;
6941
}
6942
6943
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6944
6945
error:
6946
virDispatchError(conn);
6947
return NULL;
6948
}
6949
6950
/**
6951
* virInterfaceLookupByMACString:
6952
* @conn: pointer to the hypervisor connection
6953
* @macstr: the MAC for the interface (null-terminated ASCII format)
6954
*
6955
* Try to lookup an interface on the given hypervisor based on its MAC.
6956
*
6957
* Returns a new interface object or NULL in case of failure. If the
6958
* interface cannot be found, then VIR_ERR_NO_INTERFACE error is raised.
6959
*/
6960
virInterfacePtr
6961
virInterfaceLookupByMACString(virConnectPtr conn, const char *macstr)
6962
{
6963
DEBUG("conn=%p, macstr=%s", conn, macstr);
6964
6965
virResetLastError();
6966
6967
if (!VIR_IS_CONNECT(conn)) {
6968
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
6969
virDispatchError(NULL);
6970
return NULL;
6971
}
6972
if (macstr == NULL) {
6973
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
6974
goto error;
6975
}
6976
6977
if (conn->interfaceDriver && conn->interfaceDriver->interfaceLookupByMACString) {
6978
virInterfacePtr ret;
6979
ret = conn->interfaceDriver->interfaceLookupByMACString (conn, macstr);
6980
if (!ret)
6981
goto error;
6982
return ret;
6983
}
6984
6985
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
6986
6987
error:
6988
virDispatchError(conn);
6989
return NULL;
6990
}
6991
6992
/**
6993
* virInterfaceGetName:
6994
* @iface: an interface object
6995
*
6996
* Get the public name for that interface
6997
*
6998
* Returns a pointer to the name or NULL, the string need not be deallocated
6999
* its lifetime will be the same as the interface object.
7000
*/
7001
const char *
7002
virInterfaceGetName(virInterfacePtr iface)
7003
{
7004
DEBUG("iface=%p", iface);
7005
7006
virResetLastError();
7007
7008
if (!VIR_IS_INTERFACE(iface)) {
7009
virLibInterfaceError(VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
7010
virDispatchError(NULL);
7011
return NULL;
7012
}
7013
return iface->name;
7014
}
7015
7016
/**
7017
* virInterfaceGetMACString:
7018
* @iface: an interface object
7019
*
7020
* Get the MAC for an interface as string. For more information about
7021
* MAC see RFC4122.
7022
*
7023
* Returns a pointer to the MAC address (in null-terminated ASCII
7024
* format) or NULL, the string need not be deallocated its lifetime
7025
* will be the same as the interface object.
7026
*/
7027
const char *
7028
virInterfaceGetMACString(virInterfacePtr iface)
7029
{
7030
DEBUG("iface=%p", iface);
7031
7032
virResetLastError();
7033
7034
if (!VIR_IS_INTERFACE(iface)) {
7035
virLibInterfaceError(VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
7036
virDispatchError(NULL);
7037
return NULL;
7038
}
7039
return iface->mac;
7040
}
7041
7042
/**
7043
* virInterfaceGetXMLDesc:
7044
* @iface: an interface object
7045
* @flags: an OR'ed set of extraction flags. Current valid bits:
7046
*
7047
* VIR_INTERFACE_XML_INACTIVE - return the static configuration,
7048
* suitable for use redefining the
7049
* interface via virInterfaceDefineXML()
7050
*
7051
* Provide an XML description of the interface. If
7052
* VIR_INTERFACE_XML_INACTIVE is set, the description may be reused
7053
* later to redefine the interface with virInterfaceDefineXML(). If it
7054
* is not set, the ip address and netmask will be the current live
7055
* setting of the interface, not the settings from the config files.
7056
*
7057
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
7058
* the caller must free() the returned value.
7059
*/
7060
char *
7061
virInterfaceGetXMLDesc(virInterfacePtr iface, unsigned int flags)
7062
{
7063
virConnectPtr conn;
7064
DEBUG("iface=%p, flags=%d", iface, flags);
7065
7066
virResetLastError();
7067
7068
if (!VIR_IS_CONNECTED_INTERFACE(iface)) {
7069
virLibInterfaceError(VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
7070
virDispatchError(NULL);
7071
return NULL;
7072
}
7073
if ((flags & ~VIR_INTERFACE_XML_INACTIVE) != 0) {
7074
virLibInterfaceError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7075
goto error;
7076
}
7077
7078
conn = iface->conn;
7079
7080
if (conn->interfaceDriver && conn->interfaceDriver->interfaceGetXMLDesc) {
7081
char *ret;
7082
ret = conn->interfaceDriver->interfaceGetXMLDesc (iface, flags);
7083
if (!ret)
7084
goto error;
7085
return ret;
7086
}
7087
7088
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7089
7090
error:
7091
virDispatchError(iface->conn);
7092
return NULL;
7093
}
7094
7095
/**
7096
* virInterfaceDefineXML:
7097
* @conn: pointer to the hypervisor connection
7098
* @xml: the XML description for the interface, preferably in UTF-8
7099
* @flags: and OR'ed set of extraction flags, not used yet
7100
*
7101
* Define an interface (or modify existing interface configuration)
7102
*
7103
* Returns NULL in case of error, a pointer to the interface otherwise
7104
*/
7105
virInterfacePtr
7106
virInterfaceDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
7107
{
7108
DEBUG("conn=%p, xml=%s, flags=%d", conn, xml, flags);
7109
7110
virResetLastError();
7111
7112
if (!VIR_IS_CONNECT(conn)) {
7113
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
7114
virDispatchError(NULL);
7115
return NULL;
7116
}
7117
if (conn->flags & VIR_CONNECT_RO) {
7118
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
7119
goto error;
7120
}
7121
if (xml == NULL) {
7122
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7123
goto error;
7124
}
7125
7126
if (conn->interfaceDriver && conn->interfaceDriver->interfaceDefineXML) {
7127
virInterfacePtr ret;
7128
ret = conn->interfaceDriver->interfaceDefineXML (conn, xml, flags);
7129
if (!ret)
7130
goto error;
7131
return ret;
7132
}
7133
7134
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7135
7136
error:
7137
virDispatchError(conn);
7138
return NULL;
7139
}
7140
7141
/**
7142
* virInterfaceUndefine:
7143
* @iface: pointer to a defined interface
7144
*
7145
* Undefine an interface, ie remove it from the config.
7146
* This does not free the associated virInterfacePtr object.
7147
*
7148
* Returns 0 in case of success, -1 in case of error
7149
*/
7150
int
7151
virInterfaceUndefine(virInterfacePtr iface) {
7152
virConnectPtr conn;
7153
DEBUG("iface=%p", iface);
7154
7155
virResetLastError();
7156
7157
if (!VIR_IS_CONNECTED_INTERFACE(iface)) {
7158
virLibInterfaceError(VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
7159
virDispatchError(NULL);
7160
return -1;
7161
}
7162
conn = iface->conn;
7163
if (conn->flags & VIR_CONNECT_RO) {
7164
virLibInterfaceError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
7165
goto error;
7166
}
7167
7168
if (conn->interfaceDriver && conn->interfaceDriver->interfaceUndefine) {
7169
int ret;
7170
ret = conn->interfaceDriver->interfaceUndefine (iface);
7171
if (ret < 0)
7172
goto error;
7173
return ret;
7174
}
7175
7176
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7177
7178
error:
7179
virDispatchError(iface->conn);
7180
return -1;
7181
}
7182
7183
/**
7184
* virInterfaceCreate:
7185
* @iface: pointer to a defined interface
7186
* @flags: and OR'ed set of extraction flags, not used yet
7187
*
7188
* Activate an interface (ie call "ifup")
7189
*
7190
* Returns 0 in case of success, -1 in case of error
7191
*/
7192
int
7193
virInterfaceCreate(virInterfacePtr iface, unsigned int flags)
7194
{
7195
virConnectPtr conn;
7196
DEBUG("iface=%p, flags=%d", iface, flags);
7197
7198
virResetLastError();
7199
7200
if (!VIR_IS_CONNECTED_INTERFACE(iface)) {
7201
virLibInterfaceError(VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
7202
virDispatchError(NULL);
7203
return -1;
7204
}
7205
conn = iface->conn;
7206
if (conn->flags & VIR_CONNECT_RO) {
7207
virLibInterfaceError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
7208
goto error;
7209
}
7210
7211
if (conn->interfaceDriver && conn->interfaceDriver->interfaceCreate) {
7212
int ret;
7213
ret = conn->interfaceDriver->interfaceCreate (iface, flags);
7214
if (ret < 0)
7215
goto error;
7216
return ret;
7217
}
7218
7219
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7220
7221
error:
7222
virDispatchError(iface->conn);
7223
return -1;
7224
}
7225
7226
/**
7227
* virInterfaceDestroy:
7228
* @iface: an interface object
7229
* @flags: and OR'ed set of extraction flags, not used yet
7230
*
7231
* deactivate an interface (ie call "ifdown")
7232
* This does not remove the interface from the config, and
7233
* does not free the associated virInterfacePtr object.
7234
*
7235
* Returns 0 in case of success and -1 in case of failure.
7236
*/
7237
int
7238
virInterfaceDestroy(virInterfacePtr iface, unsigned int flags)
7239
{
7240
virConnectPtr conn;
7241
DEBUG("iface=%p, flags=%d", iface, flags);
7242
7243
virResetLastError();
7244
7245
if (!VIR_IS_CONNECTED_INTERFACE(iface)) {
7246
virLibInterfaceError(VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
7247
virDispatchError(NULL);
7248
return -1;
7249
}
7250
7251
conn = iface->conn;
7252
if (conn->flags & VIR_CONNECT_RO) {
7253
virLibInterfaceError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
7254
goto error;
7255
}
7256
7257
if (conn->interfaceDriver && conn->interfaceDriver->interfaceDestroy) {
7258
int ret;
7259
ret = conn->interfaceDriver->interfaceDestroy (iface, flags);
7260
if (ret < 0)
7261
goto error;
7262
return ret;
7263
}
7264
7265
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7266
7267
error:
7268
virDispatchError(iface->conn);
7269
return -1;
7270
}
7271
7272
/**
7273
* virInterfaceRef:
7274
* @iface: the interface to hold a reference on
7275
*
7276
* Increment the reference count on the interface. For each
7277
* additional call to this method, there shall be a corresponding
7278
* call to virInterfaceFree to release the reference count, once
7279
* the caller no longer needs the reference to this object.
7280
*
7281
* This method is typically useful for applications where multiple
7282
* threads are using a connection, and it is required that the
7283
* connection remain open until all threads have finished using
7284
* it. ie, each new thread using an interface would increment
7285
* the reference count.
7286
*
7287
* Returns 0 in case of success, -1 in case of failure.
7288
*/
7289
int
7290
virInterfaceRef(virInterfacePtr iface)
7291
{
7292
if ((!VIR_IS_CONNECTED_INTERFACE(iface))) {
7293
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7294
virDispatchError(NULL);
7295
return -1;
7296
}
7297
virMutexLock(&iface->conn->lock);
7298
DEBUG("iface=%p refs=%d", iface, iface->refs);
7299
iface->refs++;
7300
virMutexUnlock(&iface->conn->lock);
7301
return 0;
7302
}
7303
7304
/**
7305
* virInterfaceFree:
7306
* @iface: an interface object
7307
*
7308
* Free the interface object. The interface itself is unaltered.
7309
* The data structure is freed and should not be used thereafter.
7310
*
7311
* Returns 0 in case of success and -1 in case of failure.
7312
*/
7313
int
7314
virInterfaceFree(virInterfacePtr iface)
7315
{
7316
DEBUG("iface=%p", iface);
7317
7318
virResetLastError();
7319
7320
if (!VIR_IS_CONNECTED_INTERFACE(iface)) {
7321
virLibInterfaceError(VIR_ERR_INVALID_INTERFACE, __FUNCTION__);
7322
virDispatchError(NULL);
7323
return -1;
7324
}
7325
if (virUnrefInterface(iface) < 0) {
7326
virDispatchError(NULL);
7327
return -1;
7328
}
7329
return 0;
7330
}
7331
7332
7333
/**
7334
* virStoragePoolGetConnect:
7335
* @pool: pointer to a pool
7336
*
7337
* Provides the connection pointer associated with a storage pool. The
7338
* reference counter on the connection is not increased by this
7339
* call.
7340
*
7341
* WARNING: When writing libvirt bindings in other languages, do
7342
* not use this function. Instead, store the connection and
7343
* the pool object together.
7344
*
7345
* Returns the virConnectPtr or NULL in case of failure.
7346
*/
7347
virConnectPtr
7348
virStoragePoolGetConnect (virStoragePoolPtr pool)
7349
{
7350
DEBUG("pool=%p", pool);
7351
7352
virResetLastError();
7353
7354
if (!VIR_IS_CONNECTED_STORAGE_POOL (pool)) {
7355
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
7356
virDispatchError(NULL);
7357
return NULL;
7358
}
7359
return pool->conn;
7360
}
7361
7362
/**
7363
* virConnectNumOfStoragePools:
7364
* @conn: pointer to hypervisor connection
7365
*
7366
* Provides the number of active storage pools
7367
*
7368
* Returns the number of pools found, or -1 on error
7369
*/
7370
int
7371
virConnectNumOfStoragePools (virConnectPtr conn)
7372
{
7373
DEBUG("conn=%p", conn);
7374
7375
virResetLastError();
7376
7377
if (!VIR_IS_CONNECT(conn)) {
7378
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
7379
virDispatchError(NULL);
7380
return -1;
7381
}
7382
7383
if (conn->storageDriver && conn->storageDriver->numOfPools) {
7384
int ret;
7385
ret = conn->storageDriver->numOfPools (conn);
7386
if (ret < 0)
7387
goto error;
7388
return ret;
7389
}
7390
7391
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7392
7393
error:
7394
virDispatchError(conn);
7395
return -1;
7396
}
7397
7398
/**
7399
* virConnectListStoragePools:
7400
* @conn: pointer to hypervisor connection
7401
* @names: array of char * to fill with pool names (allocated by caller)
7402
* @maxnames: size of the names array
7403
*
7404
* Provides the list of names of active storage pools
7405
* upto maxnames. If there are more than maxnames, the
7406
* remaining names will be silently ignored.
7407
*
7408
* Returns 0 on success, -1 on error
7409
*/
7410
int
7411
virConnectListStoragePools (virConnectPtr conn,
7412
char **const names,
7413
int maxnames)
7414
{
7415
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
7416
7417
virResetLastError();
7418
7419
if (!VIR_IS_CONNECT(conn)) {
7420
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
7421
virDispatchError(NULL);
7422
return -1;
7423
}
7424
7425
if ((names == NULL) || (maxnames < 0)) {
7426
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7427
goto error;
7428
}
7429
7430
if (conn->storageDriver && conn->storageDriver->listPools) {
7431
int ret;
7432
ret = conn->storageDriver->listPools (conn, names, maxnames);
7433
if (ret < 0)
7434
goto error;
7435
return ret;
7436
}
7437
7438
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7439
7440
error:
7441
virDispatchError(conn);
7442
return -1;
7443
}
7444
7445
7446
/**
7447
* virConnectNumOfDefinedStoragePools:
7448
* @conn: pointer to hypervisor connection
7449
*
7450
* Provides the number of inactive storage pools
7451
*
7452
* Returns the number of pools found, or -1 on error
7453
*/
7454
int
7455
virConnectNumOfDefinedStoragePools(virConnectPtr conn)
7456
{
7457
DEBUG("conn=%p", conn);
7458
7459
virResetLastError();
7460
7461
if (!VIR_IS_CONNECT(conn)) {
7462
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
7463
virDispatchError(NULL);
7464
return -1;
7465
}
7466
7467
if (conn->storageDriver && conn->storageDriver->numOfDefinedPools) {
7468
int ret;
7469
ret = conn->storageDriver->numOfDefinedPools (conn);
7470
if (ret < 0)
7471
goto error;
7472
return ret;
7473
}
7474
7475
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7476
7477
error:
7478
virDispatchError(conn);
7479
return -1;
7480
}
7481
7482
7483
/**
7484
* virConnectListDefinedStoragePools:
7485
* @conn: pointer to hypervisor connection
7486
* @names: array of char * to fill with pool names (allocated by caller)
7487
* @maxnames: size of the names array
7488
*
7489
* Provides the list of names of inactive storage pools
7490
* upto maxnames. If there are more than maxnames, the
7491
* remaining names will be silently ignored.
7492
*
7493
* Returns 0 on success, -1 on error
7494
*/
7495
int
7496
virConnectListDefinedStoragePools(virConnectPtr conn,
7497
char **const names,
7498
int maxnames)
7499
{
7500
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
7501
7502
virResetLastError();
7503
7504
if (!VIR_IS_CONNECT(conn)) {
7505
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
7506
virDispatchError(NULL);
7507
return -1;
7508
}
7509
7510
if ((names == NULL) || (maxnames < 0)) {
7511
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7512
goto error;
7513
}
7514
7515
if (conn->storageDriver && conn->storageDriver->listDefinedPools) {
7516
int ret;
7517
ret = conn->storageDriver->listDefinedPools (conn, names, maxnames);
7518
if (ret < 0)
7519
goto error;
7520
return ret;
7521
}
7522
7523
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7524
7525
error:
7526
virDispatchError(conn);
7527
return -1;
7528
}
7529
7530
7531
/**
7532
* virConnectFindStoragePoolSources:
7533
* @conn: pointer to hypervisor connection
7534
* @type: type of storage pool sources to discover
7535
* @srcSpec: XML document specifying discovery source
7536
* @flags: flags for discovery (unused, pass 0)
7537
*
7538
* Talks to a storage backend and attempts to auto-discover the set of
7539
* available storage pool sources. e.g. For iSCSI this would be a set of
7540
* iSCSI targets. For NFS this would be a list of exported paths. The
7541
* srcSpec (optional for some storage pool types, e.g. local ones) is
7542
* an instance of the storage pool's source element specifying where
7543
* to look for the pools.
7544
*
7545
* srcSpec is not required for some types (e.g., those querying
7546
* local storage resources only)
7547
*
7548
* Returns an xml document consisting of a SourceList element
7549
* containing a source document appropriate to the given pool
7550
* type for each discovered source.
7551
*/
7552
char *
7553
virConnectFindStoragePoolSources(virConnectPtr conn,
7554
const char *type,
7555
const char *srcSpec,
7556
unsigned int flags)
7557
{
7558
DEBUG("conn=%p, type=%s, src=%s, flags=%u", conn, type ? type : "", srcSpec ? srcSpec : "", flags);
7559
7560
virResetLastError();
7561
7562
if (!VIR_IS_CONNECT(conn)) {
7563
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
7564
virDispatchError(NULL);
7565
return NULL;
7566
}
7567
if (type == NULL) {
7568
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7569
goto error;
7570
}
7571
7572
if (conn->flags & VIR_CONNECT_RO) {
7573
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
7574
goto error;
7575
}
7576
7577
if (conn->storageDriver && conn->storageDriver->findPoolSources) {
7578
char *ret;
7579
ret = conn->storageDriver->findPoolSources(conn, type, srcSpec, flags);
7580
if (!ret)
7581
goto error;
7582
return ret;
7583
}
7584
7585
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7586
7587
error:
7588
virDispatchError(conn);
7589
return NULL;
7590
}
7591
7592
7593
/**
7594
* virStoragePoolLookupByName:
7595
* @conn: pointer to hypervisor connection
7596
* @name: name of pool to fetch
7597
*
7598
* Fetch a storage pool based on its unique name
7599
*
7600
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
7601
*/
7602
virStoragePoolPtr
7603
virStoragePoolLookupByName(virConnectPtr conn,
7604
const char *name)
7605
{
7606
DEBUG("conn=%p, name=%s", conn, name);
7607
7608
virResetLastError();
7609
7610
if (!VIR_IS_CONNECT(conn)) {
7611
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
7612
virDispatchError(NULL);
7613
return NULL;
7614
}
7615
if (name == NULL) {
7616
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7617
goto error;
7618
}
7619
7620
if (conn->storageDriver && conn->storageDriver->poolLookupByName) {
7621
virStoragePoolPtr ret;
7622
ret = conn->storageDriver->poolLookupByName (conn, name);
7623
if (!ret)
7624
goto error;
7625
return ret;
7626
}
7627
7628
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7629
7630
error:
7631
virDispatchError(conn);
7632
return NULL;
7633
}
7634
7635
7636
/**
7637
* virStoragePoolLookupByUUID:
7638
* @conn: pointer to hypervisor connection
7639
* @uuid: globally unique id of pool to fetch
7640
*
7641
* Fetch a storage pool based on its globally unique id
7642
*
7643
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
7644
*/
7645
virStoragePoolPtr
7646
virStoragePoolLookupByUUID(virConnectPtr conn,
7647
const unsigned char *uuid)
7648
{
7649
DEBUG("conn=%p, uuid=%s", conn, uuid);
7650
7651
virResetLastError();
7652
7653
if (!VIR_IS_CONNECT(conn)) {
7654
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
7655
virDispatchError(NULL);
7656
return NULL;
7657
}
7658
if (uuid == NULL) {
7659
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7660
goto error;
7661
}
7662
7663
if (conn->storageDriver && conn->storageDriver->poolLookupByUUID) {
7664
virStoragePoolPtr ret;
7665
ret = conn->storageDriver->poolLookupByUUID (conn, uuid);
7666
if (!ret)
7667
goto error;
7668
return ret;
7669
}
7670
7671
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7672
7673
error:
7674
virDispatchError(conn);
7675
return NULL;
7676
}
7677
7678
7679
/**
7680
* virStoragePoolLookupByUUIDString:
7681
* @conn: pointer to hypervisor connection
7682
* @uuidstr: globally unique id of pool to fetch
7683
*
7684
* Fetch a storage pool based on its globally unique id
7685
*
7686
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
7687
*/
7688
virStoragePoolPtr
7689
virStoragePoolLookupByUUIDString(virConnectPtr conn,
7690
const char *uuidstr)
7691
{
7692
unsigned char uuid[VIR_UUID_BUFLEN];
7693
DEBUG("conn=%p, uuidstr=%s", conn, uuidstr);
7694
7695
virResetLastError();
7696
7697
if (!VIR_IS_CONNECT(conn)) {
7698
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
7699
virDispatchError(NULL);
7700
return NULL;
7701
}
7702
if (uuidstr == NULL) {
7703
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7704
goto error;
7705
}
7706
7707
if (virUUIDParse(uuidstr, uuid) < 0) {
7708
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7709
goto error;
7710
}
7711
7712
return virStoragePoolLookupByUUID(conn, uuid);
7713
7714
error:
7715
virDispatchError(conn);
7716
return NULL;
7717
}
7718
7719
7720
/**
7721
* virStoragePoolLookupByVolume:
7722
* @vol: pointer to storage volume
7723
*
7724
* Fetch a storage pool which contains a particular volume
7725
*
7726
* Returns a virStoragePoolPtr object, or NULL if no matching pool is found
7727
*/
7728
virStoragePoolPtr
7729
virStoragePoolLookupByVolume(virStorageVolPtr vol)
7730
{
7731
DEBUG("vol=%p", vol);
7732
7733
virResetLastError();
7734
7735
if (!VIR_IS_CONNECTED_STORAGE_VOL(vol)) {
7736
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
7737
virDispatchError(NULL);
7738
return NULL;
7739
}
7740
7741
if (vol->conn->storageDriver && vol->conn->storageDriver->poolLookupByVolume) {
7742
virStoragePoolPtr ret;
7743
ret = vol->conn->storageDriver->poolLookupByVolume (vol);
7744
if (!ret)
7745
goto error;
7746
return ret;
7747
}
7748
7749
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7750
7751
error:
7752
virDispatchError(vol->conn);
7753
return NULL;
7754
}
7755
7756
/**
7757
* virStoragePoolCreateXML:
7758
* @conn: pointer to hypervisor connection
7759
* @xmlDesc: XML description for new pool
7760
* @flags: future flags, use 0 for now
7761
*
7762
* Create a new storage based on its XML description. The
7763
* pool is not persistent, so its definition will disappear
7764
* when it is destroyed, or if the host is restarted
7765
*
7766
* Returns a virStoragePoolPtr object, or NULL if creation failed
7767
*/
7768
virStoragePoolPtr
7769
virStoragePoolCreateXML(virConnectPtr conn,
7770
const char *xmlDesc,
7771
unsigned int flags)
7772
{
7773
DEBUG("conn=%p, xmlDesc=%s", conn, xmlDesc);
7774
7775
virResetLastError();
7776
7777
if (!VIR_IS_CONNECT(conn)) {
7778
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
7779
virDispatchError(NULL);
7780
return NULL;
7781
}
7782
if (xmlDesc == NULL) {
7783
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7784
goto error;
7785
}
7786
if (conn->flags & VIR_CONNECT_RO) {
7787
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
7788
goto error;
7789
}
7790
7791
if (conn->storageDriver && conn->storageDriver->poolCreateXML) {
7792
virStoragePoolPtr ret;
7793
ret = conn->storageDriver->poolCreateXML (conn, xmlDesc, flags);
7794
if (!ret)
7795
goto error;
7796
return ret;
7797
}
7798
7799
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7800
7801
error:
7802
virDispatchError(conn);
7803
return NULL;
7804
}
7805
7806
/**
7807
* virStoragePoolDefineXML:
7808
* @conn: pointer to hypervisor connection
7809
* @xml: XML description for new pool
7810
* @flags: future flags, use 0 for now
7811
*
7812
* Define a new inactive storage pool based on its XML description. The
7813
* pool is persistent, until explicitly undefined.
7814
*
7815
* Returns a virStoragePoolPtr object, or NULL if creation failed
7816
*/
7817
virStoragePoolPtr
7818
virStoragePoolDefineXML(virConnectPtr conn,
7819
const char *xml,
7820
unsigned int flags)
7821
{
7822
DEBUG("conn=%p, xml=%s", conn, xml);
7823
7824
virResetLastError();
7825
7826
if (!VIR_IS_CONNECT(conn)) {
7827
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
7828
virDispatchError(NULL);
7829
return NULL;
7830
}
7831
if (conn->flags & VIR_CONNECT_RO) {
7832
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
7833
goto error;
7834
}
7835
if (xml == NULL) {
7836
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
7837
goto error;
7838
}
7839
7840
if (conn->storageDriver && conn->storageDriver->poolDefineXML) {
7841
virStoragePoolPtr ret;
7842
ret = conn->storageDriver->poolDefineXML (conn, xml, flags);
7843
if (!ret)
7844
goto error;
7845
return ret;
7846
}
7847
7848
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7849
7850
error:
7851
virDispatchError(conn);
7852
return NULL;
7853
}
7854
7855
/**
7856
* virStoragePoolBuild:
7857
* @pool: pointer to storage pool
7858
* @flags: future flags, use 0 for now
7859
*
7860
* Build the underlying storage pool
7861
*
7862
* Returns 0 on success, or -1 upon failure
7863
*/
7864
int
7865
virStoragePoolBuild(virStoragePoolPtr pool,
7866
unsigned int flags)
7867
{
7868
virConnectPtr conn;
7869
DEBUG("pool=%p, flags=%u", pool, flags);
7870
7871
virResetLastError();
7872
7873
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
7874
virLibStoragePoolError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
7875
virDispatchError(NULL);
7876
return -1;
7877
}
7878
conn = pool->conn;
7879
if (conn->flags & VIR_CONNECT_RO) {
7880
virLibStoragePoolError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
7881
goto error;
7882
}
7883
7884
if (conn->storageDriver && conn->storageDriver->poolBuild) {
7885
int ret;
7886
ret = conn->storageDriver->poolBuild (pool, flags);
7887
if (ret < 0)
7888
goto error;
7889
return ret;
7890
}
7891
7892
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7893
7894
error:
7895
virDispatchError(pool->conn);
7896
return -1;
7897
}
7898
7899
7900
/**
7901
* virStoragePoolUndefine:
7902
* @pool: pointer to storage pool
7903
*
7904
* Undefine an inactive storage pool
7905
*
7906
* Returns 0 on success, -1 on failure
7907
*/
7908
int
7909
virStoragePoolUndefine(virStoragePoolPtr pool)
7910
{
7911
virConnectPtr conn;
7912
DEBUG("pool=%p", pool);
7913
7914
virResetLastError();
7915
7916
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
7917
virLibStoragePoolError(VIR_ERR_INVALID_NETWORK, __FUNCTION__);
7918
virDispatchError(NULL);
7919
return -1;
7920
}
7921
conn = pool->conn;
7922
if (conn->flags & VIR_CONNECT_RO) {
7923
virLibStoragePoolError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
7924
goto error;
7925
}
7926
7927
if (conn->storageDriver && conn->storageDriver->poolUndefine) {
7928
int ret;
7929
ret = conn->storageDriver->poolUndefine (pool);
7930
if (ret < 0)
7931
goto error;
7932
return ret;
7933
}
7934
7935
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7936
7937
error:
7938
virDispatchError(pool->conn);
7939
return -1;
7940
}
7941
7942
7943
/**
7944
* virStoragePoolCreate:
7945
* @pool: pointer to storage pool
7946
* @flags: future flags, use 0 for now
7947
*
7948
* Starts an inactive storage pool
7949
*
7950
* Returns 0 on success, or -1 if it could not be started
7951
*/
7952
int
7953
virStoragePoolCreate(virStoragePoolPtr pool,
7954
unsigned int flags)
7955
{
7956
virConnectPtr conn;
7957
DEBUG("pool=%p", pool);
7958
7959
virResetLastError();
7960
7961
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
7962
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
7963
virDispatchError(NULL);
7964
return -1;
7965
}
7966
conn = pool->conn;
7967
if (conn->flags & VIR_CONNECT_RO) {
7968
virLibStoragePoolError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
7969
goto error;
7970
}
7971
7972
if (conn->storageDriver && conn->storageDriver->poolCreate) {
7973
int ret;
7974
ret = conn->storageDriver->poolCreate (pool, flags);
7975
if (ret < 0)
7976
goto error;
7977
return ret;
7978
}
7979
7980
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
7981
7982
error:
7983
virDispatchError(pool->conn);
7984
return -1;
7985
}
7986
7987
7988
/**
7989
* virStoragePoolDestroy:
7990
* @pool: pointer to storage pool
7991
*
7992
* Destroy an active storage pool. This will deactivate the
7993
* pool on the host, but keep any persistent config associated
7994
* with it. If it has a persistent config it can later be
7995
* restarted with virStoragePoolCreate(). This does not free
7996
* the associated virStoragePoolPtr object.
7997
*
7998
* Returns 0 on success, or -1 if it could not be destroyed
7999
*/
8000
int
8001
virStoragePoolDestroy(virStoragePoolPtr pool)
8002
{
8003
virConnectPtr conn;
8004
DEBUG("pool=%p", pool);
8005
8006
virResetLastError();
8007
8008
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
8009
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8010
virDispatchError(NULL);
8011
return -1;
8012
}
8013
8014
conn = pool->conn;
8015
if (conn->flags & VIR_CONNECT_RO) {
8016
virLibStoragePoolError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
8017
goto error;
8018
}
8019
8020
if (conn->storageDriver && conn->storageDriver->poolDestroy) {
8021
int ret;
8022
ret = conn->storageDriver->poolDestroy (pool);
8023
if (ret < 0)
8024
goto error;
8025
return ret;
8026
}
8027
8028
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8029
8030
error:
8031
virDispatchError(pool->conn);
8032
return -1;
8033
}
8034
8035
/**
8036
* virStoragePoolDelete:
8037
* @pool: pointer to storage pool
8038
* @flags: flags for obliteration process
8039
*
8040
* Delete the underlying pool resources. This is
8041
* a non-recoverable operation. The virStoragePoolPtr object
8042
* itself is not free'd.
8043
*
8044
* Returns 0 on success, or -1 if it could not be obliterate
8045
*/
8046
int
8047
virStoragePoolDelete(virStoragePoolPtr pool,
8048
unsigned int flags)
8049
{
8050
virConnectPtr conn;
8051
DEBUG("pool=%p, flags=%u", pool, flags);
8052
8053
virResetLastError();
8054
8055
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
8056
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8057
virDispatchError(NULL);
8058
return -1;
8059
}
8060
8061
conn = pool->conn;
8062
if (conn->flags & VIR_CONNECT_RO) {
8063
virLibStoragePoolError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
8064
goto error;
8065
}
8066
8067
if (conn->storageDriver && conn->storageDriver->poolDelete) {
8068
int ret;
8069
ret = conn->storageDriver->poolDelete (pool, flags);
8070
if (ret < 0)
8071
goto error;
8072
return ret;
8073
}
8074
8075
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8076
8077
error:
8078
virDispatchError(pool->conn);
8079
return -1;
8080
}
8081
8082
8083
/**
8084
* virStoragePoolFree:
8085
* @pool: pointer to storage pool
8086
*
8087
* Free a storage pool object, releasing all memory associated with
8088
* it. Does not change the state of the pool on the host.
8089
*
8090
* Returns 0 on success, or -1 if it could not be free'd.
8091
*/
8092
int
8093
virStoragePoolFree(virStoragePoolPtr pool)
8094
{
8095
DEBUG("pool=%p", pool);
8096
8097
virResetLastError();
8098
8099
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
8100
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8101
virDispatchError(NULL);
8102
return -1;
8103
}
8104
if (virUnrefStoragePool(pool) < 0) {
8105
virDispatchError(NULL);
8106
return -1;
8107
}
8108
return 0;
8109
8110
}
8111
8112
8113
/**
8114
* virStoragePoolRef:
8115
* @pool: the pool to hold a reference on
8116
*
8117
* Increment the reference count on the pool. For each
8118
* additional call to this method, there shall be a corresponding
8119
* call to virStoragePoolFree to release the reference count, once
8120
* the caller no longer needs the reference to this object.
8121
*
8122
* This method is typically useful for applications where multiple
8123
* threads are using a connection, and it is required that the
8124
* connection remain open until all threads have finished using
8125
* it. ie, each new thread using a pool would increment
8126
* the reference count.
8127
*
8128
* Returns 0 in case of success, -1 in case of failure.
8129
*/
8130
int
8131
virStoragePoolRef(virStoragePoolPtr pool)
8132
{
8133
if ((!VIR_IS_CONNECTED_STORAGE_POOL(pool))) {
8134
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
8135
virDispatchError(NULL);
8136
return -1;
8137
}
8138
virMutexLock(&pool->conn->lock);
8139
DEBUG("pool=%p refs=%d", pool, pool->refs);
8140
pool->refs++;
8141
virMutexUnlock(&pool->conn->lock);
8142
return 0;
8143
}
8144
8145
/**
8146
* virStoragePoolRefresh:
8147
* @pool: pointer to storage pool
8148
* @flags: flags to control refresh behaviour (currently unused, use 0)
8149
*
8150
* Request that the pool refresh its list of volumes. This may
8151
* involve communicating with a remote server, and/or initializing
8152
* new devices at the OS layer
8153
*
8154
* Returns 0 if the volume list was refreshed, -1 on failure
8155
*/
8156
int
8157
virStoragePoolRefresh(virStoragePoolPtr pool,
8158
unsigned int flags)
8159
{
8160
virConnectPtr conn;
8161
DEBUG("pool=%p flags=%u", pool, flags);
8162
8163
virResetLastError();
8164
8165
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
8166
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8167
virDispatchError(NULL);
8168
return -1;
8169
}
8170
8171
conn = pool->conn;
8172
if (conn->flags & VIR_CONNECT_RO) {
8173
virLibStoragePoolError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
8174
goto error;
8175
}
8176
8177
if (conn->storageDriver && conn->storageDriver->poolRefresh) {
8178
int ret;
8179
ret = conn->storageDriver->poolRefresh (pool, flags);
8180
if (ret < 0)
8181
goto error;
8182
return ret;
8183
}
8184
8185
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8186
8187
error:
8188
virDispatchError(pool->conn);
8189
return -1;
8190
}
8191
8192
8193
/**
8194
* virStoragePoolGetName:
8195
* @pool: pointer to storage pool
8196
*
8197
* Fetch the locally unique name of the storage pool
8198
*
8199
* Returns the name of the pool, or NULL on error
8200
*/
8201
const char*
8202
virStoragePoolGetName(virStoragePoolPtr pool)
8203
{
8204
DEBUG("pool=%p", pool);
8205
8206
virResetLastError();
8207
8208
if (!VIR_IS_STORAGE_POOL(pool)) {
8209
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8210
virDispatchError(NULL);
8211
return NULL;
8212
}
8213
return pool->name;
8214
}
8215
8216
8217
/**
8218
* virStoragePoolGetUUID:
8219
* @pool: pointer to storage pool
8220
* @uuid: buffer of VIR_UUID_BUFLEN bytes in size
8221
*
8222
* Fetch the globally unique ID of the storage pool
8223
*
8224
* Returns 0 on success, or -1 on error;
8225
*/
8226
int
8227
virStoragePoolGetUUID(virStoragePoolPtr pool,
8228
unsigned char *uuid)
8229
{
8230
DEBUG("pool=%p, uuid=%p", pool, uuid);
8231
8232
virResetLastError();
8233
8234
if (!VIR_IS_STORAGE_POOL(pool)) {
8235
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8236
virDispatchError(NULL);
8237
return -1;
8238
}
8239
if (uuid == NULL) {
8240
virLibStoragePoolError(VIR_ERR_INVALID_ARG, __FUNCTION__);
8241
goto error;
8242
}
8243
8244
memcpy(uuid, &pool->uuid[0], VIR_UUID_BUFLEN);
8245
8246
return 0;
8247
8248
error:
8249
virDispatchError(pool->conn);
8250
return -1;
8251
}
8252
8253
/**
8254
* virStoragePoolGetUUIDString:
8255
* @pool: pointer to storage pool
8256
* @buf: buffer of VIR_UUID_STRING_BUFLEN bytes in size
8257
*
8258
* Fetch the globally unique ID of the storage pool as a string
8259
*
8260
* Returns 0 on success, or -1 on error;
8261
*/
8262
int
8263
virStoragePoolGetUUIDString(virStoragePoolPtr pool,
8264
char *buf)
8265
{
8266
unsigned char uuid[VIR_UUID_BUFLEN];
8267
DEBUG("pool=%p, buf=%p", pool, buf);
8268
8269
virResetLastError();
8270
8271
if (!VIR_IS_STORAGE_POOL(pool)) {
8272
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8273
virDispatchError(NULL);
8274
return -1;
8275
}
8276
if (buf == NULL) {
8277
virLibStoragePoolError(VIR_ERR_INVALID_ARG, __FUNCTION__);
8278
goto error;
8279
}
8280
8281
if (virStoragePoolGetUUID(pool, &uuid[0]))
8282
goto error;
8283
8284
virUUIDFormat(uuid, buf);
8285
return 0;
8286
8287
error:
8288
virDispatchError(pool->conn);
8289
return -1;
8290
}
8291
8292
8293
/**
8294
* virStoragePoolGetInfo:
8295
* @pool: pointer to storage pool
8296
* @info: pointer at which to store info
8297
*
8298
* Get volatile information about the storage pool
8299
* such as free space / usage summary
8300
*
8301
* Returns 0 on success, or -1 on failure.
8302
*/
8303
int
8304
virStoragePoolGetInfo(virStoragePoolPtr pool,
8305
virStoragePoolInfoPtr info)
8306
{
8307
virConnectPtr conn;
8308
DEBUG("pool=%p, info=%p", pool, info);
8309
8310
virResetLastError();
8311
8312
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
8313
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8314
virDispatchError(NULL);
8315
return -1;
8316
}
8317
if (info == NULL) {
8318
virLibStoragePoolError(VIR_ERR_INVALID_ARG, __FUNCTION__);
8319
goto error;
8320
}
8321
8322
memset(info, 0, sizeof(virStoragePoolInfo));
8323
8324
conn = pool->conn;
8325
8326
if (conn->storageDriver->poolGetInfo) {
8327
int ret;
8328
ret = conn->storageDriver->poolGetInfo (pool, info);
8329
if (ret < 0)
8330
goto error;
8331
return ret;
8332
}
8333
8334
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8335
8336
error:
8337
virDispatchError(pool->conn);
8338
return -1;
8339
}
8340
8341
8342
/**
8343
* virStoragePoolGetXMLDesc:
8344
* @pool: pointer to storage pool
8345
* @flags: flags for XML format options (set of virDomainXMLFlags)
8346
*
8347
* Fetch an XML document describing all aspects of the
8348
* storage pool. This is suitable for later feeding back
8349
* into the virStoragePoolCreateXML method.
8350
*
8351
* Returns a XML document, or NULL on error
8352
*/
8353
char *
8354
virStoragePoolGetXMLDesc(virStoragePoolPtr pool,
8355
unsigned int flags)
8356
{
8357
virConnectPtr conn;
8358
DEBUG("pool=%p, flags=%u", pool, flags);
8359
8360
virResetLastError();
8361
8362
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
8363
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8364
virDispatchError(NULL);
8365
return NULL;
8366
}
8367
if (flags != 0) {
8368
virLibStoragePoolError(VIR_ERR_INVALID_ARG, __FUNCTION__);
8369
goto error;
8370
}
8371
8372
conn = pool->conn;
8373
8374
if (conn->storageDriver && conn->storageDriver->poolGetXMLDesc) {
8375
char *ret;
8376
ret = conn->storageDriver->poolGetXMLDesc (pool, flags);
8377
if (!ret)
8378
goto error;
8379
return ret;
8380
}
8381
8382
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8383
8384
error:
8385
virDispatchError(pool->conn);
8386
return NULL;
8387
}
8388
8389
8390
/**
8391
* virStoragePoolGetAutostart:
8392
* @pool: pointer to storage pool
8393
* @autostart: location in which to store autostart flag
8394
*
8395
* Fetches the value of the autostart flag, which determines
8396
* whether the pool is automatically started at boot time
8397
*
8398
* Returns 0 on success, -1 on failure
8399
*/
8400
int
8401
virStoragePoolGetAutostart(virStoragePoolPtr pool,
8402
int *autostart)
8403
{
8404
virConnectPtr conn;
8405
DEBUG("pool=%p, autostart=%p", pool, autostart);
8406
8407
virResetLastError();
8408
8409
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
8410
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8411
virDispatchError(NULL);
8412
return -1;
8413
}
8414
if (!autostart) {
8415
virLibStoragePoolError(VIR_ERR_INVALID_ARG, __FUNCTION__);
8416
goto error;
8417
}
8418
8419
conn = pool->conn;
8420
8421
if (conn->storageDriver && conn->storageDriver->poolGetAutostart) {
8422
int ret;
8423
ret = conn->storageDriver->poolGetAutostart (pool, autostart);
8424
if (ret < 0)
8425
goto error;
8426
return ret;
8427
}
8428
8429
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8430
8431
error:
8432
virDispatchError(pool->conn);
8433
return -1;
8434
}
8435
8436
8437
/**
8438
* virStoragePoolSetAutostart:
8439
* @pool: pointer to storage pool
8440
* @autostart: new flag setting
8441
*
8442
* Sets the autostart flag
8443
*
8444
* Returns 0 on success, -1 on failure
8445
*/
8446
int
8447
virStoragePoolSetAutostart(virStoragePoolPtr pool,
8448
int autostart)
8449
{
8450
virConnectPtr conn;
8451
DEBUG("pool=%p, autostart=%d", pool, autostart);
8452
8453
virResetLastError();
8454
8455
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
8456
virLibStoragePoolError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8457
virDispatchError(NULL);
8458
return -1;
8459
}
8460
8461
if (pool->conn->flags & VIR_CONNECT_RO) {
8462
virLibStoragePoolError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
8463
goto error;
8464
}
8465
8466
conn = pool->conn;
8467
8468
if (conn->storageDriver && conn->storageDriver->poolSetAutostart) {
8469
int ret;
8470
ret = conn->storageDriver->poolSetAutostart (pool, autostart);
8471
if (ret < 0)
8472
goto error;
8473
return ret;
8474
}
8475
8476
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8477
8478
error:
8479
virDispatchError(pool->conn);
8480
return -1;
8481
}
8482
8483
8484
/**
8485
* virStoragePoolNumOfVolumes:
8486
* @pool: pointer to storage pool
8487
*
8488
* Fetch the number of storage volumes within a pool
8489
*
8490
* Returns the number of storage pools, or -1 on failure
8491
*/
8492
int
8493
virStoragePoolNumOfVolumes(virStoragePoolPtr pool)
8494
{
8495
DEBUG("pool=%p", pool);
8496
8497
virResetLastError();
8498
8499
if (!VIR_IS_STORAGE_POOL(pool)) {
8500
virLibConnError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8501
virDispatchError(NULL);
8502
return -1;
8503
}
8504
8505
if (pool->conn->storageDriver && pool->conn->storageDriver->poolNumOfVolumes) {
8506
int ret;
8507
ret = pool->conn->storageDriver->poolNumOfVolumes (pool);
8508
if (ret < 0)
8509
goto error;
8510
return ret;
8511
}
8512
8513
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8514
8515
error:
8516
virDispatchError(pool->conn);
8517
return -1;
8518
}
8519
8520
8521
/**
8522
* virStoragePoolListVolumes:
8523
* @pool: pointer to storage pool
8524
* @names: array in which to storage volume names
8525
* @maxnames: size of names array
8526
*
8527
* Fetch list of storage volume names, limiting to
8528
* at most maxnames.
8529
*
8530
* Returns the number of names fetched, or -1 on error
8531
*/
8532
int
8533
virStoragePoolListVolumes(virStoragePoolPtr pool,
8534
char **const names,
8535
int maxnames)
8536
{
8537
DEBUG("pool=%p, names=%p, maxnames=%d", pool, names, maxnames);
8538
8539
virResetLastError();
8540
8541
if (!VIR_IS_STORAGE_POOL(pool)) {
8542
virLibConnError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8543
virDispatchError(NULL);
8544
return -1;
8545
}
8546
8547
if ((names == NULL) || (maxnames < 0)) {
8548
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
8549
goto error;
8550
}
8551
8552
if (pool->conn->storageDriver && pool->conn->storageDriver->poolListVolumes) {
8553
int ret;
8554
ret = pool->conn->storageDriver->poolListVolumes (pool, names, maxnames);
8555
if (ret < 0)
8556
goto error;
8557
return ret;
8558
}
8559
8560
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8561
8562
error:
8563
virDispatchError(pool->conn);
8564
return -1;
8565
}
8566
8567
8568
/**
8569
* virStorageVolGetConnect:
8570
* @vol: pointer to a pool
8571
*
8572
* Provides the connection pointer associated with a storage volume. The
8573
* reference counter on the connection is not increased by this
8574
* call.
8575
*
8576
* WARNING: When writing libvirt bindings in other languages, do
8577
* not use this function. Instead, store the connection and
8578
* the volume object together.
8579
*
8580
* Returns the virConnectPtr or NULL in case of failure.
8581
*/
8582
virConnectPtr
8583
virStorageVolGetConnect (virStorageVolPtr vol)
8584
{
8585
DEBUG("vol=%p", vol);
8586
8587
virResetLastError();
8588
8589
if (!VIR_IS_STORAGE_VOL (vol)) {
8590
virLibStorageVolError(VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
8591
virDispatchError(NULL);
8592
return NULL;
8593
}
8594
return vol->conn;
8595
}
8596
8597
8598
/**
8599
* virStorageVolLookupByName:
8600
* @pool: pointer to storage pool
8601
* @name: name of storage volume
8602
*
8603
* Fetch a pointer to a storage volume based on its name
8604
* within a pool
8605
*
8606
* Returns a storage volume, or NULL if not found / error
8607
*/
8608
virStorageVolPtr
8609
virStorageVolLookupByName(virStoragePoolPtr pool,
8610
const char *name)
8611
{
8612
DEBUG("pool=%p, name=%s", pool, name);
8613
8614
virResetLastError();
8615
8616
if (!VIR_IS_STORAGE_POOL(pool)) {
8617
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
8618
virDispatchError(NULL);
8619
return NULL;
8620
}
8621
if (name == NULL) {
8622
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
8623
goto error;
8624
}
8625
8626
if (pool->conn->storageDriver && pool->conn->storageDriver->volLookupByName) {
8627
virStorageVolPtr ret;
8628
ret = pool->conn->storageDriver->volLookupByName (pool, name);
8629
if (!ret)
8630
goto error;
8631
return ret;
8632
}
8633
8634
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8635
8636
error:
8637
virDispatchError(pool->conn);
8638
return NULL;
8639
}
8640
8641
8642
8643
/**
8644
* virStorageVolLookupByKey:
8645
* @conn: pointer to hypervisor connection
8646
* @key: globally unique key
8647
*
8648
* Fetch a pointer to a storage volume based on its
8649
* globally unique key
8650
*
8651
* Returns a storage volume, or NULL if not found / error
8652
*/
8653
virStorageVolPtr
8654
virStorageVolLookupByKey(virConnectPtr conn,
8655
const char *key)
8656
{
8657
DEBUG("conn=%p, key=%s", conn, key);
8658
8659
virResetLastError();
8660
8661
if (!VIR_IS_CONNECT(conn)) {
8662
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
8663
virDispatchError(NULL);
8664
return NULL;
8665
}
8666
if (key == NULL) {
8667
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
8668
goto error;
8669
}
8670
8671
if (conn->storageDriver && conn->storageDriver->volLookupByKey) {
8672
virStorageVolPtr ret;
8673
ret = conn->storageDriver->volLookupByKey (conn, key);
8674
if (!ret)
8675
goto error;
8676
return ret;
8677
}
8678
8679
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8680
8681
error:
8682
virDispatchError(conn);
8683
return NULL;
8684
}
8685
8686
/**
8687
* virStorageVolLookupByPath:
8688
* @conn: pointer to hypervisor connection
8689
* @path: locally unique path
8690
*
8691
* Fetch a pointer to a storage volume based on its
8692
* locally (host) unique path
8693
*
8694
* Returns a storage volume, or NULL if not found / error
8695
*/
8696
virStorageVolPtr
8697
virStorageVolLookupByPath(virConnectPtr conn,
8698
const char *path)
8699
{
8700
DEBUG("conn=%p, path=%s", conn, path);
8701
8702
virResetLastError();
8703
8704
if (!VIR_IS_CONNECT(conn)) {
8705
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
8706
virDispatchError(NULL);
8707
return NULL;
8708
}
8709
if (path == NULL) {
8710
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
8711
goto error;
8712
}
8713
8714
if (conn->storageDriver && conn->storageDriver->volLookupByPath) {
8715
virStorageVolPtr ret;
8716
ret = conn->storageDriver->volLookupByPath (conn, path);
8717
if (!ret)
8718
goto error;
8719
return ret;
8720
}
8721
8722
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8723
8724
error:
8725
virDispatchError(conn);
8726
return NULL;
8727
}
8728
8729
8730
/**
8731
* virStorageVolGetName:
8732
* @vol: pointer to storage volume
8733
*
8734
* Fetch the storage volume name. This is unique
8735
* within the scope of a pool
8736
*
8737
* Returns the volume name, or NULL on error
8738
*/
8739
const char*
8740
virStorageVolGetName(virStorageVolPtr vol)
8741
{
8742
DEBUG("vol=%p", vol);
8743
8744
virResetLastError();
8745
8746
if (!VIR_IS_STORAGE_VOL(vol)) {
8747
virLibStorageVolError(VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
8748
virDispatchError(NULL);
8749
return NULL;
8750
}
8751
return vol->name;
8752
}
8753
8754
8755
/**
8756
* virStorageVolGetKey:
8757
* @vol: pointer to storage volume
8758
*
8759
* Fetch the storage volume key. This is globally
8760
* unique, so the same volume will have the same
8761
* key no matter what host it is accessed from
8762
*
8763
* Returns the volume key, or NULL on error
8764
*/
8765
const char*
8766
virStorageVolGetKey(virStorageVolPtr vol)
8767
{
8768
DEBUG("vol=%p", vol);
8769
8770
virResetLastError();
8771
8772
if (!VIR_IS_STORAGE_VOL(vol)) {
8773
virLibStorageVolError(VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
8774
virDispatchError(NULL);
8775
return NULL;
8776
}
8777
return vol->key;
8778
}
8779
8780
8781
/**
8782
* virStorageVolCreateXML:
8783
* @pool: pointer to storage pool
8784
* @xmldesc: description of volume to create
8785
* @flags: flags for creation (unused, pass 0)
8786
*
8787
* Create a storage volume within a pool based
8788
* on an XML description. Not all pools support
8789
* creation of volumes
8790
*
8791
* Returns the storage volume, or NULL on error
8792
*/
8793
virStorageVolPtr
8794
virStorageVolCreateXML(virStoragePoolPtr pool,
8795
const char *xmldesc,
8796
unsigned int flags)
8797
{
8798
DEBUG("pool=%p, flags=%u", pool, flags);
8799
8800
virResetLastError();
8801
8802
if (!VIR_IS_STORAGE_POOL(pool)) {
8803
virLibConnError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8804
virDispatchError(NULL);
8805
return NULL;
8806
}
8807
8808
if (pool->conn->flags & VIR_CONNECT_RO) {
8809
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
8810
goto error;
8811
}
8812
8813
if (pool->conn->storageDriver && pool->conn->storageDriver->volCreateXML) {
8814
virStorageVolPtr ret;
8815
ret = pool->conn->storageDriver->volCreateXML (pool, xmldesc, flags);
8816
if (!ret)
8817
goto error;
8818
return ret;
8819
}
8820
8821
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8822
8823
error:
8824
virDispatchError(pool->conn);
8825
return NULL;
8826
}
8827
8828
8829
/**
8830
* virStorageVolCreateXMLFrom:
8831
* @pool: pointer to parent pool for the new volume
8832
* @xmldesc: description of volume to create
8833
* @clonevol: storage volume to use as input
8834
* @flags: flags for creation (unused, pass 0)
8835
*
8836
* Create a storage volume in the parent pool, using the
8837
* 'clonevol' volume as input. Information for the new
8838
* volume (name, perms) are passed via a typical volume
8839
* XML description.
8840
*
8841
* Returns the storage volume, or NULL on error
8842
*/
8843
virStorageVolPtr
8844
virStorageVolCreateXMLFrom(virStoragePoolPtr pool,
8845
const char *xmldesc,
8846
virStorageVolPtr clonevol,
8847
unsigned int flags)
8848
{
8849
DEBUG("pool=%p, flags=%u, clonevol=%p", pool, flags, clonevol);
8850
8851
virResetLastError();
8852
8853
if (!VIR_IS_STORAGE_POOL(pool)) {
8854
virLibConnError(VIR_ERR_INVALID_STORAGE_POOL, __FUNCTION__);
8855
virDispatchError(NULL);
8856
return NULL;
8857
}
8858
8859
if (!VIR_IS_STORAGE_VOL(clonevol)) {
8860
virLibConnError(VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
8861
goto error;
8862
}
8863
8864
if (pool->conn->flags & VIR_CONNECT_RO ||
8865
clonevol->conn->flags & VIR_CONNECT_RO) {
8866
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
8867
goto error;
8868
}
8869
8870
if (pool->conn->storageDriver &&
8871
pool->conn->storageDriver->volCreateXMLFrom) {
8872
virStorageVolPtr ret;
8873
ret = pool->conn->storageDriver->volCreateXMLFrom (pool, xmldesc,
8874
clonevol, flags);
8875
if (!ret)
8876
goto error;
8877
return ret;
8878
}
8879
8880
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8881
8882
error:
8883
virDispatchError(pool->conn);
8884
return NULL;
8885
}
8886
8887
8888
/**
8889
* virStorageVolDelete:
8890
* @vol: pointer to storage volume
8891
* @flags: future flags, use 0 for now
8892
*
8893
* Delete the storage volume from the pool
8894
*
8895
* Returns 0 on success, or -1 on error
8896
*/
8897
int
8898
virStorageVolDelete(virStorageVolPtr vol,
8899
unsigned int flags)
8900
{
8901
virConnectPtr conn;
8902
DEBUG("vol=%p, flags=%u", vol, flags);
8903
8904
virResetLastError();
8905
8906
if (!VIR_IS_CONNECTED_STORAGE_VOL(vol)) {
8907
virLibStorageVolError(VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
8908
virDispatchError(NULL);
8909
return -1;
8910
}
8911
8912
conn = vol->conn;
8913
if (conn->flags & VIR_CONNECT_RO) {
8914
virLibStorageVolError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
8915
goto error;
8916
}
8917
8918
if (conn->storageDriver && conn->storageDriver->volDelete) {
8919
int ret;
8920
ret = conn->storageDriver->volDelete (vol, flags);
8921
if (ret < 0)
8922
goto error;
8923
return ret;
8924
}
8925
8926
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8927
8928
error:
8929
virDispatchError(vol->conn);
8930
return -1;
8931
}
8932
8933
8934
/**
8935
* virStorageVolWipe:
8936
* @vol: pointer to storage volume
8937
* @flags: future flags, use 0 for now
8938
*
8939
* Ensure data previously on a volume is not accessible to future reads
8940
*
8941
* Returns 0 on success, or -1 on error
8942
*/
8943
int
8944
virStorageVolWipe(virStorageVolPtr vol,
8945
unsigned int flags)
8946
{
8947
virConnectPtr conn;
8948
VIR_DEBUG("vol=%p, flags=%u", vol, flags);
8949
8950
virResetLastError();
8951
8952
if (!VIR_IS_CONNECTED_STORAGE_VOL(vol)) {
8953
virLibStorageVolError(VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
8954
virDispatchError(NULL);
8955
return -1;
8956
}
8957
8958
conn = vol->conn;
8959
if (conn->flags & VIR_CONNECT_RO) {
8960
virLibStorageVolError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
8961
goto error;
8962
}
8963
8964
if (conn->storageDriver && conn->storageDriver->volWipe) {
8965
int ret;
8966
ret = conn->storageDriver->volWipe(vol, flags);
8967
if (ret < 0) {
8968
goto error;
8969
}
8970
return ret;
8971
}
8972
8973
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
8974
8975
error:
8976
virDispatchError(vol->conn);
8977
return -1;
8978
}
8979
8980
8981
/**
8982
* virStorageVolFree:
8983
* @vol: pointer to storage volume
8984
*
8985
* Release the storage volume handle. The underlying
8986
* storage volume continues to exist.
8987
*
8988
* Returns 0 on success, or -1 on error
8989
*/
8990
int
8991
virStorageVolFree(virStorageVolPtr vol)
8992
{
8993
DEBUG("vol=%p", vol);
8994
8995
virResetLastError();
8996
8997
if (!VIR_IS_STORAGE_VOL(vol)) {
8998
virLibStorageVolError(VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
8999
virDispatchError(NULL);
9000
return -1;
9001
}
9002
if (virUnrefStorageVol(vol) < 0) {
9003
virDispatchError(NULL);
9004
return -1;
9005
}
9006
return 0;
9007
}
9008
9009
9010
/**
9011
* virStorageVolRef:
9012
* @vol: the vol to hold a reference on
9013
*
9014
* Increment the reference count on the vol. For each
9015
* additional call to this method, there shall be a corresponding
9016
* call to virStorageVolFree to release the reference count, once
9017
* the caller no longer needs the reference to this object.
9018
*
9019
* This method is typically useful for applications where multiple
9020
* threads are using a connection, and it is required that the
9021
* connection remain open until all threads have finished using
9022
* it. ie, each new thread using a vol would increment
9023
* the reference count.
9024
*
9025
* Returns 0 in case of success, -1 in case of failure.
9026
*/
9027
int
9028
virStorageVolRef(virStorageVolPtr vol)
9029
{
9030
if ((!VIR_IS_CONNECTED_STORAGE_VOL(vol))) {
9031
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9032
virDispatchError(NULL);
9033
return -1;
9034
}
9035
virMutexLock(&vol->conn->lock);
9036
DEBUG("vol=%p refs=%d", vol, vol->refs);
9037
vol->refs++;
9038
virMutexUnlock(&vol->conn->lock);
9039
return 0;
9040
}
9041
9042
/**
9043
* virStorageVolGetInfo:
9044
* @vol: pointer to storage volume
9045
* @info: pointer at which to store info
9046
*
9047
* Fetches volatile information about the storage
9048
* volume such as its current allocation
9049
*
9050
* Returns 0 on success, or -1 on failure
9051
*/
9052
int
9053
virStorageVolGetInfo(virStorageVolPtr vol,
9054
virStorageVolInfoPtr info)
9055
{
9056
virConnectPtr conn;
9057
DEBUG("vol=%p, info=%p", vol, info);
9058
9059
virResetLastError();
9060
9061
if (!VIR_IS_CONNECTED_STORAGE_VOL(vol)) {
9062
virLibStorageVolError(VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
9063
virDispatchError(NULL);
9064
return -1;
9065
}
9066
if (info == NULL) {
9067
virLibStorageVolError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9068
goto error;
9069
}
9070
9071
memset(info, 0, sizeof(virStorageVolInfo));
9072
9073
conn = vol->conn;
9074
9075
if (conn->storageDriver->volGetInfo){
9076
int ret;
9077
ret = conn->storageDriver->volGetInfo (vol, info);
9078
if (ret < 0)
9079
goto error;
9080
return ret;
9081
}
9082
9083
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9084
9085
error:
9086
virDispatchError(vol->conn);
9087
return -1;
9088
}
9089
9090
9091
/**
9092
* virStorageVolGetXMLDesc:
9093
* @vol: pointer to storage volume
9094
* @flags: flags for XML generation (unused, pass 0)
9095
*
9096
* Fetch an XML document describing all aspects of
9097
* the storage volume
9098
*
9099
* Returns the XML document, or NULL on error
9100
*/
9101
char *
9102
virStorageVolGetXMLDesc(virStorageVolPtr vol,
9103
unsigned int flags)
9104
{
9105
virConnectPtr conn;
9106
DEBUG("vol=%p, flags=%u", vol, flags);
9107
9108
virResetLastError();
9109
9110
if (!VIR_IS_STORAGE_VOL(vol)) {
9111
virLibStorageVolError(VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
9112
virDispatchError(NULL);
9113
return NULL;
9114
}
9115
if (flags != 0) {
9116
virLibStorageVolError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9117
goto error;
9118
}
9119
9120
conn = vol->conn;
9121
9122
if (conn->storageDriver && conn->storageDriver->volGetXMLDesc) {
9123
char *ret;
9124
ret = conn->storageDriver->volGetXMLDesc (vol, flags);
9125
if (!ret)
9126
goto error;
9127
return ret;
9128
}
9129
9130
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9131
9132
error:
9133
virDispatchError(vol->conn);
9134
return NULL;
9135
}
9136
9137
9138
/**
9139
* virStorageVolGetPath:
9140
* @vol: pointer to storage volume
9141
*
9142
* Fetch the storage volume path. Depending on the pool
9143
* configuration this is either persistent across hosts,
9144
* or dynamically assigned at pool startup. Consult
9145
* pool documentation for information on getting the
9146
* persistent naming
9147
*
9148
* Returns the storage volume path, or NULL on error
9149
*/
9150
char *
9151
virStorageVolGetPath(virStorageVolPtr vol)
9152
{
9153
virConnectPtr conn;
9154
DEBUG("vol=%p", vol);
9155
9156
virResetLastError();
9157
9158
if (!VIR_IS_STORAGE_VOL(vol)) {
9159
virLibStorageVolError(VIR_ERR_INVALID_STORAGE_VOL, __FUNCTION__);
9160
virDispatchError(NULL);
9161
return NULL;
9162
}
9163
9164
conn = vol->conn;
9165
9166
if (conn->storageDriver && conn->storageDriver->volGetPath) {
9167
char *ret;
9168
ret = conn->storageDriver->volGetPath (vol);
9169
if (!ret)
9170
goto error;
9171
return ret;
9172
}
9173
9174
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9175
9176
error:
9177
virDispatchError(vol->conn);
9178
return NULL;
9179
}
9180
9181
9182
/**
9183
* virNodeNumOfDevices:
9184
* @conn: pointer to the hypervisor connection
9185
* @cap: capability name
9186
* @flags: flags (unused, pass 0)
9187
*
9188
* Provides the number of node devices.
9189
*
9190
* If the optional 'cap' argument is non-NULL, then the count
9191
* will be restricted to devices with the specified capability
9192
*
9193
* Returns the number of node devices or -1 in case of error
9194
*/
9195
int
9196
virNodeNumOfDevices(virConnectPtr conn, const char *cap, unsigned int flags)
9197
{
9198
DEBUG("conn=%p, cap=%s, flags=%d", conn, NULLSTR(cap), flags);
9199
9200
virResetLastError();
9201
9202
if (!VIR_IS_CONNECT(conn)) {
9203
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
9204
virDispatchError(NULL);
9205
return -1;
9206
}
9207
if (flags != 0) {
9208
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9209
goto error;
9210
}
9211
9212
if (conn->deviceMonitor && conn->deviceMonitor->numOfDevices) {
9213
int ret;
9214
ret = conn->deviceMonitor->numOfDevices (conn, cap, flags);
9215
if (ret < 0)
9216
goto error;
9217
return ret;
9218
}
9219
9220
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9221
9222
error:
9223
virDispatchError(conn);
9224
return -1;
9225
}
9226
9227
9228
/**
9229
* virNodeListDevices:
9230
* @conn: pointer to the hypervisor connection
9231
* @cap: capability name
9232
* @names: array to collect the list of node device names
9233
* @maxnames: size of @names
9234
* @flags: flags (unused, pass 0)
9235
*
9236
* Collect the list of node devices, and store their names in @names
9237
*
9238
* If the optional 'cap' argument is non-NULL, then the count
9239
* will be restricted to devices with the specified capability
9240
*
9241
* Returns the number of node devices found or -1 in case of error
9242
*/
9243
int
9244
virNodeListDevices(virConnectPtr conn,
9245
const char *cap,
9246
char **const names, int maxnames,
9247
unsigned int flags)
9248
{
9249
DEBUG("conn=%p, cap=%s, names=%p, maxnames=%d, flags=%d",
9250
conn, cap, names, maxnames, flags);
9251
9252
virResetLastError();
9253
9254
if (!VIR_IS_CONNECT(conn)) {
9255
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
9256
virDispatchError(NULL);
9257
return -1;
9258
}
9259
if ((flags != 0) || (names == NULL) || (maxnames < 0)) {
9260
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9261
goto error;
9262
}
9263
9264
if (conn->deviceMonitor && conn->deviceMonitor->listDevices) {
9265
int ret;
9266
ret = conn->deviceMonitor->listDevices (conn, cap, names, maxnames, flags);
9267
if (ret < 0)
9268
goto error;
9269
return ret;
9270
}
9271
9272
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9273
9274
error:
9275
virDispatchError(conn);
9276
return -1;
9277
}
9278
9279
9280
/**
9281
* virNodeDeviceLookupByName:
9282
* @conn: pointer to the hypervisor connection
9283
* @name: unique device name
9284
*
9285
* Lookup a node device by its name.
9286
*
9287
* Returns a virNodeDevicePtr if found, NULL otherwise.
9288
*/
9289
virNodeDevicePtr virNodeDeviceLookupByName(virConnectPtr conn, const char *name)
9290
{
9291
DEBUG("conn=%p, name=%p", conn, name);
9292
9293
virResetLastError();
9294
9295
if (!VIR_IS_CONNECT(conn)) {
9296
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
9297
virDispatchError(NULL);
9298
return NULL;
9299
}
9300
9301
if (name == NULL) {
9302
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9303
goto error;
9304
}
9305
9306
if (conn->deviceMonitor && conn->deviceMonitor->deviceLookupByName) {
9307
virNodeDevicePtr ret;
9308
ret = conn->deviceMonitor->deviceLookupByName (conn, name);
9309
if (!ret)
9310
goto error;
9311
return ret;
9312
}
9313
9314
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9315
9316
error:
9317
virDispatchError(conn);
9318
return NULL;
9319
}
9320
9321
9322
/**
9323
* virNodeDeviceGetXMLDesc:
9324
* @dev: pointer to the node device
9325
* @flags: flags for XML generation (unused, pass 0)
9326
*
9327
* Fetch an XML document describing all aspects of
9328
* the device.
9329
*
9330
* Returns the XML document, or NULL on error
9331
*/
9332
char *virNodeDeviceGetXMLDesc(virNodeDevicePtr dev, unsigned int flags)
9333
{
9334
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
9335
9336
virResetLastError();
9337
9338
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
9339
virLibNodeDeviceError(VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
9340
virDispatchError(NULL);
9341
return NULL;
9342
}
9343
9344
if (dev->conn->deviceMonitor && dev->conn->deviceMonitor->deviceDumpXML) {
9345
char *ret;
9346
ret = dev->conn->deviceMonitor->deviceDumpXML (dev, flags);
9347
if (!ret)
9348
goto error;
9349
return ret;
9350
}
9351
9352
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9353
9354
error:
9355
virDispatchError(dev->conn);
9356
return NULL;
9357
}
9358
9359
9360
/**
9361
* virNodeDeviceGetName:
9362
* @dev: the device
9363
*
9364
* Just return the device name
9365
*
9366
* Returns the device name or NULL in case of error
9367
*/
9368
const char *virNodeDeviceGetName(virNodeDevicePtr dev)
9369
{
9370
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
9371
9372
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
9373
virLibNodeDeviceError(VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
9374
virDispatchError(NULL);
9375
return NULL;
9376
}
9377
9378
return dev->name;
9379
}
9380
9381
/**
9382
* virNodeDeviceGetParent:
9383
* @dev: the device
9384
*
9385
* Accessor for the parent of the device
9386
*
9387
* Returns the name of the device's parent, or NULL if the
9388
* device has no parent.
9389
*/
9390
const char *virNodeDeviceGetParent(virNodeDevicePtr dev)
9391
{
9392
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
9393
9394
virResetLastError();
9395
9396
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
9397
virLibNodeDeviceError(VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
9398
virDispatchError(NULL);
9399
return NULL;
9400
}
9401
9402
if (!dev->parent) {
9403
if (dev->conn->deviceMonitor && dev->conn->deviceMonitor->deviceGetParent) {
9404
dev->parent = dev->conn->deviceMonitor->deviceGetParent (dev);
9405
} else {
9406
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9407
virDispatchError(dev->conn);
9408
return NULL;
9409
}
9410
}
9411
return dev->parent;
9412
}
9413
9414
/**
9415
* virNodeDeviceNumOfCaps:
9416
* @dev: the device
9417
*
9418
* Accessor for the number of capabilities supported by the device.
9419
*
9420
* Returns the number of capabilities supported by the device.
9421
*/
9422
int virNodeDeviceNumOfCaps(virNodeDevicePtr dev)
9423
{
9424
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
9425
9426
virResetLastError();
9427
9428
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
9429
virLibNodeDeviceError(VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
9430
virDispatchError(NULL);
9431
return -1;
9432
}
9433
9434
if (dev->conn->deviceMonitor && dev->conn->deviceMonitor->deviceNumOfCaps) {
9435
int ret;
9436
ret = dev->conn->deviceMonitor->deviceNumOfCaps (dev);
9437
if (ret < 0)
9438
goto error;
9439
return ret;
9440
}
9441
9442
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9443
9444
error:
9445
virDispatchError(dev->conn);
9446
return -1;
9447
}
9448
9449
/**
9450
* virNodeDeviceListCaps:
9451
* @dev: the device
9452
* @names: array to collect the list of capability names
9453
* @maxnames: size of @names
9454
*
9455
* Lists the names of the capabilities supported by the device.
9456
*
9457
* Returns the number of capability names listed in @names.
9458
*/
9459
int virNodeDeviceListCaps(virNodeDevicePtr dev,
9460
char **const names,
9461
int maxnames)
9462
{
9463
DEBUG("dev=%p, conn=%p, names=%p, maxnames=%d",
9464
dev, dev ? dev->conn : NULL, names, maxnames);
9465
9466
virResetLastError();
9467
9468
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
9469
virLibNodeDeviceError(VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
9470
virDispatchError(NULL);
9471
return -1;
9472
}
9473
9474
if (dev->conn->deviceMonitor && dev->conn->deviceMonitor->deviceListCaps) {
9475
int ret;
9476
ret = dev->conn->deviceMonitor->deviceListCaps (dev, names, maxnames);
9477
if (ret < 0)
9478
goto error;
9479
return ret;
9480
}
9481
9482
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9483
9484
error:
9485
virDispatchError(dev->conn);
9486
return -1;
9487
}
9488
9489
9490
/**
9491
* virNodeDeviceFree:
9492
* @dev: pointer to the node device
9493
*
9494
* Drops a reference to the node device, freeing it if
9495
* this was the last reference.
9496
*
9497
* Returns the 0 for success, -1 for error.
9498
*/
9499
int virNodeDeviceFree(virNodeDevicePtr dev)
9500
{
9501
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
9502
9503
virResetLastError();
9504
9505
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
9506
virLibNodeDeviceError(VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
9507
virDispatchError(NULL);
9508
return -1;
9509
}
9510
if (virUnrefNodeDevice(dev) < 0) {
9511
virDispatchError(NULL);
9512
return -1;
9513
}
9514
return 0;
9515
}
9516
9517
9518
/**
9519
* virNodeDeviceRef:
9520
* @dev: the dev to hold a reference on
9521
*
9522
* Increment the reference count on the dev. For each
9523
* additional call to this method, there shall be a corresponding
9524
* call to virNodeDeviceFree to release the reference count, once
9525
* the caller no longer needs the reference to this object.
9526
*
9527
* This method is typically useful for applications where multiple
9528
* threads are using a connection, and it is required that the
9529
* connection remain open until all threads have finished using
9530
* it. ie, each new thread using a dev would increment
9531
* the reference count.
9532
*
9533
* Returns 0 in case of success, -1 in case of failure.
9534
*/
9535
int
9536
virNodeDeviceRef(virNodeDevicePtr dev)
9537
{
9538
if ((!VIR_IS_CONNECTED_NODE_DEVICE(dev))) {
9539
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9540
virDispatchError(NULL);
9541
return -1;
9542
}
9543
virMutexLock(&dev->conn->lock);
9544
DEBUG("dev=%p refs=%d", dev, dev->refs);
9545
dev->refs++;
9546
virMutexUnlock(&dev->conn->lock);
9547
return 0;
9548
}
9549
9550
/**
9551
* virNodeDeviceDettach:
9552
* @dev: pointer to the node device
9553
*
9554
* Dettach the node device from the node itself so that it may be
9555
* assigned to a guest domain.
9556
*
9557
* Depending on the hypervisor, this may involve operations such
9558
* as unbinding any device drivers from the device, binding the
9559
* device to a dummy device driver and resetting the device.
9560
*
9561
* If the device is currently in use by the node, this method may
9562
* fail.
9563
*
9564
* Once the device is not assigned to any guest, it may be re-attached
9565
* to the node using the virNodeDeviceReattach() method.
9566
*
9567
* Returns 0 in case of success, -1 in case of failure.
9568
*/
9569
int
9570
virNodeDeviceDettach(virNodeDevicePtr dev)
9571
{
9572
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
9573
9574
virResetLastError();
9575
9576
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
9577
virLibNodeDeviceError(VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
9578
virDispatchError(NULL);
9579
return -1;
9580
}
9581
9582
if (dev->conn->driver->nodeDeviceDettach) {
9583
int ret;
9584
ret = dev->conn->driver->nodeDeviceDettach (dev);
9585
if (ret < 0)
9586
goto error;
9587
return ret;
9588
}
9589
9590
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9591
9592
error:
9593
virDispatchError(dev->conn);
9594
return -1;
9595
}
9596
9597
/**
9598
* virNodeDeviceReAttach:
9599
* @dev: pointer to the node device
9600
*
9601
* Re-attach a previously dettached node device to the node so that it
9602
* may be used by the node again.
9603
*
9604
* Depending on the hypervisor, this may involve operations such
9605
* as resetting the device, unbinding it from a dummy device driver
9606
* and binding it to its appropriate driver.
9607
*
9608
* If the device is currently in use by a guest, this method may fail.
9609
*
9610
* Returns 0 in case of success, -1 in case of failure.
9611
*/
9612
int
9613
virNodeDeviceReAttach(virNodeDevicePtr dev)
9614
{
9615
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
9616
9617
virResetLastError();
9618
9619
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
9620
virLibNodeDeviceError(VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
9621
virDispatchError(NULL);
9622
return -1;
9623
}
9624
9625
if (dev->conn->driver->nodeDeviceReAttach) {
9626
int ret;
9627
ret = dev->conn->driver->nodeDeviceReAttach (dev);
9628
if (ret < 0)
9629
goto error;
9630
return ret;
9631
}
9632
9633
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9634
9635
error:
9636
virDispatchError(dev->conn);
9637
return -1;
9638
}
9639
9640
/**
9641
* virNodeDeviceReset:
9642
* @dev: pointer to the node device
9643
*
9644
* Reset a previously dettached node device to the node before or
9645
* after assigning it to a guest.
9646
*
9647
* The exact reset semantics depends on the hypervisor and device
9648
* type but, for example, KVM will attempt to reset PCI devices with
9649
* a Function Level Reset, Secondary Bus Reset or a Power Management
9650
* D-State reset.
9651
*
9652
* If the reset will affect other devices which are currently in use,
9653
* this function may fail.
9654
*
9655
* Returns 0 in case of success, -1 in case of failure.
9656
*/
9657
int
9658
virNodeDeviceReset(virNodeDevicePtr dev)
9659
{
9660
DEBUG("dev=%p, conn=%p", dev, dev ? dev->conn : NULL);
9661
9662
virResetLastError();
9663
9664
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
9665
virLibNodeDeviceError(VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
9666
virDispatchError(NULL);
9667
return -1;
9668
}
9669
9670
if (dev->conn->driver->nodeDeviceReset) {
9671
int ret;
9672
ret = dev->conn->driver->nodeDeviceReset (dev);
9673
if (ret < 0)
9674
goto error;
9675
return ret;
9676
}
9677
9678
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9679
9680
error:
9681
virDispatchError(dev->conn);
9682
return -1;
9683
}
9684
9685
9686
/**
9687
* virNodeDeviceCreateXML:
9688
* @conn: pointer to the hypervisor connection
9689
* @xmlDesc: string containing an XML description of the device to be created
9690
* @flags: callers should always pass 0
9691
*
9692
* Create a new device on the VM host machine, for example, virtual
9693
* HBAs created using vport_create.
9694
*
9695
* Returns a node device object if successful, NULL in case of failure
9696
*/
9697
virNodeDevicePtr
9698
virNodeDeviceCreateXML(virConnectPtr conn,
9699
const char *xmlDesc,
9700
unsigned int flags)
9701
{
9702
VIR_DEBUG("conn=%p, xmlDesc=%s, flags=%d", conn, xmlDesc, flags);
9703
9704
virResetLastError();
9705
9706
if (!VIR_IS_CONNECT(conn)) {
9707
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
9708
virDispatchError(NULL);
9709
return NULL;
9710
}
9711
9712
if (conn->flags & VIR_CONNECT_RO) {
9713
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
9714
goto error;
9715
}
9716
9717
if (xmlDesc == NULL) {
9718
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9719
goto error;
9720
}
9721
9722
if (conn->deviceMonitor &&
9723
conn->deviceMonitor->deviceCreateXML) {
9724
virNodeDevicePtr dev = conn->deviceMonitor->deviceCreateXML(conn, xmlDesc, flags);
9725
if (dev == NULL)
9726
goto error;
9727
return dev;
9728
}
9729
9730
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9731
9732
error:
9733
virDispatchError(conn);
9734
return NULL;
9735
}
9736
9737
9738
/**
9739
* virNodeDeviceDestroy:
9740
* @dev: a device object
9741
*
9742
* Destroy the device object. The virtual device is removed from the host operating system.
9743
* This function may require privileged access
9744
*
9745
* Returns 0 in case of success and -1 in case of failure.
9746
*/
9747
int
9748
virNodeDeviceDestroy(virNodeDevicePtr dev)
9749
{
9750
DEBUG("dev=%p", dev);
9751
9752
virResetLastError();
9753
9754
if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) {
9755
virLibNodeDeviceError(VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__);
9756
virDispatchError(NULL);
9757
return -1;
9758
}
9759
9760
if (dev->conn->flags & VIR_CONNECT_RO) {
9761
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
9762
goto error;
9763
}
9764
9765
if (dev->conn->deviceMonitor &&
9766
dev->conn->deviceMonitor->deviceDestroy) {
9767
int retval = dev->conn->deviceMonitor->deviceDestroy(dev);
9768
if (retval < 0) {
9769
goto error;
9770
}
9771
9772
return 0;
9773
}
9774
9775
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9776
9777
error:
9778
virDispatchError(dev->conn);
9779
return -1;
9780
}
9781
9782
9783
/*
9784
* Domain Event Notification
9785
*/
9786
9787
/**
9788
* virConnectDomainEventRegister:
9789
* @conn: pointer to the connection
9790
* @cb: callback to the function handling domain events
9791
* @opaque: opaque data to pass on to the callback
9792
* @freecb: optional function to deallocate opaque when not used anymore
9793
*
9794
* Adds a callback to receive notifications of domain lifecycle events
9795
* occurring on a connection
9796
*
9797
* Use of this method is no longer recommended. Instead applications
9798
* should try virConnectDomainEventRegisterAny which has a more flexible
9799
* API contract
9800
*
9801
* The virDomainPtr object handle passed into the callback upon delivery
9802
* of an event is only valid for the duration of execution of the callback.
9803
* If the callback wishes to keep the domain object after the callback
9804
* returns, it shall take a reference to it, by calling virDomainRef.
9805
* The reference can be released once the object is no longer required
9806
* by calling virDomainFree.
9807
*
9808
* Returns 0 on success, -1 on failure
9809
*/
9810
int
9811
virConnectDomainEventRegister(virConnectPtr conn,
9812
virConnectDomainEventCallback cb,
9813
void *opaque,
9814
virFreeCallback freecb)
9815
{
9816
DEBUG("conn=%p, cb=%p, opaque=%p, freecb=%p", conn, cb, opaque, freecb);
9817
virResetLastError();
9818
9819
if (!VIR_IS_CONNECT(conn)) {
9820
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
9821
virDispatchError(NULL);
9822
return -1;
9823
}
9824
if (cb == NULL) {
9825
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9826
goto error;
9827
}
9828
9829
if ((conn->driver) && (conn->driver->domainEventRegister)) {
9830
int ret;
9831
ret = conn->driver->domainEventRegister (conn, cb, opaque, freecb);
9832
if (ret < 0)
9833
goto error;
9834
return ret;
9835
}
9836
9837
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9838
error:
9839
virDispatchError(conn);
9840
return -1;
9841
}
9842
9843
/**
9844
* virConnectDomainEventDeregister:
9845
* @conn: pointer to the connection
9846
* @cb: callback to the function handling domain events
9847
*
9848
* Removes a callback previously registered with the virConnectDomainEventRegister
9849
* funtion.
9850
*
9851
* Use of this method is no longer recommended. Instead applications
9852
* should try virConnectDomainEventUnregisterAny which has a more flexible
9853
* API contract
9854
*
9855
* Returns 0 on success, -1 on failure
9856
*/
9857
int
9858
virConnectDomainEventDeregister(virConnectPtr conn,
9859
virConnectDomainEventCallback cb)
9860
{
9861
DEBUG("conn=%p, cb=%p", conn, cb);
9862
9863
virResetLastError();
9864
9865
if (!VIR_IS_CONNECT(conn)) {
9866
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
9867
virDispatchError(NULL);
9868
return -1;
9869
}
9870
if (cb == NULL) {
9871
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9872
goto error;
9873
}
9874
if ((conn->driver) && (conn->driver->domainEventDeregister)) {
9875
int ret;
9876
ret = conn->driver->domainEventDeregister (conn, cb);
9877
if (ret < 0)
9878
goto error;
9879
return ret;
9880
}
9881
9882
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9883
error:
9884
virDispatchError(conn);
9885
return -1;
9886
}
9887
9888
/**
9889
* virSecretGetConnect:
9890
* @secret: A virSecret secret
9891
*
9892
* Provides the connection pointer associated with a secret. The reference
9893
* counter on the connection is not increased by this call.
9894
*
9895
* WARNING: When writing libvirt bindings in other languages, do not use this
9896
* function. Instead, store the connection and the secret object together.
9897
*
9898
* Returns the virConnectPtr or NULL in case of failure.
9899
*/
9900
virConnectPtr
9901
virSecretGetConnect (virSecretPtr secret)
9902
{
9903
DEBUG("secret=%p", secret);
9904
9905
virResetLastError();
9906
9907
if (!VIR_IS_CONNECTED_SECRET (secret)) {
9908
virLibSecretError(VIR_ERR_INVALID_SECRET, __FUNCTION__);
9909
virDispatchError(NULL);
9910
return NULL;
9911
}
9912
return secret->conn;
9913
}
9914
9915
/**
9916
* virConnectNumOfSecrets:
9917
* @conn: virConnect connection
9918
*
9919
* Fetch number of currently defined secrets.
9920
*
9921
* Returns the number currently defined secrets.
9922
*/
9923
int
9924
virConnectNumOfSecrets(virConnectPtr conn)
9925
{
9926
VIR_DEBUG("conn=%p", conn);
9927
9928
virResetLastError();
9929
9930
if (!VIR_IS_CONNECT(conn)) {
9931
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
9932
virDispatchError(NULL);
9933
return -1;
9934
}
9935
9936
if (conn->secretDriver != NULL &&
9937
conn->secretDriver->numOfSecrets != NULL) {
9938
int ret;
9939
9940
ret = conn->secretDriver->numOfSecrets(conn);
9941
if (ret < 0)
9942
goto error;
9943
return ret;
9944
}
9945
9946
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9947
9948
error:
9949
virDispatchError(conn);
9950
return -1;
9951
}
9952
9953
/**
9954
* virConnectListSecrets:
9955
* @conn: virConnect connection
9956
* @uuids: Pointer to an array to store the UUIDs
9957
* @maxuuids: size of the array.
9958
*
9959
* List UUIDs of defined secrets, store pointers to names in uuids.
9960
*
9961
* Returns the number of UUIDs provided in the array, or -1 on failure.
9962
*/
9963
int
9964
virConnectListSecrets(virConnectPtr conn, char **uuids, int maxuuids)
9965
{
9966
VIR_DEBUG("conn=%p, uuids=%p, maxuuids=%d", conn, uuids, maxuuids);
9967
9968
virResetLastError();
9969
9970
if (!VIR_IS_CONNECT(conn)) {
9971
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
9972
virDispatchError(NULL);
9973
return -1;
9974
}
9975
if (uuids == NULL || maxuuids < 0) {
9976
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
9977
goto error;
9978
}
9979
9980
if (conn->secretDriver != NULL && conn->secretDriver->listSecrets != NULL) {
9981
int ret;
9982
9983
ret = conn->secretDriver->listSecrets(conn, uuids, maxuuids);
9984
if (ret < 0)
9985
goto error;
9986
return ret;
9987
}
9988
9989
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
9990
9991
error:
9992
virDispatchError(conn);
9993
return -1;
9994
}
9995
9996
/**
9997
* virSecretLookupByUUID:
9998
* @conn: pointer to the hypervisor connection
9999
* @uuid: the raw UUID for the secret
10000
*
10001
* Try to lookup a secret on the given hypervisor based on its UUID.
10002
* Uses the 16 bytes of raw data to describe the UUID
10003
*
10004
* Returns a new secret object or NULL in case of failure. If the
10005
* secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
10006
*/
10007
virSecretPtr
10008
virSecretLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
10009
{
10010
DEBUG("conn=%p, uuid=%s", conn, uuid);
10011
10012
virResetLastError();
10013
10014
if (!VIR_IS_CONNECT(conn)) {
10015
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
10016
virDispatchError(NULL);
10017
return NULL;
10018
}
10019
if (uuid == NULL) {
10020
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
10021
goto error;
10022
}
10023
10024
if (conn->secretDriver &&
10025
conn->secretDriver->lookupByUUID) {
10026
virSecretPtr ret;
10027
ret = conn->secretDriver->lookupByUUID (conn, uuid);
10028
if (!ret)
10029
goto error;
10030
return ret;
10031
}
10032
10033
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
10034
10035
error:
10036
virDispatchError(conn);
10037
return NULL;
10038
}
10039
10040
/**
10041
* virSecretLookupByUUIDString:
10042
* @conn: pointer to the hypervisor connection
10043
* @uuidstr: the string UUID for the secret
10044
*
10045
* Try to lookup a secret on the given hypervisor based on its UUID.
10046
* Uses the printable string value to describe the UUID
10047
*
10048
* Returns a new secret object or NULL in case of failure. If the
10049
* secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
10050
*/
10051
virSecretPtr
10052
virSecretLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
10053
{
10054
unsigned char uuid[VIR_UUID_BUFLEN];
10055
DEBUG("conn=%p, uuidstr=%s", conn, uuidstr);
10056
10057
virResetLastError();
10058
10059
if (!VIR_IS_CONNECT(conn)) {
10060
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
10061
virDispatchError(NULL);
10062
return NULL;
10063
}
10064
if (uuidstr == NULL) {
10065
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
10066
goto error;
10067
}
10068
10069
if (virUUIDParse(uuidstr, uuid) < 0) {
10070
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
10071
goto error;
10072
}
10073
10074
return virSecretLookupByUUID(conn, &uuid[0]);
10075
10076
error:
10077
virDispatchError(conn);
10078
return NULL;
10079
}
10080
10081
10082
/**
10083
* virSecretLookupByUsage:
10084
* @conn: pointer to the hypervisor connection
10085
* @usageType: the type of secret usage
10086
* @usageID: identifier of the object using the secret
10087
*
10088
* Try to lookup a secret on the given hypervisor based on its usage
10089
* The usageID is unique within the set of secrets sharing the
10090
* same usageType value.
10091
*
10092
* Returns a new secret object or NULL in case of failure. If the
10093
* secret cannot be found, then VIR_ERR_NO_SECRET error is raised.
10094
*/
10095
virSecretPtr
10096
virSecretLookupByUsage(virConnectPtr conn,
10097
int usageType,
10098
const char *usageID)
10099
{
10100
DEBUG("conn=%p, usageType=%d usageID=%s", conn, usageType, NULLSTR(usageID));
10101
10102
virResetLastError();
10103
10104
if (!VIR_IS_CONNECT(conn)) {
10105
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
10106
virDispatchError(NULL);
10107
return NULL;
10108
}
10109
if (usageID == NULL) {
10110
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
10111
goto error;
10112
}
10113
10114
if (conn->secretDriver &&
10115
conn->secretDriver->lookupByUsage) {
10116
virSecretPtr ret;
10117
ret = conn->secretDriver->lookupByUsage (conn, usageType, usageID);
10118
if (!ret)
10119
goto error;
10120
return ret;
10121
}
10122
10123
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
10124
10125
error:
10126
virDispatchError(conn);
10127
return NULL;
10128
}
10129
10130
10131
/**
10132
* virSecretDefineXML:
10133
* @conn: virConnect connection
10134
* @xml: XML describing the secret.
10135
* @flags: flags, use 0 for now
10136
*
10137
* If XML specifies a UUID, locates the specified secret and replaces all
10138
* attributes of the secret specified by UUID by attributes specified in xml
10139
* (any attributes not specified in xml are discarded).
10140
*
10141
* Otherwise, creates a new secret with an automatically chosen UUID, and
10142
* initializes its attributes from xml.
10143
*
10144
* Returns a the secret on success, NULL on failure.
10145
*/
10146
virSecretPtr
10147
virSecretDefineXML(virConnectPtr conn, const char *xml, unsigned int flags)
10148
{
10149
VIR_DEBUG("conn=%p, xml=%s, flags=%u", conn, xml, flags);
10150
10151
virResetLastError();
10152
10153
if (!VIR_IS_CONNECT(conn)) {
10154
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
10155
virDispatchError(NULL);
10156
return NULL;
10157
}
10158
if (conn->flags & VIR_CONNECT_RO) {
10159
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
10160
goto error;
10161
}
10162
if (xml == NULL) {
10163
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
10164
goto error;
10165
}
10166
10167
if (conn->secretDriver != NULL && conn->secretDriver->defineXML != NULL) {
10168
virSecretPtr ret;
10169
10170
ret = conn->secretDriver->defineXML(conn, xml, flags);
10171
if (ret == NULL)
10172
goto error;
10173
return ret;
10174
}
10175
10176
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
10177
10178
error:
10179
virDispatchError(conn);
10180
return NULL;
10181
}
10182
10183
/**
10184
* virSecretGetUUID:
10185
* @secret: A virSecret secret
10186
* @uuid: buffer of VIR_UUID_BUFLEN bytes in size
10187
*
10188
* Fetches the UUID of the secret.
10189
*
10190
* Returns 0 on success with the uuid buffer being filled, or
10191
* -1 upon failure.
10192
*/
10193
int
10194
virSecretGetUUID(virSecretPtr secret, unsigned char *uuid)
10195
{
10196
VIR_DEBUG("secret=%p", secret);
10197
10198
virResetLastError();
10199
10200
if (!VIR_IS_CONNECTED_SECRET(secret)) {
10201
virLibSecretError(VIR_ERR_INVALID_SECRET, __FUNCTION__);
10202
virDispatchError(NULL);
10203
return -1;
10204
}
10205
if (uuid == NULL) {
10206
virLibSecretError(VIR_ERR_INVALID_ARG, __FUNCTION__);
10207
virDispatchError(secret->conn);
10208
return -1;
10209
}
10210
10211
memcpy(uuid, &secret->uuid[0], VIR_UUID_BUFLEN);
10212
10213
return 0;
10214
}
10215
10216
/**
10217
* virSecretGetUUIDString:
10218
* @secret: a secret object
10219
* @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
10220
*
10221
* Get the UUID for a secret as string. For more information about
10222
* UUID see RFC4122.
10223
*
10224
* Returns -1 in case of error, 0 in case of success
10225
*/
10226
int
10227
virSecretGetUUIDString(virSecretPtr secret, char *buf)
10228
{
10229
unsigned char uuid[VIR_UUID_BUFLEN];
10230
DEBUG("secret=%p, buf=%p", secret, buf);
10231
10232
virResetLastError();
10233
10234
if (!VIR_IS_SECRET(secret)) {
10235
virLibSecretError(VIR_ERR_INVALID_SECRET, __FUNCTION__);
10236
virDispatchError(NULL);
10237
return -1;
10238
}
10239
if (buf == NULL) {
10240
virLibSecretError(VIR_ERR_INVALID_ARG, __FUNCTION__);
10241
goto error;
10242
}
10243
10244
if (virSecretGetUUID(secret, &uuid[0]))
10245
goto error;
10246
10247
virUUIDFormat(uuid, buf);
10248
return 0;
10249
10250
error:
10251
virDispatchError(secret->conn);
10252
return -1;
10253
}
10254
10255
/**
10256
* virSecretGetUsageType:
10257
* @secret: a secret object
10258
*
10259
* Get the type of object which uses this secret. The returned
10260
* value is one of the constants defined in the virSecretUsageType
10261
* enumeration. More values may be added to this enumeration in
10262
* the future, so callers should expect to see usage types they
10263
* do not explicitly know about.
10264
*
10265
* Returns a positive integer identifying the type of object,
10266
* or -1 upon error.
10267
*/
10268
int
10269
virSecretGetUsageType(virSecretPtr secret)
10270
{
10271
DEBUG("secret=%p", secret);
10272
10273
virResetLastError();
10274
10275
if (!VIR_IS_SECRET(secret)) {
10276
virLibSecretError(VIR_ERR_INVALID_SECRET, __FUNCTION__);
10277
virDispatchError(NULL);
10278
return -1;
10279
}
10280
return secret->usageType;
10281
}
10282
10283
/**
10284
* virSecretGetUsageID:
10285
* @secret: a secret object
10286
*
10287
* Get the unique identifier of the object with which this
10288
* secret is to be used. The format of the identifier is
10289
* dependant on the usage type of the secret. For a secret
10290
* with a usage type of VIR_SECRET_USAGE_TYPE_VOLUME the
10291
* identifier will be a fully qualfied path name. The
10292
* identifiers are intended to be unique within the set of
10293
* all secrets sharing the same usage type. ie, there shall
10294
* only ever be one secret for each volume path.
10295
*
10296
* Returns a string identifying the object using the secret,
10297
* or NULL upon error
10298
*/
10299
const char *
10300
virSecretGetUsageID(virSecretPtr secret)
10301
{
10302
DEBUG("secret=%p", secret);
10303
10304
virResetLastError();
10305
10306
if (!VIR_IS_SECRET(secret)) {
10307
virLibSecretError(VIR_ERR_INVALID_SECRET, __FUNCTION__);
10308
virDispatchError(NULL);
10309
return NULL;
10310
}
10311
return secret->usageID;
10312
}
10313
10314
10315
/**
10316
* virSecretGetXMLDesc:
10317
* @secret: A virSecret secret
10318
* @flags: flags, use 0 for now
10319
*
10320
* Fetches an XML document describing attributes of the secret.
10321
*
10322
* Returns the XML document on success, NULL on failure. The caller must
10323
* free() the XML.
10324
*/
10325
char *
10326
virSecretGetXMLDesc(virSecretPtr secret, unsigned int flags)
10327
{
10328
virConnectPtr conn;
10329
10330
VIR_DEBUG("secret=%p, flags=%u", secret, flags);
10331
10332
virResetLastError();
10333
10334
if (!VIR_IS_CONNECTED_SECRET(secret)) {
10335
virLibSecretError(VIR_ERR_INVALID_SECRET, __FUNCTION__);
10336
virDispatchError(NULL);
10337
return NULL;
10338
}
10339
10340
conn = secret->conn;
10341
if (conn->secretDriver != NULL && conn->secretDriver->getXMLDesc != NULL) {
10342
char *ret;
10343
10344
ret = conn->secretDriver->getXMLDesc(secret, flags);
10345
if (ret == NULL)
10346
goto error;
10347
return ret;
10348
}
10349
10350
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
10351
10352
error:
10353
virDispatchError(conn);
10354
return NULL;
10355
}
10356
10357
/**
10358
* virSecretSetValue:
10359
* @secret: A virSecret secret
10360
* @value: Value of the secret
10361
* @value_size: Size of the value
10362
* @flags: flags, use 0 for now
10363
*
10364
* Sets the value of a secret.
10365
*
10366
* Returns 0 on success, -1 on failure.
10367
*/
10368
int
10369
virSecretSetValue(virSecretPtr secret, const unsigned char *value,
10370
size_t value_size, unsigned int flags)
10371
{
10372
virConnectPtr conn;
10373
10374
VIR_DEBUG("secret=%p, value=%p, value_size=%zu, flags=%u", secret, value,
10375
value_size, flags);
10376
10377
virResetLastError();
10378
10379
if (!VIR_IS_CONNECTED_SECRET(secret)) {
10380
virLibSecretError(VIR_ERR_INVALID_SECRET, __FUNCTION__);
10381
virDispatchError(NULL);
10382
return -1;
10383
}
10384
conn = secret->conn;
10385
if (conn->flags & VIR_CONNECT_RO) {
10386
virLibSecretError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
10387
goto error;
10388
}
10389
if (value == NULL) {
10390
virLibSecretError(VIR_ERR_INVALID_ARG, __FUNCTION__);
10391
goto error;
10392
}
10393
10394
if (conn->secretDriver != NULL && conn->secretDriver->setValue != NULL) {
10395
int ret;
10396
10397
ret = conn->secretDriver->setValue(secret, value, value_size, flags);
10398
if (ret < 0)
10399
goto error;
10400
return ret;
10401
}
10402
10403
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
10404
10405
error:
10406
virDispatchError(conn);
10407
return -1;
10408
}
10409
10410
/**
10411
* virSecretGetValue:
10412
* @secret: A virSecret connection
10413
* @value_size: Place for storing size of the secret value
10414
* @flags: flags, use 0 for now
10415
*
10416
* Fetches the value of a secret.
10417
*
10418
* Returns the secret value on success, NULL on failure. The caller must
10419
* free() the secret value.
10420
*/
10421
unsigned char *
10422
virSecretGetValue(virSecretPtr secret, size_t *value_size, unsigned int flags)
10423
{
10424
virConnectPtr conn;
10425
10426
VIR_DEBUG("secret=%p, value_size=%p, flags=%u", secret, value_size, flags);
10427
10428
virResetLastError();
10429
10430
if (!VIR_IS_CONNECTED_SECRET(secret)) {
10431
virLibSecretError(VIR_ERR_INVALID_SECRET, __FUNCTION__);
10432
virDispatchError(NULL);
10433
return NULL;
10434
}
10435
conn = secret->conn;
10436
if (conn->flags & VIR_CONNECT_RO) {
10437
virLibSecretError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
10438
goto error;
10439
}
10440
if (value_size == NULL) {
10441
virLibSecretError(VIR_ERR_INVALID_ARG, __FUNCTION__);
10442
goto error;
10443
}
10444
10445
flags &= VIR_SECRET_GET_VALUE_FLAGS_MASK;
10446
10447
if (conn->secretDriver != NULL && conn->secretDriver->getValue != NULL) {
10448
unsigned char *ret;
10449
10450
ret = conn->secretDriver->getValue(secret, value_size, flags);
10451
if (ret == NULL)
10452
goto error;
10453
return ret;
10454
}
10455
10456
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
10457
10458
error:
10459
virDispatchError(conn);
10460
return NULL;
10461
}
10462
10463
/**
10464
* virSecretUndefine:
10465
* @secret: A virSecret secret
10466
*
10467
* Deletes the specified secret. This does not free the associated
10468
* virSecretPtr object.
10469
*
10470
* Returns 0 on success, -1 on failure.
10471
*/
10472
int
10473
virSecretUndefine(virSecretPtr secret)
10474
{
10475
virConnectPtr conn;
10476
10477
VIR_DEBUG("secret=%p", secret);
10478
10479
virResetLastError();
10480
10481
if (!VIR_IS_CONNECTED_SECRET(secret)) {
10482
virLibSecretError(VIR_ERR_INVALID_SECRET, __FUNCTION__);
10483
virDispatchError(NULL);
10484
return -1;
10485
}
10486
conn = secret->conn;
10487
if (conn->flags & VIR_CONNECT_RO) {
10488
virLibSecretError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
10489
goto error;
10490
}
10491
10492
if (conn->secretDriver != NULL && conn->secretDriver->undefine != NULL) {
10493
int ret;
10494
10495
ret = conn->secretDriver->undefine(secret);
10496
if (ret < 0)
10497
goto error;
10498
return ret;
10499
}
10500
10501
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
10502
10503
error:
10504
virDispatchError(conn);
10505
return -1;
10506
}
10507
10508
/**
10509
* virSecretRef:
10510
* @secret: the secret to hold a reference on
10511
*
10512
* Increment the reference count on the secret. For each additional call to
10513
* this method, there shall be a corresponding call to virSecretFree to release
10514
* the reference count, once the caller no longer needs the reference to this
10515
* object.
10516
*
10517
* This method is typically useful for applications where multiple threads are
10518
* using a connection, and it is required that the connection remain open until
10519
* all threads have finished using it. ie, each new thread using a secret would
10520
* increment the reference count.
10521
*
10522
* Returns 0 in case of success, -1 in case of failure.
10523
*/
10524
int
10525
virSecretRef(virSecretPtr secret)
10526
{
10527
if (!VIR_IS_CONNECTED_SECRET(secret)) {
10528
virLibSecretError(VIR_ERR_INVALID_SECRET, __FUNCTION__);
10529
virDispatchError(NULL);
10530
return -1;
10531
}
10532
virMutexLock(&secret->conn->lock);
10533
DEBUG("secret=%p refs=%d", secret, secret->refs);
10534
secret->refs++;
10535
virMutexUnlock(&secret->conn->lock);
10536
return 0;
10537
}
10538
10539
/**
10540
* virSecretFree:
10541
* @secret: pointer to a secret
10542
*
10543
* Release the secret handle. The underlying secret continues to exist.
10544
*
10545
* Returns 0 on success, or -1 on error
10546
*/
10547
int
10548
virSecretFree(virSecretPtr secret)
10549
{
10550
DEBUG("secret=%p", secret);
10551
10552
virResetLastError();
10553
10554
if (!VIR_IS_CONNECTED_SECRET(secret)) {
10555
virLibSecretError(VIR_ERR_INVALID_SECRET, __FUNCTION__);
10556
virDispatchError(NULL);
10557
return -1;
10558
}
10559
if (virUnrefSecret(secret) < 0) {
10560
virDispatchError(NULL);
10561
return -1;
10562
}
10563
return 0;
10564
}
10565
10566
10567
/**
10568
* virStreamNew:
10569
* @conn: pointer to the connection
10570
* @flags: control features of the stream
10571
*
10572
* Creates a new stream object which can be used to perform
10573
* streamed I/O with other public API function.
10574
*
10575
* When no longer needed, a stream object must be released
10576
* with virStreamFree. If a data stream has been used,
10577
* then the application must call virStreamFinish or
10578
* virStreamAbort before free'ing to, in order to notify
10579
* the driver of termination.
10580
*
10581
* If a non-blocking data stream is required passed
10582
* VIR_STREAM_NONBLOCK for flags, otherwise pass 0.
10583
*
10584
* Returns the new stream, or NULL upon error
10585
*/
10586
virStreamPtr
10587
virStreamNew(virConnectPtr conn,
10588
unsigned int flags)
10589
{
10590
virStreamPtr st;
10591
10592
DEBUG("conn=%p, flags=%u", conn, flags);
10593
10594
virResetLastError();
10595
10596
if (!VIR_IS_CONNECT(conn)) {
10597
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
10598
virDispatchError(NULL);
10599
return NULL;
10600
}
10601
10602
st = virGetStream(conn);
10603
if (st)
10604
st->flags = flags;
10605
10606
return st;
10607
}
10608
10609
10610
/**
10611
* virStreamRef:
10612
* @stream: pointer to the stream
10613
*
10614
* Increment the reference count on the stream. For each
10615
* additional call to this method, there shall be a corresponding
10616
* call to virStreamFree to release the reference count, once
10617
* the caller no longer needs the reference to this object.
10618
*
10619
* Returns 0 in case of success, -1 in case of failure
10620
*/
10621
int
10622
virStreamRef(virStreamPtr stream)
10623
{
10624
if ((!VIR_IS_CONNECTED_STREAM(stream))) {
10625
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
10626
virDispatchError(NULL);
10627
return -1;
10628
}
10629
virMutexLock(&stream->conn->lock);
10630
DEBUG("stream=%p refs=%d", stream, stream->refs);
10631
stream->refs++;
10632
virMutexUnlock(&stream->conn->lock);
10633
return 0;
10634
}
10635
10636
10637
/**
10638
* virStreamSend:
10639
* @stream: pointer to the stream object
10640
* @data: buffer to write to stream
10641
* @nbytes: size of @data buffer
10642
*
10643
* Write a series of bytes to the stream. This method may
10644
* block the calling application for an arbitrary amount
10645
* of time. Once an application has finished sending data
10646
* it should call virStreamFinish to wait for successful
10647
* confirmation from the driver, or detect any error
10648
*
10649
* This method may not be used if a stream source has been
10650
* registered
10651
*
10652
* Errors are not guaranteed to be reported synchronously
10653
* with the call, but may instead be delayed until a
10654
* subsequent call.
10655
*
10656
* An example using this with a hypothetical file upload
10657
* API looks like
10658
*
10659
* virStreamPtr st = virStreamNew(conn, 0);
10660
* int fd = open("demo.iso", O_RDONLY)
10661
*
10662
* virConnectUploadFile(conn, "demo.iso", st);
10663
*
10664
* while (1) {
10665
* char buf[1024];
10666
* int got = read(fd, buf, 1024);
10667
* if (got < 0) {
10668
* virStreamAbort(st);
10669
* break;
10670
* }
10671
* if (got == 0) {
10672
* virStreamFinish(st);
10673
* break;
10674
* }
10675
* int offset = 0;
10676
* while (offset < got) {
10677
* int sent = virStreamSend(st, buf+offset, got-offset)
10678
* if (sent < 0) {
10679
* virStreamAbort(st);
10680
* goto done;
10681
* }
10682
* offset += sent;
10683
* }
10684
* }
10685
* if (virStreamFinish(st) < 0)
10686
* ... report an error ....
10687
* done:
10688
* virStreamFree(st);
10689
* close(fd);
10690
*
10691
* Returns the number of bytes written, which may be less
10692
* than requested.
10693
*
10694
* Returns -1 upon error, at which time the stream will
10695
* be marked as aborted, and the caller should now release
10696
* the stream with virStreamFree.
10697
*
10698
* Returns -2 if the outgoing transmit buffers are full &
10699
* the stream is marked as non-blocking.
10700
*/
10701
int virStreamSend(virStreamPtr stream,
10702
const char *data,
10703
size_t nbytes)
10704
{
10705
DEBUG("stream=%p, data=%p, nbytes=%zi", stream, data, nbytes);
10706
10707
virResetLastError();
10708
10709
if (!VIR_IS_CONNECTED_STREAM(stream)) {
10710
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
10711
virDispatchError(NULL);
10712
return -1;
10713
}
10714
10715
if (stream->driver &&
10716
stream->driver->streamSend) {
10717
int ret;
10718
ret = (stream->driver->streamSend)(stream, data, nbytes);
10719
if (ret == -2)
10720
return -2;
10721
if (ret < 0)
10722
goto error;
10723
return ret;
10724
}
10725
10726
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
10727
10728
error:
10729
virDispatchError(stream->conn);
10730
return -1;
10731
}
10732
10733
10734
/**
10735
* virStreamRecv:
10736
* @stream: pointer to the stream object
10737
* @data: buffer to write to stream
10738
* @nbytes: size of @data buffer
10739
*
10740
* Write a series of bytes to the stream. This method may
10741
* block the calling application for an arbitrary amount
10742
* of time.
10743
*
10744
* Errors are not guaranteed to be reported synchronously
10745
* with the call, but may instead be delayed until a
10746
* subsequent call.
10747
*
10748
* An example using this with a hypothetical file download
10749
* API looks like
10750
*
10751
* virStreamPtr st = virStreamNew(conn, 0);
10752
* int fd = open("demo.iso", O_WRONLY, 0600)
10753
*
10754
* virConnectDownloadFile(conn, "demo.iso", st);
10755
*
10756
* while (1) {
10757
* char buf[1024];
10758
* int got = virStreamRecv(st, buf, 1024);
10759
* if (got < 0)
10760
* break;
10761
* if (got == 0) {
10762
* virStreamFinish(st);
10763
* break;
10764
* }
10765
* int offset = 0;
10766
* while (offset < got) {
10767
* int sent = write(fd, buf+offset, got-offset)
10768
* if (sent < 0) {
10769
* virStreamAbort(st);
10770
* goto done;
10771
* }
10772
* offset += sent;
10773
* }
10774
* }
10775
* if (virStreamFinish(st) < 0)
10776
* ... report an error ....
10777
* done:
10778
* virStreamFree(st);
10779
* close(fd);
10780
*
10781
*
10782
* Returns the number of bytes read, which may be less
10783
* than requested.
10784
*
10785
* Returns 0 when the end of the stream is reached, at
10786
* which time the caller should invoke virStreamFinish()
10787
* to get confirmation of stream completion.
10788
*
10789
* Returns -1 upon error, at which time the stream will
10790
* be marked as aborted, and the caller should now release
10791
* the stream with virStreamFree.
10792
*
10793
* Returns -2 if there is no data pending to be read & the
10794
* stream is marked as non-blocking.
10795
*/
10796
int virStreamRecv(virStreamPtr stream,
10797
char *data,
10798
size_t nbytes)
10799
{
10800
DEBUG("stream=%p, data=%p, nbytes=%zi", stream, data, nbytes);
10801
10802
virResetLastError();
10803
10804
if (!VIR_IS_CONNECTED_STREAM(stream)) {
10805
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
10806
virDispatchError(NULL);
10807
return -1;
10808
}
10809
10810
if (stream->driver &&
10811
stream->driver->streamRecv) {
10812
int ret;
10813
ret = (stream->driver->streamRecv)(stream, data, nbytes);
10814
if (ret == -2)
10815
return -2;
10816
if (ret < 0)
10817
goto error;
10818
return ret;
10819
}
10820
10821
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
10822
10823
error:
10824
virDispatchError(stream->conn);
10825
return -1;
10826
}
10827
10828
10829
/**
10830
* virStreamSendAll:
10831
* @stream: pointer to the stream object
10832
* @handler: source callback for reading data from application
10833
* @opaque: application defined data
10834
*
10835
* Send the entire data stream, reading the data from the
10836
* requested data source. This is simply a convenient alternative
10837
* to virStreamSend, for apps that do blocking-I/o.
10838
*
10839
* An example using this with a hypothetical file upload
10840
* API looks like
10841
*
10842
* int mysource(virStreamPtr st, char *buf, int nbytes, void *opaque) {
10843
* int *fd = opaque;
10844
*
10845
* return read(*fd, buf, nbytes);
10846
* }
10847
*
10848
* virStreamPtr st = virStreamNew(conn, 0);
10849
* int fd = open("demo.iso", O_RDONLY)
10850
*
10851
* virConnectUploadFile(conn, st);
10852
* if (virStreamSendAll(st, mysource, &fd) < 0) {
10853
* ...report an error ...
10854
* goto done;
10855
* }
10856
* if (virStreamFinish(st) < 0)
10857
* ...report an error...
10858
* virStreamFree(st);
10859
* close(fd);
10860
*
10861
* Returns 0 if all the data was successfully sent. The caller
10862
* should invoke virStreamFinish(st) to flush the stream upon
10863
* success and then virStreamFree
10864
*
10865
* Returns -1 upon any error, with virStreamAbort() already
10866
* having been called, so the caller need only call
10867
* virStreamFree()
10868
*/
10869
int virStreamSendAll(virStreamPtr stream,
10870
virStreamSourceFunc handler,
10871
void *opaque)
10872
{
10873
char *bytes = NULL;
10874
int want = 1024*64;
10875
int ret = -1;
10876
DEBUG("stream=%p, handler=%p, opaque=%p", stream, handler, opaque);
10877
10878
virResetLastError();
10879
10880
if (!VIR_IS_CONNECTED_STREAM(stream)) {
10881
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
10882
virDispatchError(NULL);
10883
return -1;
10884
}
10885
10886
if (stream->flags & VIR_STREAM_NONBLOCK) {
10887
virLibConnError(VIR_ERR_OPERATION_INVALID,
10888
_("data sources cannot be used for non-blocking streams"));
10889
goto cleanup;
10890
}
10891
10892
if (VIR_ALLOC_N(bytes, want) < 0) {
10893
virReportOOMError();
10894
goto cleanup;
10895
}
10896
10897
for (;;) {
10898
int got, offset = 0;
10899
got = (handler)(stream, bytes, want, opaque);
10900
if (got < 0) {
10901
virStreamAbort(stream);
10902
goto cleanup;
10903
}
10904
if (got == 0)
10905
break;
10906
while (offset < got) {
10907
int done;
10908
done = virStreamSend(stream, bytes + offset, got - offset);
10909
if (done < 0)
10910
goto cleanup;
10911
offset += done;
10912
}
10913
}
10914
ret = 0;
10915
10916
cleanup:
10917
VIR_FREE(bytes);
10918
10919
if (ret != 0)
10920
virDispatchError(stream->conn);
10921
10922
return ret;
10923
}
10924
10925
10926
/**
10927
* virStreamRecvAll:
10928
* @stream: pointer to the stream object
10929
* @handler: sink callback for writing data to application
10930
* @opaque: application defined data
10931
*
10932
* Receive the entire data stream, sending the data to the
10933
* requested data sink. This is simply a convenient alternative
10934
* to virStreamRecv, for apps that do blocking-I/o.
10935
*
10936
* An example using this with a hypothetical file download
10937
* API looks like
10938
*
10939
* int mysink(virStreamPtr st, const char *buf, int nbytes, void *opaque) {
10940
* int *fd = opaque;
10941
*
10942
* return write(*fd, buf, nbytes);
10943
* }
10944
*
10945
* virStreamPtr st = virStreamNew(conn, 0);
10946
* int fd = open("demo.iso", O_WRONLY)
10947
*
10948
* virConnectUploadFile(conn, st);
10949
* if (virStreamRecvAll(st, mysink, &fd) < 0) {
10950
* ...report an error ...
10951
* goto done;
10952
* }
10953
* if (virStreamFinish(st) < 0)
10954
* ...report an error...
10955
* virStreamFree(st);
10956
* close(fd);
10957
*
10958
* Returns 0 if all the data was successfully received. The caller
10959
* should invoke virStreamFinish(st) to flush the stream upon
10960
* success and then virStreamFree
10961
*
10962
* Returns -1 upon any error, with virStreamAbort() already
10963
* having been called, so the caller need only call
10964
* virStreamFree()
10965
*/
10966
int virStreamRecvAll(virStreamPtr stream,
10967
virStreamSinkFunc handler,
10968
void *opaque)
10969
{
10970
char *bytes = NULL;
10971
int want = 1024*64;
10972
int ret = -1;
10973
DEBUG("stream=%p, handler=%p, opaque=%p", stream, handler, opaque);
10974
10975
virResetLastError();
10976
10977
if (!VIR_IS_CONNECTED_STREAM(stream)) {
10978
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
10979
virDispatchError(NULL);
10980
return -1;
10981
}
10982
10983
if (stream->flags & VIR_STREAM_NONBLOCK) {
10984
virLibConnError(VIR_ERR_OPERATION_INVALID,
10985
_("data sinks cannot be used for non-blocking streams"));
10986
goto cleanup;
10987
}
10988
10989
10990
if (VIR_ALLOC_N(bytes, want) < 0) {
10991
virReportOOMError();
10992
goto cleanup;
10993
}
10994
10995
for (;;) {
10996
int got, offset = 0;
10997
got = virStreamRecv(stream, bytes, want);
10998
if (got < 0)
10999
goto cleanup;
11000
if (got == 0)
11001
break;
11002
while (offset < got) {
11003
int done;
11004
done = (handler)(stream, bytes + offset, got - offset, opaque);
11005
if (done < 0) {
11006
virStreamAbort(stream);
11007
goto cleanup;
11008
}
11009
offset += done;
11010
}
11011
}
11012
ret = 0;
11013
11014
cleanup:
11015
VIR_FREE(bytes);
11016
11017
if (ret != 0)
11018
virDispatchError(stream->conn);
11019
11020
return ret;
11021
}
11022
11023
11024
/**
11025
* virStreamEventAddCallback:
11026
* @stream: pointer to the stream object
11027
* @events: set of events to monitor
11028
* @cb: callback to invoke when an event occurs
11029
* @opaque: application defined data
11030
* @ff: callback to free @opaque data
11031
*
11032
* Register a callback to be notified when a stream
11033
* becomes writable, or readable. This is most commonly
11034
* used in conjunction with non-blocking data streams
11035
* to integrate into an event loop
11036
*
11037
* Returns 0 on success, -1 upon error
11038
*/
11039
int virStreamEventAddCallback(virStreamPtr stream,
11040
int events,
11041
virStreamEventCallback cb,
11042
void *opaque,
11043
virFreeCallback ff)
11044
{
11045
DEBUG("stream=%p, events=%d, cb=%p, opaque=%p, ff=%p", stream, events, cb, opaque, ff);
11046
11047
virResetLastError();
11048
11049
if (!VIR_IS_CONNECTED_STREAM(stream)) {
11050
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11051
virDispatchError(NULL);
11052
return -1;
11053
}
11054
11055
if (stream->driver &&
11056
stream->driver->streamAddCallback) {
11057
int ret;
11058
ret = (stream->driver->streamAddCallback)(stream, events, cb, opaque, ff);
11059
if (ret < 0)
11060
goto error;
11061
return ret;
11062
}
11063
11064
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11065
11066
error:
11067
virDispatchError(stream->conn);
11068
return -1;
11069
}
11070
11071
11072
/**
11073
* virStreamEventUpdateCallback:
11074
* @stream: pointer to the stream object
11075
* @events: set of events to monitor
11076
*
11077
* Changes the set of events to monitor for a stream. This allows
11078
* for event notification to be changed without having to
11079
* unregister & register the callback completely. This method
11080
* is guarenteed to succeed if a callback is already registered
11081
*
11082
* Returns 0 on success, -1 if no callback is registered
11083
*/
11084
int virStreamEventUpdateCallback(virStreamPtr stream,
11085
int events)
11086
{
11087
DEBUG("stream=%p, events=%d", stream, events);
11088
11089
virResetLastError();
11090
11091
if (!VIR_IS_CONNECTED_STREAM(stream)) {
11092
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11093
virDispatchError(NULL);
11094
return -1;
11095
}
11096
11097
if (stream->driver &&
11098
stream->driver->streamUpdateCallback) {
11099
int ret;
11100
ret = (stream->driver->streamUpdateCallback)(stream, events);
11101
if (ret < 0)
11102
goto error;
11103
return ret;
11104
}
11105
11106
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11107
11108
error:
11109
virDispatchError(stream->conn);
11110
return -1;
11111
}
11112
11113
/**
11114
* virStreamEventRemoveCallback:
11115
* @stream: pointer to the stream object
11116
*
11117
* Remove an event callback from the stream
11118
*
11119
* Returns 0 on success, -1 on error
11120
*/
11121
int virStreamEventRemoveCallback(virStreamPtr stream)
11122
{
11123
DEBUG("stream=%p", stream);
11124
11125
virResetLastError();
11126
11127
if (!VIR_IS_CONNECTED_STREAM(stream)) {
11128
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11129
virDispatchError(NULL);
11130
return -1;
11131
}
11132
11133
if (stream->driver &&
11134
stream->driver->streamRemoveCallback) {
11135
int ret;
11136
ret = (stream->driver->streamRemoveCallback)(stream);
11137
if (ret < 0)
11138
goto error;
11139
return ret;
11140
}
11141
11142
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11143
11144
error:
11145
virDispatchError(stream->conn);
11146
return -1;
11147
}
11148
11149
/**
11150
* virStreamFinish:
11151
* @stream: pointer to the stream object
11152
*
11153
* Indicate that there is no further data is to be transmitted
11154
* on the stream. For output streams this should be called once
11155
* all data has been written. For input streams this should be
11156
* called once virStreamRecv returns end-of-file.
11157
*
11158
* This method is a synchronization point for all asynchronous
11159
* errors, so if this returns a success code the application can
11160
* be sure that all data has been successfully processed.
11161
*
11162
* Returns 0 on success, -1 upon error
11163
*/
11164
int virStreamFinish(virStreamPtr stream)
11165
{
11166
DEBUG("stream=%p", stream);
11167
11168
virResetLastError();
11169
11170
if (!VIR_IS_CONNECTED_STREAM(stream)) {
11171
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11172
virDispatchError(NULL);
11173
return -1;
11174
}
11175
11176
if (stream->driver &&
11177
stream->driver->streamFinish) {
11178
int ret;
11179
ret = (stream->driver->streamFinish)(stream);
11180
if (ret < 0)
11181
goto error;
11182
return ret;
11183
}
11184
11185
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11186
11187
error:
11188
virDispatchError(stream->conn);
11189
return -1;
11190
}
11191
11192
/**
11193
* virStreamAbort:
11194
* @stream: pointer to the stream object
11195
*
11196
* Request that the in progress data transfer be cancelled
11197
* abnormally before the end of the stream has been reached.
11198
* For output streams this can be used to inform the driver
11199
* that the stream is being terminated early. For input
11200
* streams this can be used to inform the driver that it
11201
* should stop sending data.
11202
*
11203
* Returns 0 on success, -1 upon error
11204
*/
11205
int virStreamAbort(virStreamPtr stream)
11206
{
11207
DEBUG("stream=%p", stream);
11208
11209
virResetLastError();
11210
11211
if (!VIR_IS_CONNECTED_STREAM(stream)) {
11212
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11213
virDispatchError(NULL);
11214
return -1;
11215
}
11216
11217
if (stream->driver &&
11218
stream->driver->streamAbort) {
11219
int ret;
11220
ret = (stream->driver->streamAbort)(stream);
11221
if (ret < 0)
11222
goto error;
11223
return ret;
11224
}
11225
11226
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11227
11228
error:
11229
virDispatchError(stream->conn);
11230
return -1;
11231
}
11232
11233
/**
11234
* virStreamFree:
11235
* @stream: pointer to the stream object
11236
*
11237
* Decrement the reference count on a stream, releasing
11238
* the stream object if the reference count has hit zero.
11239
*
11240
* There must not be an active data transfer in progress
11241
* when releasing the stream. If a stream needs to be
11242
* disposed of prior to end of stream being reached, then
11243
* the virStreamAbort function should be called first.
11244
*
11245
* Returns 0 upon success, or -1 on error
11246
*/
11247
int virStreamFree(virStreamPtr stream)
11248
{
11249
DEBUG("stream=%p", stream);
11250
11251
virResetLastError();
11252
11253
if (!VIR_IS_CONNECTED_STREAM(stream)) {
11254
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11255
virDispatchError(NULL);
11256
return -1;
11257
}
11258
11259
/* XXX Enforce shutdown before free'ing resources ? */
11260
11261
if (virUnrefStream(stream) < 0) {
11262
virDispatchError(NULL);
11263
return -1;
11264
}
11265
return 0;
11266
}
11267
11268
11269
/**
11270
* virDomainIsActive:
11271
* @dom: pointer to the domain object
11272
*
11273
* Determine if the domain is currently running
11274
*
11275
* Returns 1 if running, 0 if inactive, -1 on error
11276
*/
11277
int virDomainIsActive(virDomainPtr dom)
11278
{
11279
DEBUG("dom=%p", dom);
11280
11281
virResetLastError();
11282
11283
if (!VIR_IS_CONNECTED_DOMAIN(dom)) {
11284
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11285
virDispatchError(NULL);
11286
return -1;
11287
}
11288
if (dom->conn->driver->domainIsActive) {
11289
int ret;
11290
ret = dom->conn->driver->domainIsActive(dom);
11291
if (ret < 0)
11292
goto error;
11293
return ret;
11294
}
11295
11296
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11297
error:
11298
virDispatchError(dom->conn);
11299
return -1;
11300
}
11301
11302
/**
11303
* virDomainIsPersistent:
11304
* @dom: pointer to the domain object
11305
*
11306
* Determine if the domain has a persistent configuration
11307
* which means it will still exist after shutting down
11308
*
11309
* Returns 1 if persistent, 0 if transient, -1 on error
11310
*/
11311
int virDomainIsPersistent(virDomainPtr dom)
11312
{
11313
VIR_DOMAIN_DEBUG0(dom);
11314
11315
virResetLastError();
11316
11317
if (!VIR_IS_CONNECTED_DOMAIN(dom)) {
11318
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11319
virDispatchError(NULL);
11320
return -1;
11321
}
11322
if (dom->conn->driver->domainIsPersistent) {
11323
int ret;
11324
ret = dom->conn->driver->domainIsPersistent(dom);
11325
if (ret < 0)
11326
goto error;
11327
return ret;
11328
}
11329
11330
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11331
error:
11332
virDispatchError(dom->conn);
11333
return -1;
11334
}
11335
11336
/**
11337
* virDomainIsUpdated:
11338
* @dom: pointer to the domain object
11339
*
11340
* Determine if the domain has been updated.
11341
*
11342
* Returns 1 if updated, 0 if not, -1 on error
11343
*/
11344
int virDomainIsUpdated(virDomainPtr dom)
11345
{
11346
VIR_DOMAIN_DEBUG0(dom);
11347
11348
virResetLastError();
11349
11350
if (!VIR_IS_CONNECTED_DOMAIN(dom)) {
11351
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11352
virDispatchError(NULL);
11353
return -1;
11354
}
11355
if (dom->conn->driver->domainIsUpdated) {
11356
int ret;
11357
ret = dom->conn->driver->domainIsUpdated(dom);
11358
if (ret < 0)
11359
goto error;
11360
return ret;
11361
}
11362
11363
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11364
error:
11365
virDispatchError(dom->conn);
11366
return -1;
11367
}
11368
11369
/**
11370
* virNetworkIsActive:
11371
* @net: pointer to the network object
11372
*
11373
* Determine if the network is currently running
11374
*
11375
* Returns 1 if running, 0 if inactive, -1 on error
11376
*/
11377
int virNetworkIsActive(virNetworkPtr net)
11378
{
11379
DEBUG("net=%p", net);
11380
11381
virResetLastError();
11382
11383
if (!VIR_IS_CONNECTED_NETWORK(net)) {
11384
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11385
virDispatchError(NULL);
11386
return -1;
11387
}
11388
if (net->conn->networkDriver->networkIsActive) {
11389
int ret;
11390
ret = net->conn->networkDriver->networkIsActive(net);
11391
if (ret < 0)
11392
goto error;
11393
return ret;
11394
}
11395
11396
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11397
error:
11398
virDispatchError(net->conn);
11399
return -1;
11400
}
11401
11402
11403
/**
11404
* virNetworkIsPersistent:
11405
* @net: pointer to the network object
11406
*
11407
* Determine if the network has a persistent configuration
11408
* which means it will still exist after shutting down
11409
*
11410
* Returns 1 if persistent, 0 if transient, -1 on error
11411
*/
11412
int virNetworkIsPersistent(virNetworkPtr net)
11413
{
11414
DEBUG("net=%p", net);
11415
11416
virResetLastError();
11417
11418
if (!VIR_IS_CONNECTED_NETWORK(net)) {
11419
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11420
virDispatchError(NULL);
11421
return -1;
11422
}
11423
if (net->conn->networkDriver->networkIsPersistent) {
11424
int ret;
11425
ret = net->conn->networkDriver->networkIsPersistent(net);
11426
if (ret < 0)
11427
goto error;
11428
return ret;
11429
}
11430
11431
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11432
error:
11433
virDispatchError(net->conn);
11434
return -1;
11435
}
11436
11437
11438
/**
11439
* virStoragePoolIsActive:
11440
* @pool: pointer to the storage pool object
11441
*
11442
* Determine if the storage pool is currently running
11443
*
11444
* Returns 1 if running, 0 if inactive, -1 on error
11445
*/
11446
int virStoragePoolIsActive(virStoragePoolPtr pool)
11447
{
11448
DEBUG("pool=%p", pool);
11449
11450
virResetLastError();
11451
11452
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
11453
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11454
virDispatchError(NULL);
11455
return -1;
11456
}
11457
if (pool->conn->storageDriver->poolIsActive) {
11458
int ret;
11459
ret = pool->conn->storageDriver->poolIsActive(pool);
11460
if (ret < 0)
11461
goto error;
11462
return ret;
11463
}
11464
11465
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11466
error:
11467
virDispatchError(pool->conn);
11468
return -1;
11469
}
11470
11471
11472
/**
11473
* virStoragePoolIsPersistent:
11474
* @pool: pointer to the storage pool object
11475
*
11476
* Determine if the storage pool has a persistent configuration
11477
* which means it will still exist after shutting down
11478
*
11479
* Returns 1 if persistent, 0 if transient, -1 on error
11480
*/
11481
int virStoragePoolIsPersistent(virStoragePoolPtr pool)
11482
{
11483
DEBUG("pool=%p", pool);
11484
11485
virResetLastError();
11486
11487
if (!VIR_IS_CONNECTED_STORAGE_POOL(pool)) {
11488
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11489
virDispatchError(NULL);
11490
return -1;
11491
}
11492
if (pool->conn->storageDriver->poolIsPersistent) {
11493
int ret;
11494
ret = pool->conn->storageDriver->poolIsPersistent(pool);
11495
if (ret < 0)
11496
goto error;
11497
return ret;
11498
}
11499
11500
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11501
error:
11502
virDispatchError(pool->conn);
11503
return -1;
11504
}
11505
11506
11507
11508
/**
11509
* virConnectNumOfNWFilters:
11510
* @conn: pointer to the hypervisor connection
11511
*
11512
* Provides the number of nwfilters.
11513
*
11514
* Returns the number of nwfilters found or -1 in case of error
11515
*/
11516
int
11517
virConnectNumOfNWFilters(virConnectPtr conn)
11518
{
11519
DEBUG("conn=%p", conn);
11520
11521
virResetLastError();
11522
11523
if (!VIR_IS_CONNECT(conn)) {
11524
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11525
virDispatchError(NULL);
11526
return -1;
11527
}
11528
11529
if (conn->nwfilterDriver && conn->nwfilterDriver->numOfNWFilters) {
11530
int ret;
11531
ret = conn->nwfilterDriver->numOfNWFilters (conn);
11532
if (ret < 0)
11533
goto error;
11534
return ret;
11535
}
11536
11537
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11538
11539
error:
11540
virDispatchError(conn);
11541
return -1;
11542
}
11543
11544
11545
/**
11546
* virConnectListNWFilters:
11547
* @conn: pointer to the hypervisor connection
11548
* @names: array to collect the list of names of network filters
11549
* @maxnames: size of @names
11550
*
11551
* Collect the list of network filters, and store their names in @names
11552
*
11553
* Returns the number of network filters found or -1 in case of error
11554
*/
11555
int
11556
virConnectListNWFilters(virConnectPtr conn, char **const names, int maxnames)
11557
{
11558
DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames);
11559
11560
virResetLastError();
11561
11562
if (!VIR_IS_CONNECT(conn)) {
11563
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11564
virDispatchError(NULL);
11565
return -1;
11566
}
11567
11568
if ((names == NULL) || (maxnames < 0)) {
11569
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
11570
goto error;
11571
}
11572
11573
if (conn->nwfilterDriver && conn->nwfilterDriver->listNWFilters) {
11574
int ret;
11575
ret = conn->nwfilterDriver->listNWFilters (conn, names, maxnames);
11576
if (ret < 0)
11577
goto error;
11578
return ret;
11579
}
11580
11581
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11582
11583
error:
11584
virDispatchError(conn);
11585
return -1;
11586
}
11587
11588
11589
/**
11590
* virNWFilterLookupByName:
11591
* @conn: pointer to the hypervisor connection
11592
* @name: name for the network filter
11593
*
11594
* Try to lookup a network filter on the given hypervisor based on its name.
11595
*
11596
* Returns a new nwfilter object or NULL in case of failure. If the
11597
* network filter cannot be found, then VIR_ERR_NO_NWFILTER error is raised.
11598
*/
11599
virNWFilterPtr
11600
virNWFilterLookupByName(virConnectPtr conn, const char *name)
11601
{
11602
DEBUG("conn=%p, name=%s", conn, name);
11603
11604
virResetLastError();
11605
11606
if (!VIR_IS_CONNECT(conn)) {
11607
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11608
virDispatchError(NULL);
11609
return NULL;
11610
}
11611
if (name == NULL) {
11612
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
11613
goto error;
11614
}
11615
11616
if (conn->nwfilterDriver && conn->nwfilterDriver->nwfilterLookupByName) {
11617
virNWFilterPtr ret;
11618
ret = conn->nwfilterDriver->nwfilterLookupByName (conn, name);
11619
if (!ret)
11620
goto error;
11621
return ret;
11622
}
11623
11624
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11625
11626
error:
11627
virDispatchError(conn);
11628
return NULL;
11629
}
11630
11631
/**
11632
* virNWFilterLookupByUUID:
11633
* @conn: pointer to the hypervisor connection
11634
* @uuid: the raw UUID for the network filter
11635
*
11636
* Try to lookup a network filter on the given hypervisor based on its UUID.
11637
*
11638
* Returns a new nwfilter object or NULL in case of failure. If the
11639
* nwfdilter cannot be found, then VIR_ERR_NO_NWFILTER error is raised.
11640
*/
11641
virNWFilterPtr
11642
virNWFilterLookupByUUID(virConnectPtr conn, const unsigned char *uuid)
11643
{
11644
DEBUG("conn=%p, uuid=%s", conn, uuid);
11645
11646
virResetLastError();
11647
11648
if (!VIR_IS_CONNECT(conn)) {
11649
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11650
virDispatchError(NULL);
11651
return NULL;
11652
}
11653
if (uuid == NULL) {
11654
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
11655
goto error;
11656
}
11657
11658
if (conn->nwfilterDriver && conn->nwfilterDriver->nwfilterLookupByUUID){
11659
virNWFilterPtr ret;
11660
ret = conn->nwfilterDriver->nwfilterLookupByUUID (conn, uuid);
11661
if (!ret)
11662
goto error;
11663
return ret;
11664
}
11665
11666
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11667
11668
error:
11669
virDispatchError(conn);
11670
return NULL;
11671
}
11672
11673
/**
11674
* virNWFilterLookupByUUIDString:
11675
* @conn: pointer to the hypervisor connection
11676
* @uuidstr: the string UUID for the nwfilter
11677
*
11678
* Try to lookup an nwfilter on the given hypervisor based on its UUID.
11679
*
11680
* Returns a new nwfilter object or NULL in case of failure. If the
11681
* nwfilter cannot be found, then VIR_ERR_NO_NWFILTER error is raised.
11682
*/
11683
virNWFilterPtr
11684
virNWFilterLookupByUUIDString(virConnectPtr conn, const char *uuidstr)
11685
{
11686
unsigned char uuid[VIR_UUID_BUFLEN];
11687
DEBUG("conn=%p, uuidstr=%s", conn, uuidstr);
11688
11689
virResetLastError();
11690
11691
if (!VIR_IS_CONNECT(conn)) {
11692
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11693
virDispatchError(NULL);
11694
return NULL;
11695
}
11696
if (uuidstr == NULL) {
11697
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
11698
goto error;
11699
}
11700
11701
if (virUUIDParse(uuidstr, uuid) < 0) {
11702
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
11703
goto error;
11704
}
11705
11706
return virNWFilterLookupByUUID(conn, &uuid[0]);
11707
11708
error:
11709
virDispatchError(conn);
11710
return NULL;
11711
}
11712
11713
/**
11714
* virNWFilterFree:
11715
* @nwfilter: a nwfilter object
11716
*
11717
* Free the nwfilter object. The running instance is kept alive.
11718
* The data structure is freed and should not be used thereafter.
11719
*
11720
* Returns 0 in case of success and -1 in case of failure.
11721
*/
11722
int
11723
virNWFilterFree(virNWFilterPtr nwfilter)
11724
{
11725
DEBUG("nwfilter=%p", nwfilter);
11726
11727
virResetLastError();
11728
11729
if (!VIR_IS_CONNECTED_NWFILTER(nwfilter)) {
11730
virLibNWFilterError(VIR_ERR_INVALID_NWFILTER, __FUNCTION__);
11731
virDispatchError(NULL);
11732
return -1;
11733
}
11734
if (virUnrefNWFilter(nwfilter) < 0) {
11735
virDispatchError(NULL);
11736
return -1;
11737
}
11738
return 0;
11739
}
11740
11741
/**
11742
* virNWFilterGetName:
11743
* @nwfilter: a nwfilter object
11744
*
11745
* Get the public name for the network filter
11746
*
11747
* Returns a pointer to the name or NULL, the string need not be deallocated
11748
* its lifetime will be the same as the nwfilter object.
11749
*/
11750
const char *
11751
virNWFilterGetName(virNWFilterPtr nwfilter)
11752
{
11753
DEBUG("nwfilter=%p", nwfilter);
11754
11755
virResetLastError();
11756
11757
if (!VIR_IS_NWFILTER(nwfilter)) {
11758
virLibNWFilterError(VIR_ERR_INVALID_NWFILTER, __FUNCTION__);
11759
virDispatchError(NULL);
11760
return NULL;
11761
}
11762
return nwfilter->name;
11763
}
11764
11765
/**
11766
* virNWFilterGetUUID:
11767
* @nwfilter: a nwfilter object
11768
* @uuid: pointer to a VIR_UUID_BUFLEN bytes array
11769
*
11770
* Get the UUID for a network filter
11771
*
11772
* Returns -1 in case of error, 0 in case of success
11773
*/
11774
int
11775
virNWFilterGetUUID(virNWFilterPtr nwfilter, unsigned char *uuid)
11776
{
11777
DEBUG("nwfilter=%p, uuid=%p", nwfilter, uuid);
11778
11779
virResetLastError();
11780
11781
if (!VIR_IS_NWFILTER(nwfilter)) {
11782
virLibNWFilterError(VIR_ERR_INVALID_NWFILTER, __FUNCTION__);
11783
virDispatchError(NULL);
11784
return -1;
11785
}
11786
if (uuid == NULL) {
11787
virLibNWFilterError(VIR_ERR_INVALID_ARG, __FUNCTION__);
11788
goto error;
11789
}
11790
11791
memcpy(uuid, &nwfilter->uuid[0], VIR_UUID_BUFLEN);
11792
11793
return 0;
11794
11795
error:
11796
virDispatchError(nwfilter->conn);
11797
return -1;
11798
}
11799
11800
/**
11801
* virNWFilterGetUUIDString:
11802
* @nwfilter: a nwfilter object
11803
* @buf: pointer to a VIR_UUID_STRING_BUFLEN bytes array
11804
*
11805
* Get the UUID for a network filter as string. For more information about
11806
* UUID see RFC4122.
11807
*
11808
* Returns -1 in case of error, 0 in case of success
11809
*/
11810
int
11811
virNWFilterGetUUIDString(virNWFilterPtr nwfilter, char *buf)
11812
{
11813
unsigned char uuid[VIR_UUID_BUFLEN];
11814
DEBUG("nwfilter=%p, buf=%p", nwfilter, buf);
11815
11816
virResetLastError();
11817
11818
if (!VIR_IS_NWFILTER(nwfilter)) {
11819
virLibNWFilterError(VIR_ERR_INVALID_NWFILTER, __FUNCTION__);
11820
virDispatchError(NULL);
11821
return -1;
11822
}
11823
if (buf == NULL) {
11824
virLibNWFilterError(VIR_ERR_INVALID_ARG, __FUNCTION__);
11825
goto error;
11826
}
11827
11828
if (virNWFilterGetUUID(nwfilter, &uuid[0]))
11829
goto error;
11830
11831
virUUIDFormat(uuid, buf);
11832
return 0;
11833
11834
error:
11835
virDispatchError(nwfilter->conn);
11836
return -1;
11837
}
11838
11839
11840
/**
11841
* virNWFilterDefineXML:
11842
* @conn: pointer to the hypervisor connection
11843
* @xmlDesc: an XML description of the nwfilter
11844
*
11845
* Define a new network filter, based on an XML description
11846
* similar to the one returned by virNWFilterGetXMLDesc()
11847
*
11848
* Returns a new nwfilter object or NULL in case of failure
11849
*/
11850
virNWFilterPtr
11851
virNWFilterDefineXML(virConnectPtr conn, const char *xmlDesc)
11852
{
11853
DEBUG("conn=%p, xmlDesc=%s", conn, xmlDesc);
11854
11855
virResetLastError();
11856
11857
if (!VIR_IS_CONNECT(conn)) {
11858
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
11859
virDispatchError(NULL);
11860
return NULL;
11861
}
11862
if (xmlDesc == NULL) {
11863
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
11864
goto error;
11865
}
11866
if (conn->flags & VIR_CONNECT_RO) {
11867
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
11868
goto error;
11869
}
11870
11871
if (conn->nwfilterDriver && conn->nwfilterDriver->defineXML) {
11872
virNWFilterPtr ret;
11873
ret = conn->nwfilterDriver->defineXML (conn, xmlDesc, 0);
11874
if (!ret)
11875
goto error;
11876
return ret;
11877
}
11878
11879
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11880
11881
error:
11882
virDispatchError(conn);
11883
return NULL;
11884
}
11885
11886
11887
/**
11888
* virNWFilterUndefine:
11889
* @nwfilter: a nwfilter object
11890
*
11891
* Undefine the nwfilter object. This call will not succeed if
11892
* a running VM is referencing the filter. This does not free the
11893
* associated virNWFilterPtr object.
11894
*
11895
* Returns 0 in case of success and -1 in case of failure.
11896
*/
11897
int
11898
virNWFilterUndefine(virNWFilterPtr nwfilter)
11899
{
11900
virConnectPtr conn;
11901
DEBUG("nwfilter=%p", nwfilter);
11902
11903
virResetLastError();
11904
11905
if (!VIR_IS_CONNECTED_NWFILTER(nwfilter)) {
11906
virLibNWFilterError(VIR_ERR_INVALID_NWFILTER, __FUNCTION__);
11907
virDispatchError(NULL);
11908
return -1;
11909
}
11910
11911
conn = nwfilter->conn;
11912
if (conn->flags & VIR_CONNECT_RO) {
11913
virLibNWFilterError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
11914
goto error;
11915
}
11916
11917
if (conn->nwfilterDriver && conn->nwfilterDriver->undefine) {
11918
int ret;
11919
ret = conn->nwfilterDriver->undefine (nwfilter);
11920
if (ret < 0)
11921
goto error;
11922
return ret;
11923
}
11924
11925
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11926
11927
error:
11928
virDispatchError(nwfilter->conn);
11929
return -1;
11930
}
11931
11932
11933
/**
11934
* virNWFilterGetXMLDesc:
11935
* @nwfilter: a nwfilter object
11936
* @flags: an OR'ed set of extraction flags, not used yet
11937
*
11938
* Provide an XML description of the network filter. The description may be
11939
* reused later to redefine the network filter with virNWFilterCreateXML().
11940
*
11941
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
11942
* the caller must free() the returned value.
11943
*/
11944
char *
11945
virNWFilterGetXMLDesc(virNWFilterPtr nwfilter, int flags)
11946
{
11947
virConnectPtr conn;
11948
DEBUG("nwfilter=%p, flags=%d", nwfilter, flags);
11949
11950
virResetLastError();
11951
11952
if (!VIR_IS_CONNECTED_NWFILTER(nwfilter)) {
11953
virLibNWFilterError(VIR_ERR_INVALID_NWFILTER, __FUNCTION__);
11954
virDispatchError(NULL);
11955
return NULL;
11956
}
11957
if (flags != 0) {
11958
virLibNWFilterError(VIR_ERR_INVALID_ARG, __FUNCTION__);
11959
goto error;
11960
}
11961
11962
conn = nwfilter->conn;
11963
11964
if (conn->nwfilterDriver && conn->nwfilterDriver->getXMLDesc) {
11965
char *ret;
11966
ret = conn->nwfilterDriver->getXMLDesc (nwfilter, flags);
11967
if (!ret)
11968
goto error;
11969
return ret;
11970
}
11971
11972
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
11973
11974
error:
11975
virDispatchError(nwfilter->conn);
11976
return NULL;
11977
}
11978
11979
11980
/**
11981
* virNWFilterRef:
11982
* @nwfilter: the nwfilter to hold a reference on
11983
*
11984
* Increment the reference count on the nwfilter. For each
11985
* additional call to this method, there shall be a corresponding
11986
* call to virNWFilterFree to release the reference count, once
11987
* the caller no longer needs the reference to this object.
11988
*
11989
* This method is typically useful for applications where multiple
11990
* threads are using a connection, and it is required that the
11991
* connection remain open until all threads have finished using
11992
* it. ie, each new thread using an nwfilter would increment
11993
* the reference count.
11994
*
11995
* Returns 0 in case of success, -1 in case of failure.
11996
*/
11997
int
11998
virNWFilterRef(virNWFilterPtr nwfilter)
11999
{
12000
if ((!VIR_IS_CONNECTED_NWFILTER(nwfilter))) {
12001
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
12002
virDispatchError(NULL);
12003
return -1;
12004
}
12005
virMutexLock(&nwfilter->conn->lock);
12006
DEBUG("nwfilter=%p refs=%d", nwfilter, nwfilter->refs);
12007
nwfilter->refs++;
12008
virMutexUnlock(&nwfilter->conn->lock);
12009
return 0;
12010
}
12011
12012
12013
/**
12014
* virInterfaceIsActive:
12015
* @iface: pointer to the interface object
12016
*
12017
* Determine if the interface is currently running
12018
*
12019
* Returns 1 if running, 0 if inactive, -1 on error
12020
*/
12021
int virInterfaceIsActive(virInterfacePtr iface)
12022
{
12023
DEBUG("iface=%p", iface);
12024
12025
virResetLastError();
12026
12027
if (!VIR_IS_CONNECTED_INTERFACE(iface)) {
12028
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
12029
virDispatchError(NULL);
12030
return -1;
12031
}
12032
if (iface->conn->interfaceDriver->interfaceIsActive) {
12033
int ret;
12034
ret = iface->conn->interfaceDriver->interfaceIsActive(iface);
12035
if (ret < 0)
12036
goto error;
12037
return ret;
12038
}
12039
12040
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12041
error:
12042
virDispatchError(iface->conn);
12043
return -1;
12044
}
12045
12046
12047
/**
12048
* virConnectIsEncrypted:
12049
* @conn: pointer to the connection object
12050
*
12051
* Determine if the connection to the hypervisor is encrypted
12052
*
12053
* Returns 1 if encrypted, 0 if not encrypted, -1 on error
12054
*/
12055
int virConnectIsEncrypted(virConnectPtr conn)
12056
{
12057
DEBUG("conn=%p", conn);
12058
12059
virResetLastError();
12060
12061
if (!VIR_IS_CONNECT(conn)) {
12062
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
12063
virDispatchError(NULL);
12064
return -1;
12065
}
12066
if (conn->driver->isEncrypted) {
12067
int ret;
12068
ret = conn->driver->isEncrypted(conn);
12069
if (ret < 0)
12070
goto error;
12071
return ret;
12072
}
12073
12074
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12075
error:
12076
virDispatchError(conn);
12077
return -1;
12078
}
12079
12080
/**
12081
* virConnectIsSecure:
12082
* @conn: pointer to the connection object
12083
*
12084
* Determine if the connection to the hypervisor is secure
12085
*
12086
* A connection will be classed as secure if it is either
12087
* encrypted, or running over a channel which is not exposed
12088
* to eavesdropping (eg a UNIX domain socket, or pipe)
12089
*
12090
* Returns 1 if secure, 0 if secure, -1 on error
12091
*/
12092
int virConnectIsSecure(virConnectPtr conn)
12093
{
12094
DEBUG("conn=%p", conn);
12095
12096
virResetLastError();
12097
12098
if (!VIR_IS_CONNECT(conn)) {
12099
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
12100
virDispatchError(NULL);
12101
return -1;
12102
}
12103
if (conn->driver->isSecure) {
12104
int ret;
12105
ret = conn->driver->isSecure(conn);
12106
if (ret < 0)
12107
goto error;
12108
return ret;
12109
}
12110
12111
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12112
error:
12113
virDispatchError(conn);
12114
return -1;
12115
}
12116
12117
12118
/**
12119
* virConnectCompareCPU:
12120
* @conn: virConnect connection
12121
* @xmlDesc: XML describing the CPU to compare with host CPU
12122
* @flags: currently unused, pass 0
12123
*
12124
* Compares the given CPU description with the host CPU
12125
*
12126
* Returns comparison result according to enum virCPUCompareResult
12127
*/
12128
int
12129
virConnectCompareCPU(virConnectPtr conn,
12130
const char *xmlDesc,
12131
unsigned int flags)
12132
{
12133
VIR_DEBUG("conn=%p, xmlDesc=%s, flags=%u", conn, xmlDesc, flags);
12134
12135
virResetLastError();
12136
12137
if (!VIR_IS_CONNECT(conn)) {
12138
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
12139
virDispatchError(NULL);
12140
return VIR_CPU_COMPARE_ERROR;
12141
}
12142
if (xmlDesc == NULL) {
12143
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
12144
goto error;
12145
}
12146
12147
if (conn->driver->cpuCompare) {
12148
int ret;
12149
12150
ret = conn->driver->cpuCompare(conn, xmlDesc, flags);
12151
if (ret == VIR_CPU_COMPARE_ERROR)
12152
goto error;
12153
return ret;
12154
}
12155
12156
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12157
12158
error:
12159
virDispatchError(conn);
12160
return VIR_CPU_COMPARE_ERROR;
12161
}
12162
12163
12164
/**
12165
* virConnectBaselineCPU:
12166
*
12167
* @conn: virConnect connection
12168
* @xmlCPUs: array of XML descriptions of host CPUs
12169
* @ncpus: number of CPUs in xmlCPUs
12170
* @flags: fine-tuning flags, currently unused, pass 0.
12171
*
12172
* Computes the most feature-rich CPU which is compatible with all given
12173
* host CPUs.
12174
*
12175
* Returns XML description of the computed CPU or NULL on error.
12176
*/
12177
char *
12178
virConnectBaselineCPU(virConnectPtr conn,
12179
const char **xmlCPUs,
12180
unsigned int ncpus,
12181
unsigned int flags)
12182
{
12183
unsigned int i;
12184
12185
VIR_DEBUG("conn=%p, xmlCPUs=%p, ncpus=%u, flags=%u",
12186
conn, xmlCPUs, ncpus, flags);
12187
if (xmlCPUs) {
12188
for (i = 0; i < ncpus; i++)
12189
VIR_DEBUG("xmlCPUs[%u]=%s", i, NULLSTR(xmlCPUs[i]));
12190
}
12191
12192
virResetLastError();
12193
12194
if (!VIR_IS_CONNECT(conn)) {
12195
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
12196
virDispatchError(NULL);
12197
return NULL;
12198
}
12199
if (xmlCPUs == NULL) {
12200
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
12201
goto error;
12202
}
12203
12204
if (conn->driver->cpuBaseline) {
12205
char *cpu;
12206
12207
cpu = conn->driver->cpuBaseline(conn, xmlCPUs, ncpus, flags);
12208
if (!cpu)
12209
goto error;
12210
return cpu;
12211
}
12212
12213
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12214
12215
error:
12216
virDispatchError(conn);
12217
return NULL;
12218
}
12219
12220
12221
/**
12222
* virDomainGetJobInfo:
12223
* @domain: a domain object
12224
* @info: pointer to a virDomainJobInfo structure allocated by the user
12225
*
12226
* Extract information about progress of a background job on a domain.
12227
* Will return an error if the domain is not active.
12228
*
12229
* Returns 0 in case of success and -1 in case of failure.
12230
*/
12231
int
12232
virDomainGetJobInfo(virDomainPtr domain, virDomainJobInfoPtr info)
12233
{
12234
virConnectPtr conn;
12235
12236
VIR_DOMAIN_DEBUG(domain, "info=%p", info);
12237
12238
virResetLastError();
12239
12240
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
12241
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
12242
virDispatchError(NULL);
12243
return -1;
12244
}
12245
if (info == NULL) {
12246
virLibDomainError(VIR_ERR_INVALID_ARG, __FUNCTION__);
12247
goto error;
12248
}
12249
12250
memset(info, 0, sizeof(virDomainJobInfo));
12251
12252
conn = domain->conn;
12253
12254
if (conn->driver->domainGetJobInfo) {
12255
int ret;
12256
ret = conn->driver->domainGetJobInfo (domain, info);
12257
if (ret < 0)
12258
goto error;
12259
return ret;
12260
}
12261
12262
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12263
12264
error:
12265
virDispatchError(domain->conn);
12266
return -1;
12267
}
12268
12269
12270
/**
12271
* virDomainAbortJob:
12272
* @domain: a domain object
12273
*
12274
* Requests that the current background job be aborted at the
12275
* soonest opportunity. This will block until the job has
12276
* either completed, or aborted.
12277
*
12278
* Returns 0 in case of success and -1 in case of failure.
12279
*/
12280
int
12281
virDomainAbortJob(virDomainPtr domain)
12282
{
12283
virConnectPtr conn;
12284
12285
VIR_DOMAIN_DEBUG0(domain);
12286
12287
virResetLastError();
12288
12289
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
12290
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
12291
virDispatchError(NULL);
12292
return -1;
12293
}
12294
12295
conn = domain->conn;
12296
if (conn->flags & VIR_CONNECT_RO) {
12297
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
12298
goto error;
12299
}
12300
12301
if (conn->driver->domainAbortJob) {
12302
int ret;
12303
ret = conn->driver->domainAbortJob(domain);
12304
if (ret < 0)
12305
goto error;
12306
return ret;
12307
}
12308
12309
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12310
12311
error:
12312
virDispatchError(conn);
12313
return -1;
12314
}
12315
12316
12317
/**
12318
* virDomainMigrateSetMaxDowntime:
12319
* @domain: a domain object
12320
* @downtime: maximum tolerable downtime for live migration, in milliseconds
12321
* @flags: fine-tuning flags, currently unused, use 0
12322
*
12323
* Sets maximum tolerable time for which the domain is allowed to be paused
12324
* at the end of live migration. It's supposed to be called while the domain is
12325
* being live-migrated as a reaction to migration progress.
12326
*
12327
* Returns 0 in case of success, -1 otherwise.
12328
*/
12329
int
12330
virDomainMigrateSetMaxDowntime(virDomainPtr domain,
12331
unsigned long long downtime,
12332
unsigned int flags)
12333
{
12334
virConnectPtr conn;
12335
12336
VIR_DOMAIN_DEBUG(domain, "downtime=%llu, flags=%u", downtime, flags);
12337
12338
virResetLastError();
12339
12340
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
12341
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
12342
virDispatchError(NULL);
12343
return -1;
12344
}
12345
12346
conn = domain->conn;
12347
if (conn->flags & VIR_CONNECT_RO) {
12348
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
12349
goto error;
12350
}
12351
12352
if (conn->driver->domainMigrateSetMaxDowntime) {
12353
if (conn->driver->domainMigrateSetMaxDowntime(domain, downtime, flags) < 0)
12354
goto error;
12355
return 0;
12356
}
12357
12358
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12359
error:
12360
virDispatchError(conn);
12361
return -1;
12362
}
12363
12364
/**
12365
* virConnectDomainEventRegisterAny:
12366
* @conn: pointer to the connection
12367
* @dom: pointer to the domain
12368
* @eventID: the event type to receive
12369
* @cb: callback to the function handling domain events
12370
* @opaque: opaque data to pass on to the callback
12371
* @freecb: optional function to deallocate opaque when not used anymore
12372
*
12373
* Adds a callback to receive notifications of arbitrary domain events
12374
* occurring on a domain.
12375
*
12376
* If dom is NULL, then events will be monitored for any domain. If dom
12377
* is non-NULL, then only the specific domain will be monitored
12378
*
12379
* Most types of event have a callback providing a custom set of parameters
12380
* for the event. When registering an event, it is thus neccessary to use
12381
* the VIR_DOMAIN_EVENT_CALLBACK() macro to cast the supplied function pointer
12382
* to match the signature of this method.
12383
*
12384
* The virDomainPtr object handle passed into the callback upon delivery
12385
* of an event is only valid for the duration of execution of the callback.
12386
* If the callback wishes to keep the domain object after the callback
12387
* returns, it shall take a reference to it, by calling virDomainRef.
12388
* The reference can be released once the object is no longer required
12389
* by calling virDomainFree.
12390
*
12391
* The return value from this method is a positive integer identifier
12392
* for the callback. To unregister a callback, this callback ID should
12393
* be passed to the virDomainEventUnregisterAny method
12394
*
12395
* Returns a callback identifier on success, -1 on failure
12396
*/
12397
int
12398
virConnectDomainEventRegisterAny(virConnectPtr conn,
12399
virDomainPtr dom,
12400
int eventID,
12401
virConnectDomainEventGenericCallback cb,
12402
void *opaque,
12403
virFreeCallback freecb)
12404
{
12405
VIR_DOMAIN_DEBUG(dom, "conn=%p, eventID=%d, cb=%p, opaque=%p, freecb=%p",
12406
conn, eventID, cb, opaque, freecb);
12407
12408
virResetLastError();
12409
12410
if (!VIR_IS_CONNECT(conn)) {
12411
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
12412
virDispatchError(NULL);
12413
return -1;
12414
}
12415
if (dom != NULL &&
12416
!(VIR_IS_CONNECTED_DOMAIN(dom) && dom->conn == conn)) {
12417
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
12418
virDispatchError(conn);
12419
return -1;
12420
}
12421
if (eventID < 0 || eventID >= VIR_DOMAIN_EVENT_ID_LAST || cb == NULL) {
12422
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
12423
goto error;
12424
}
12425
12426
if ((conn->driver) && (conn->driver->domainEventRegisterAny)) {
12427
int ret;
12428
ret = conn->driver->domainEventRegisterAny(conn, dom, eventID, cb, opaque, freecb);
12429
if (ret < 0)
12430
goto error;
12431
return ret;
12432
}
12433
12434
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12435
error:
12436
virDispatchError(conn);
12437
return -1;
12438
}
12439
12440
/**
12441
* virConnectDomainEventDeregisterAny:
12442
* @conn: pointer to the connection
12443
* @callbackID: the callback identifier
12444
*
12445
* Removes an event callback. The callbackID parameter should be the
12446
* vaule obtained from a previous virDomainEventRegisterAny method.
12447
*
12448
* Returns 0 on success, -1 on failure
12449
*/
12450
int
12451
virConnectDomainEventDeregisterAny(virConnectPtr conn,
12452
int callbackID)
12453
{
12454
DEBUG("conn=%p, callbackID=%d", conn, callbackID);
12455
12456
virResetLastError();
12457
12458
if (!VIR_IS_CONNECT(conn)) {
12459
virLibConnError(VIR_ERR_INVALID_CONN, __FUNCTION__);
12460
virDispatchError(NULL);
12461
return -1;
12462
}
12463
if (callbackID < 0) {
12464
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
12465
goto error;
12466
}
12467
if ((conn->driver) && (conn->driver->domainEventDeregisterAny)) {
12468
int ret;
12469
ret = conn->driver->domainEventDeregisterAny(conn, callbackID);
12470
if (ret < 0)
12471
goto error;
12472
return ret;
12473
}
12474
12475
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12476
error:
12477
virDispatchError(conn);
12478
return -1;
12479
}
12480
12481
/**
12482
* virDomainManagedSave:
12483
* @dom: pointer to the domain
12484
* @flags: optional flags currently unused
12485
*
12486
* This method will suspend a domain and save its memory contents to
12487
* a file on disk. After the call, if successful, the domain is not
12488
* listed as running anymore.
12489
* The difference from virDomainSave() is that libvirt is keeping track of
12490
* the saved state itself, and will reuse it once the domain is being
12491
* restarted (automatically or via an explicit libvirt call).
12492
* As a result any running domain is sure to not have a managed saved image.
12493
*
12494
* Returns 0 in case of success or -1 in case of failure
12495
*/
12496
int virDomainManagedSave(virDomainPtr dom, unsigned int flags)
12497
{
12498
virConnectPtr conn;
12499
12500
VIR_DOMAIN_DEBUG(dom, "flags=%u", flags);
12501
12502
virResetLastError();
12503
12504
if (!VIR_IS_CONNECTED_DOMAIN(dom)) {
12505
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
12506
virDispatchError(NULL);
12507
return -1;
12508
}
12509
12510
conn = dom->conn;
12511
if (conn->flags & VIR_CONNECT_RO) {
12512
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
12513
goto error;
12514
}
12515
12516
if (conn->driver->domainManagedSave) {
12517
int ret;
12518
12519
ret = conn->driver->domainManagedSave(dom, flags);
12520
if (ret < 0)
12521
goto error;
12522
return ret;
12523
}
12524
12525
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12526
12527
error:
12528
virDispatchError(conn);
12529
return -1;
12530
}
12531
12532
/**
12533
* virDomainHasManagedSaveImage:
12534
* @dom: pointer to the domain
12535
* @flags: optional flags currently unused
12536
*
12537
* Check if a domain has a managed save image as created by
12538
* virDomainManagedSave(). Note that any running domain should not have
12539
* such an image, as it should have been removed on restart.
12540
*
12541
* Returns 0 if no image is present, 1 if an image is present, and
12542
* -1 in case of error
12543
*/
12544
int virDomainHasManagedSaveImage(virDomainPtr dom, unsigned int flags)
12545
{
12546
virConnectPtr conn;
12547
12548
VIR_DOMAIN_DEBUG(dom, "flags=%u", flags);
12549
12550
virResetLastError();
12551
12552
if (!VIR_IS_CONNECTED_DOMAIN(dom)) {
12553
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
12554
virDispatchError(NULL);
12555
return -1;
12556
}
12557
12558
conn = dom->conn;
12559
12560
if (conn->driver->domainHasManagedSaveImage) {
12561
int ret;
12562
12563
ret = conn->driver->domainHasManagedSaveImage(dom, flags);
12564
if (ret < 0)
12565
goto error;
12566
return ret;
12567
}
12568
12569
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12570
12571
error:
12572
virDispatchError(conn);
12573
return -1;
12574
}
12575
12576
/**
12577
* virDomainManagedSaveRemove:
12578
* @dom: pointer to the domain
12579
* @flags: optional flags currently unused
12580
*
12581
* Remove any managed save image for this domain.
12582
*
12583
* Returns 0 in case of success, and -1 in case of error
12584
*/
12585
int virDomainManagedSaveRemove(virDomainPtr dom, unsigned int flags)
12586
{
12587
virConnectPtr conn;
12588
12589
VIR_DOMAIN_DEBUG(dom, "flags=%u", flags);
12590
12591
virResetLastError();
12592
12593
if (!VIR_IS_CONNECTED_DOMAIN(dom)) {
12594
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
12595
virDispatchError(NULL);
12596
return -1;
12597
}
12598
12599
conn = dom->conn;
12600
if (conn->flags & VIR_CONNECT_RO) {
12601
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
12602
goto error;
12603
}
12604
12605
if (conn->driver->domainManagedSaveRemove) {
12606
int ret;
12607
12608
ret = conn->driver->domainManagedSaveRemove(dom, flags);
12609
if (ret < 0)
12610
goto error;
12611
return ret;
12612
}
12613
12614
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12615
12616
error:
12617
virDispatchError(conn);
12618
return -1;
12619
}
12620
12621
/**
12622
* virDomainSnapshotCreateXML:
12623
* @domain: a domain object
12624
* @xmlDesc: string containing an XML description of the domain
12625
* @flags: unused flag parameters; callers should pass 0
12626
*
12627
* Creates a new snapshot of a domain based on the snapshot xml
12628
* contained in xmlDesc.
12629
*
12630
* Returns an (opaque) virDomainSnapshotPtr on success, NULL on failure.
12631
*/
12632
virDomainSnapshotPtr
12633
virDomainSnapshotCreateXML(virDomainPtr domain,
12634
const char *xmlDesc,
12635
unsigned int flags)
12636
{
12637
virConnectPtr conn;
12638
12639
VIR_DOMAIN_DEBUG(domain, "xmlDesc=%s, flags=%u", xmlDesc, flags);
12640
12641
virResetLastError();
12642
12643
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
12644
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
12645
virDispatchError(NULL);
12646
return NULL;
12647
}
12648
12649
conn = domain->conn;
12650
if (conn->flags & VIR_CONNECT_RO) {
12651
virLibConnError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
12652
goto error;
12653
}
12654
12655
if (conn->driver->domainSnapshotCreateXML) {
12656
virDomainSnapshotPtr ret;
12657
ret = conn->driver->domainSnapshotCreateXML(domain, xmlDesc, flags);
12658
if (!ret)
12659
goto error;
12660
return ret;
12661
}
12662
12663
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12664
error:
12665
virDispatchError(conn);
12666
return NULL;
12667
}
12668
12669
/**
12670
* virDomainSnapshotGetXMLDesc:
12671
* @snapshot: a domain snapshot object
12672
* @flags: unused flag parameters; callers should pass 0
12673
*
12674
* Provide an XML description of the domain snapshot.
12675
*
12676
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
12677
* the caller must free() the returned value.
12678
*/
12679
char *
12680
virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,
12681
unsigned int flags)
12682
{
12683
virConnectPtr conn;
12684
DEBUG("snapshot=%p, flags=%d", snapshot, flags);
12685
12686
virResetLastError();
12687
12688
if (!VIR_IS_DOMAIN_SNAPSHOT(snapshot)) {
12689
virLibDomainSnapshotError(VIR_ERR_INVALID_DOMAIN_SNAPSHOT,
12690
__FUNCTION__);
12691
virDispatchError(NULL);
12692
return NULL;
12693
}
12694
12695
conn = snapshot->domain->conn;
12696
12697
if ((conn->flags & VIR_CONNECT_RO) && (flags & VIR_DOMAIN_XML_SECURE)) {
12698
virLibConnError(VIR_ERR_OPERATION_DENIED,
12699
_("virDomainSnapshotGetXMLDesc with secure flag"));
12700
goto error;
12701
}
12702
12703
if (conn->driver->domainSnapshotDumpXML) {
12704
char *ret;
12705
ret = conn->driver->domainSnapshotDumpXML(snapshot, flags);
12706
if (!ret)
12707
goto error;
12708
return ret;
12709
}
12710
12711
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12712
error:
12713
virDispatchError(conn);
12714
return NULL;
12715
}
12716
12717
/**
12718
* virDomainSnapshotNum:
12719
* @domain: a domain object
12720
* @flags: unused flag parameters; callers should pass 0
12721
*
12722
* Provides the number of domain snapshots for this domain..
12723
*
12724
* Returns the number of domain snapshost found or -1 in case of error.
12725
*/
12726
int
12727
virDomainSnapshotNum(virDomainPtr domain, unsigned int flags)
12728
{
12729
virConnectPtr conn;
12730
12731
VIR_DOMAIN_DEBUG0(domain);
12732
12733
virResetLastError();
12734
12735
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
12736
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
12737
virDispatchError(NULL);
12738
return -1;
12739
}
12740
12741
conn = domain->conn;
12742
if (conn->driver->domainSnapshotNum) {
12743
int ret = conn->driver->domainSnapshotNum(domain, flags);
12744
if (ret < 0)
12745
goto error;
12746
return ret;
12747
}
12748
12749
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12750
error:
12751
virDispatchError(conn);
12752
return -1;
12753
}
12754
12755
/**
12756
* virDomainSnapshotListNames:
12757
* @domain: a domain object
12758
* @names: array to collect the list of names of snapshots
12759
* @nameslen: size of @names
12760
* @flags: unused flag parameters; callers should pass 0
12761
*
12762
* Collect the list of domain snapshots for the given domain, and store
12763
* their names in @names. Caller is responsible for freeing each member
12764
* of the array.
12765
*
12766
* Returns the number of domain snapshots found or -1 in case of error.
12767
*/
12768
int
12769
virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen,
12770
unsigned int flags)
12771
{
12772
virConnectPtr conn;
12773
12774
VIR_DOMAIN_DEBUG(domain, "names=%p, nameslen=%d, flags=%u",
12775
names, nameslen, flags);
12776
12777
virResetLastError();
12778
12779
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
12780
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
12781
virDispatchError(NULL);
12782
return -1;
12783
}
12784
12785
conn = domain->conn;
12786
12787
if ((names == NULL) || (nameslen < 0)) {
12788
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
12789
goto error;
12790
}
12791
12792
if (conn->driver->domainSnapshotListNames) {
12793
int ret = conn->driver->domainSnapshotListNames(domain, names,
12794
nameslen, flags);
12795
if (ret < 0)
12796
goto error;
12797
return ret;
12798
}
12799
12800
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12801
error:
12802
virDispatchError(conn);
12803
return -1;
12804
}
12805
12806
/**
12807
* virDomainSnapshotLookupByName:
12808
* @domain: a domain object
12809
* @name: name for the domain snapshot
12810
* @flags: unused flag parameters; callers should pass 0
12811
*
12812
* Try to lookup a domain snapshot based on its name.
12813
*
12814
* Returns a domain snapshot object or NULL in case of failure. If the
12815
* domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT
12816
* error is raised.
12817
*/
12818
virDomainSnapshotPtr
12819
virDomainSnapshotLookupByName(virDomainPtr domain,
12820
const char *name,
12821
unsigned int flags)
12822
{
12823
virConnectPtr conn;
12824
12825
VIR_DOMAIN_DEBUG(domain, "name=%s, flags=%u", name, flags);
12826
12827
virResetLastError();
12828
12829
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
12830
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
12831
virDispatchError(NULL);
12832
return NULL;
12833
}
12834
12835
conn = domain->conn;
12836
12837
if (name == NULL) {
12838
virLibConnError(VIR_ERR_INVALID_ARG, __FUNCTION__);
12839
goto error;
12840
}
12841
12842
if (conn->driver->domainSnapshotLookupByName) {
12843
virDomainSnapshotPtr dom;
12844
dom = conn->driver->domainSnapshotLookupByName(domain, name, flags);
12845
if (!dom)
12846
goto error;
12847
return dom;
12848
}
12849
12850
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12851
error:
12852
virDispatchError(conn);
12853
return NULL;
12854
}
12855
12856
/**
12857
* virDomainHasCurrentSnapshot:
12858
* @domain: pointer to the domain object
12859
* @flags: unused flag parameters; callers should pass 0
12860
*
12861
* Determine if the domain has a current snapshot.
12862
*
12863
* Returns 1 if such snapshot exists, 0 if it doesn't, -1 on error.
12864
*/
12865
int
12866
virDomainHasCurrentSnapshot(virDomainPtr domain, unsigned int flags)
12867
{
12868
virConnectPtr conn;
12869
12870
VIR_DOMAIN_DEBUG(domain, "flags=%u", flags);
12871
12872
virResetLastError();
12873
12874
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
12875
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
12876
virDispatchError(NULL);
12877
return -1;
12878
}
12879
12880
conn = domain->conn;
12881
12882
if (conn->driver->domainHasCurrentSnapshot) {
12883
int ret = conn->driver->domainHasCurrentSnapshot(domain, flags);
12884
if (ret < 0)
12885
goto error;
12886
return ret;
12887
}
12888
12889
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12890
error:
12891
virDispatchError(conn);
12892
return -1;
12893
}
12894
12895
/**
12896
* virDomainSnapshotCurrent:
12897
* @domain: a domain object
12898
* @flags: unused flag parameters; callers should pass 0
12899
*
12900
* Get the current snapshot for a domain, if any.
12901
*
12902
* Returns a domain snapshot object or NULL in case of failure. If the
12903
* current domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT
12904
* error is raised.
12905
*/
12906
virDomainSnapshotPtr
12907
virDomainSnapshotCurrent(virDomainPtr domain,
12908
unsigned int flags)
12909
{
12910
virConnectPtr conn;
12911
12912
VIR_DOMAIN_DEBUG(domain, "flags=%u", flags);
12913
12914
virResetLastError();
12915
12916
if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
12917
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
12918
virDispatchError(NULL);
12919
return NULL;
12920
}
12921
12922
conn = domain->conn;
12923
12924
if (conn->driver->domainSnapshotCurrent) {
12925
virDomainSnapshotPtr snap;
12926
snap = conn->driver->domainSnapshotCurrent(domain, flags);
12927
if (!snap)
12928
goto error;
12929
return snap;
12930
}
12931
12932
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12933
error:
12934
virDispatchError(conn);
12935
return NULL;
12936
}
12937
12938
/**
12939
* virDomainRevertToSnapshot:
12940
* @snapshot: a domain snapshot object
12941
* @flags: unused flag parameters; callers should pass 0
12942
*
12943
* Revert the domain to a given snapshot.
12944
*
12945
* Returns 0 if the creation is successful, -1 on error.
12946
*/
12947
int
12948
virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot,
12949
unsigned int flags)
12950
{
12951
virConnectPtr conn;
12952
12953
DEBUG("snapshot=%p, flags=%u", snapshot, flags);
12954
12955
virResetLastError();
12956
12957
if (!VIR_IS_DOMAIN_SNAPSHOT(snapshot)) {
12958
virLibDomainSnapshotError(VIR_ERR_INVALID_DOMAIN_SNAPSHOT,
12959
__FUNCTION__);
12960
virDispatchError(NULL);
12961
return -1;
12962
}
12963
12964
conn = snapshot->domain->conn;
12965
12966
if (conn->driver->domainRevertToSnapshot) {
12967
int ret = conn->driver->domainRevertToSnapshot(snapshot, flags);
12968
if (ret < 0)
12969
goto error;
12970
return ret;
12971
}
12972
12973
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
12974
error:
12975
virDispatchError(conn);
12976
return -1;
12977
}
12978
12979
/**
12980
* virDomainSnapshotDelete:
12981
* @snapshot: a domain snapshot object
12982
* @flags: flag parameters
12983
*
12984
* Delete the snapshot.
12985
*
12986
* If @flags is 0, then just this snapshot is deleted, and changes from
12987
* this snapshot are automatically merged into children snapshots. If
12988
* flags is VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN, then this snapshot
12989
* and any children snapshots are deleted.
12990
*
12991
* Returns 0 if the snapshot was successfully deleted, -1 on error.
12992
*/
12993
int
12994
virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
12995
unsigned int flags)
12996
{
12997
virConnectPtr conn;
12998
12999
DEBUG("snapshot=%p, flags=%u", snapshot, flags);
13000
13001
virResetLastError();
13002
13003
if (!VIR_IS_DOMAIN_SNAPSHOT(snapshot)) {
13004
virLibDomainSnapshotError(VIR_ERR_INVALID_DOMAIN_SNAPSHOT,
13005
__FUNCTION__);
13006
virDispatchError(NULL);
13007
return -1;
13008
}
13009
13010
conn = snapshot->domain->conn;
13011
13012
if (conn->driver->domainSnapshotDelete) {
13013
int ret = conn->driver->domainSnapshotDelete(snapshot, flags);
13014
if (ret < 0)
13015
goto error;
13016
return ret;
13017
}
13018
13019
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
13020
error:
13021
virDispatchError(conn);
13022
return -1;
13023
}
13024
13025
/**
13026
* virDomainSnapshotFree:
13027
* @snapshot: a domain snapshot object
13028
*
13029
* Free the domain snapshot object. The snapshot itself is not modified.
13030
* The data structure is freed and should not be used thereafter.
13031
*
13032
* Returns 0 in case of success and -1 in case of failure.
13033
*/
13034
int
13035
virDomainSnapshotFree(virDomainSnapshotPtr snapshot)
13036
{
13037
DEBUG("snapshot=%p", snapshot);
13038
13039
virResetLastError();
13040
13041
if (!VIR_IS_DOMAIN_SNAPSHOT(snapshot)) {
13042
virLibDomainSnapshotError(VIR_ERR_INVALID_DOMAIN_SNAPSHOT,
13043
__FUNCTION__);
13044
virDispatchError(NULL);
13045
return -1;
13046
}
13047
if (virUnrefDomainSnapshot(snapshot) < 0) {
13048
virDispatchError(NULL);
13049
return -1;
13050
}
13051
return 0;
13052
}
13053
13054
/**
13055
* virDomainOpenConsole:
13056
* @dom: a domain object
13057
* @devname: the console, serial or parallel port device alias, or NULL
13058
* @st: a stream to associate with the console
13059
* @flags: unused, pass 0
13060
*
13061
* This opens the backend associated with a console, serial or
13062
* parallel port device on a guest, if the backend is supported.
13063
* If the @devname is omitted, then the first console or serial
13064
* device is opened. The console is associated with the passed
13065
* in @st stream, which should have been opened in non-blocking
13066
* mode for bi-directional I/O.
13067
*
13068
* returns 0 if the console was opened, -1 on error
13069
*/
13070
int virDomainOpenConsole(virDomainPtr dom,
13071
const char *devname,
13072
virStreamPtr st,
13073
unsigned int flags)
13074
{
13075
virConnectPtr conn;
13076
13077
VIR_DOMAIN_DEBUG(dom, "devname=%s, st=%p, flags=%u",
13078
NULLSTR(devname), st, flags);
13079
13080
virResetLastError();
13081
13082
if (!VIR_IS_DOMAIN(dom)) {
13083
virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
13084
virDispatchError(NULL);
13085
return -1;
13086
}
13087
13088
conn = dom->conn;
13089
if (conn->flags & VIR_CONNECT_RO) {
13090
virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
13091
goto error;
13092
}
13093
13094
if (conn->driver->domainOpenConsole) {
13095
int ret;
13096
ret = conn->driver->domainOpenConsole(dom, devname, st, flags);
13097
if (ret < 0)
13098
goto error;
13099
return ret;
13100
}
13101
13102
virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
13103
13104
error:
13105
virDispatchError(conn);
13106
return -1;
13107
}
Loggerhead is a web-based interface for Breezy
Version: 2.0.1