/** * virNWFilterBindingDelete: * @binding: a binding object * * Delete the binding object. This does not free the * associated virNWFilterBindingPtr object. This API * may be used to remove the network port binding filter * currently in use for the guest while the guest is * running without needing to restart the guest. Restoring * the network port binding filter for the running guest * would be accomplished by using virNWFilterBindingCreateXML. * * Returns 0 in case of success and -1 in case of failure. */ int virNWFilterBindingDelete(virNWFilterBindingPtr binding) { virConnectPtr conn; VIR_DEBUG("binding=%p", binding); virResetLastError(); virCheckNWFilterBindingReturn(binding, -1); conn = binding->conn; virCheckReadOnlyGoto(conn->flags, error); if (conn->nwfilterDriver && conn->nwfilterDriver->nwfilterBindingDelete) { int ret; ret = conn->nwfilterDriver->nwfilterBindingDelete(binding); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(binding->conn); return -1; }
/** * virDomainSnapshotGetXMLDesc: * @snapshot: a domain snapshot object * @flags: bitwise-OR of supported virDomainSnapshotXMLFlags * * Provide an XML description of the domain snapshot, with a top-level * element of <domainsnapshot>. * * No security-sensitive data will be included unless @flags contains * VIR_DOMAIN_SNAPSHOT_XML_SECURE; this flag is rejected on read-only * connections. * * Returns a 0 terminated UTF-8 encoded XML instance or NULL in case * of error. The caller must free() the returned value. */ char * virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot, unsigned int flags) { virConnectPtr conn; VIR_DEBUG("snapshot=%p, flags=0x%x", snapshot, flags); virResetLastError(); virCheckDomainSnapshotReturn(snapshot, NULL); conn = snapshot->domain->conn; if ((conn->flags & VIR_CONNECT_RO) && (flags & VIR_DOMAIN_SNAPSHOT_XML_SECURE)) { virReportError(VIR_ERR_OPERATION_DENIED, "%s", _("virDomainSnapshotGetXMLDesc with secure flag")); goto error; } if (conn->driver->domainSnapshotGetXMLDesc) { char *ret; ret = conn->driver->domainSnapshotGetXMLDesc(snapshot, flags); if (!ret) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return NULL; }
/** * virDomainSnapshotListChildrenNames: * @snapshot: a domain snapshot object * @names: array to collect the list of names of snapshots * @nameslen: size of @names * @flags: bitwise-OR of supported virDomainSnapshotListFlags * * Collect the list of domain snapshots that are children of the given * snapshot, and store their names in @names. The value to use for * @nameslen can be determined by virDomainSnapshotNumChildren() with * the same @flags. * * If @flags lacks VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS or contains * VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL, and no other connection is * modifying snapshots, then it is guaranteed that for any snapshot in * the resulting list, no snapshots later in the list can be reached * by a sequence of virDomainSnapshotGetParent() starting from that * earlier snapshot; otherwise, the order of snapshots in the * resulting list is unspecified. * * By default, this command covers only direct children. It is also * possible to expand things to cover all descendants, when @flags * includes VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Additional filters * are provided via the same @flags values as documented in * virDomainSnapshotListAllChildren(). * * Note that this command is inherently racy: another connection can * define a new snapshot between a call to virDomainSnapshotNumChildren() * and this call. You are only guaranteed that all currently defined * snapshots were listed if the return is less than @nameslen. Likewise, * you should be prepared for virDomainSnapshotLookupByName() to fail when * converting a name from this call into a snapshot object, if another * connection deletes the snapshot in the meantime. For more control over * the results, see virDomainSnapshotListAllChildren(). * * Returns the number of domain snapshots found or -1 in case of error. * The caller is responsible to call free() for each member of the array. */ int virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot, char **names, int nameslen, unsigned int flags) { virConnectPtr conn; VIR_DEBUG("snapshot=%p, names=%p, nameslen=%d, flags=0x%x", snapshot, names, nameslen, flags); virResetLastError(); virCheckDomainSnapshotReturn(snapshot, -1); conn = snapshot->domain->conn; virCheckNonNullArgGoto(names, error); virCheckNonNegativeArgGoto(nameslen, error); if (conn->driver->domainSnapshotListChildrenNames) { int ret = conn->driver->domainSnapshotListChildrenNames(snapshot, names, nameslen, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return -1; }
/** * virDomainQemuAttach: * @conn: pointer to a hypervisor connection * @pid_value: the UNIX process ID of the external QEMU process * @flags: optional flags, currently unused * * This API is QEMU specific, so it will only work with hypervisor * connections to the QEMU driver. * * This API will attach to an externally launched QEMU process * identified by @pid. There are several requirements to successfully * attach to an external QEMU process: * * - It must have been started with a monitor socket using the UNIX * domain socket protocol. * - No device hotplug/unplug, or other configuration changes can * have been made via the monitor since it started. * - The '-name' and '-uuid' arguments should have been set (not * mandatory, but strongly recommended) * * To date, the only platforms we know of where pid_t is larger than * unsigned int (64-bit Windows) also lack UNIX sockets, so the choice * of @pid_value as an unsigned int should not present any difficulties. * * If successful, then the guest will appear in the list of running * domains for this connection, and other APIs should operate * normally (provided the above requirements were honored). * * Returns a new domain object on success, NULL otherwise */ virDomainPtr virDomainQemuAttach(virConnectPtr conn, unsigned int pid_value, unsigned int flags) { pid_t pid = pid_value; VIR_DEBUG("conn=%p, pid=%u, flags=%x", conn, pid_value, flags); virResetLastError(); virCheckConnectReturn(conn, NULL); virCheckPositiveArgGoto(pid_value, error); if (pid != pid_value) { virReportInvalidArg(pid_value, _("pid_value in %s is too large"), __FUNCTION__); goto error; } virCheckReadOnlyGoto(conn->flags, error); if (conn->driver->domainQemuAttach) { virDomainPtr ret; ret = conn->driver->domainQemuAttach(conn, pid_value, flags); if (!ret) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return NULL; }
/** * virDomainQemuMonitorCommand: * @domain: a domain object * @cmd: the qemu monitor command string * @result: a string returned by @cmd * @flags: bitwise-or of supported virDomainQemuMonitorCommandFlags * * This API is QEMU specific, so it will only work with hypervisor * connections to the QEMU driver. * * Send an arbitrary monitor command @cmd to @domain through the * qemu monitor. There are several requirements to safely and * successfully use this API: * * - A @cmd that queries state without making any modifications is safe * - A @cmd that alters state that is also tracked by libvirt is unsafe, * and may cause libvirtd to crash * - A @cmd that alters state not tracked by the current version of * libvirt is possible as a means to test new qemu features before * they have support in libvirt, but no guarantees are made to safety * * If VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP is set, the command is * considered to be a human monitor command and libvirt will automatically * convert it into QMP if needed. In that case the @result will also * be converted back from QMP. * * If successful, @result will be filled with the string output of the * @cmd, and the caller must free this string. * * Returns 0 in case of success, -1 in case of failure * */ int virDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd, char **result, unsigned int flags) { virConnectPtr conn; VIR_DOMAIN_DEBUG(domain, "cmd=%s, result=%p, flags=%x", cmd, result, flags); virResetLastError(); virCheckDomainReturn(domain, -1); conn = domain->conn; virCheckNonNullArgGoto(result, error); virCheckReadOnlyGoto(conn->flags, error); if (conn->driver->domainQemuMonitorCommand) { int ret; ret = conn->driver->domainQemuMonitorCommand(domain, cmd, result, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return -1; }
/** * virNodeDeviceDetachFlags: * @dev: pointer to the node device * @driverName: name of backend driver that will be used * for later device assignment to a domain. NULL * means "use the hypervisor default driver" * @flags: extra flags; not used yet, so callers should always pass 0 * * Detach the node device from the node itself so that it may be * assigned to a guest domain. * * Depending on the hypervisor, this may involve operations such as * unbinding any device drivers from the device, binding the device to * a dummy device driver and resetting the device. Different backend * drivers expect the device to be bound to different dummy * devices. For example, QEMU's "kvm" backend driver (the default) * expects the device to be bound to "pci-stub", but its "vfio" * backend driver expects the device to be bound to "vfio-pci". * * If the device is currently in use by the node, this method may * fail. * * Once the device is not assigned to any guest, it may be re-attached * to the node using the virNodeDeviceReAttach() method. * * Returns 0 in case of success, -1 in case of failure. */ int virNodeDeviceDetachFlags(virNodeDevicePtr dev, const char *driverName, unsigned int flags) { VIR_DEBUG("dev=%p, conn=%p driverName=%s flags=%x", dev, dev ? dev->conn : NULL, driverName ? driverName : "(default)", flags); virResetLastError(); virCheckNodeDeviceReturn(dev, -1); virCheckReadOnlyGoto(dev->conn->flags, error); if (dev->conn->driver->nodeDeviceDetachFlags) { int ret; ret = dev->conn->driver->nodeDeviceDetachFlags(dev, driverName, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(dev->conn); return -1; }
/** * virNodeDeviceDestroy: * @dev: a device object * * Destroy the device object. The virtual device (only works for vHBA * currently) is removed from the host operating system. This function * may require privileged access. * * Returns 0 in case of success and -1 in case of failure. */ int virNodeDeviceDestroy(virNodeDevicePtr dev) { VIR_DEBUG("dev=%p", dev); virResetLastError(); virCheckNodeDeviceReturn(dev, -1); virCheckReadOnlyGoto(dev->conn->flags, error); if (dev->conn->nodeDeviceDriver && dev->conn->nodeDeviceDriver->nodeDeviceDestroy) { int retval = dev->conn->nodeDeviceDriver->nodeDeviceDestroy(dev); if (retval < 0) { goto error; } return 0; } virReportUnsupportedError(); error: virDispatchError(dev->conn); return -1; }
/** * virNetworkDefineXML: * @conn: pointer to the hypervisor connection * @xml: the XML description for the network, preferably in UTF-8 * * Define an inactive persistent virtual network or modify an existing * persistent one from the XML description. * * virNetworkFree should be used to free the resources after the * network object is no longer needed. * * Returns NULL in case of error, a pointer to the network otherwise */ virNetworkPtr virNetworkDefineXML(virConnectPtr conn, const char *xml) { VIR_DEBUG("conn=%p, xml=%s", conn, NULLSTR(xml)); virResetLastError(); virCheckConnectReturn(conn, NULL); virCheckReadOnlyGoto(conn->flags, error); virCheckNonNullArgGoto(xml, error); if (conn->networkDriver && conn->networkDriver->networkDefineXML) { virNetworkPtr ret; ret = conn->networkDriver->networkDefineXML(conn, xml); if (!ret) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return NULL; }
/** * virNetworkUpdate: * @network: pointer to a defined network * @section: which section of the network to update * (see virNetworkUpdateSection for descriptions) * @command: what action to perform (add/delete/modify) * (see virNetworkUpdateCommand for descriptions) * @parentIndex: which parent element, if there are multiple parents * of the same type (e.g. which <ip> element when modifying * a <dhcp>/<host> element), or "-1" for "don't care" or * "automatically find appropriate one". * @xml: the XML description for the network, preferably in UTF-8 * @flags: bitwise OR of virNetworkUpdateFlags. * * Update the definition of an existing network, either its live * running state, its persistent configuration, or both. * * Returns 0 in case of success, -1 in case of error */ int virNetworkUpdate(virNetworkPtr network, unsigned int command, /* virNetworkUpdateCommand */ unsigned int section, /* virNetworkUpdateSection */ int parentIndex, const char *xml, unsigned int flags) { virConnectPtr conn; VIR_DEBUG("network=%p, section=%d, parentIndex=%d, xml=%s, flags=0x%x", network, section, parentIndex, xml, flags); virResetLastError(); virCheckNetworkReturn(network, -1); conn = network->conn; virCheckReadOnlyGoto(conn->flags, error); virCheckNonNullArgGoto(xml, error); if (conn->networkDriver && conn->networkDriver->networkUpdate) { int ret; ret = conn->networkDriver->networkUpdate(network, section, command, parentIndex, xml, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(network->conn); return -1; }
/** * virNetworkGetDHCPLeases: * @network: Pointer to network object * @mac: Optional ASCII formatted MAC address of an interface * @leases: Pointer to a variable to store the array containing details on * obtained leases, or NULL if the list is not required (just returns * number of leases). * @flags: Extra flags, not used yet, so callers should always pass 0 * * For DHCPv4, the information returned: * - Network Interface Name * - Expiry Time * - MAC address * - IAID (NULL) * - IPv4 address (with type and prefix) * - Hostname (can be NULL) * - Client ID (can be NULL) * * For DHCPv6, the information returned: * - Network Interface Name * - Expiry Time * - MAC address * - IAID (can be NULL, only in rare cases) * - IPv6 address (with type and prefix) * - Hostname (can be NULL) * - Client DUID * * Note: @mac, @iaid, @ipaddr, @clientid are in ASCII form, not raw bytes. * Note: @expirytime can 0, in case the lease is for infinite time. * * The API fetches leases info of guests in the specified network. If the * optional parameter @mac is specified, the returned list will contain only * lease info about a specific guest interface with @mac. There can be * multiple leases for a single @mac because this API supports DHCPv6 too. * * Returns the number of leases found or -1 and sets @leases to NULL in * case of error. On success, the array stored into @leases is guaranteed to * have an extra allocated element set to NULL but not included in the return * count, to make iteration easier. The caller is responsible for calling * virNetworkDHCPLeaseFree() on each array element, then calling free() on @leases. * * See also virNetworkGetDHCPLeasesForMAC() as a convenience for filtering * the list to a single MAC address. * * Example of usage: * * virNetworkDHCPLeasePtr *leases = NULL; * virNetworkPtr network = ... obtain a network pointer here ...; * size_t i; * int nleases; * unsigned int flags = 0; * * nleases = virNetworkGetDHCPLeases(network, NULL, &leases, flags); * if (nleases < 0) * error(); * * ... do something with returned values, for example: * * for (i = 0; i < nleases; i++) { * virNetworkDHCPLeasePtr lease = leases[i]; * * printf("Time(epoch): %lu, MAC address: %s, " * "IP address: %s, Hostname: %s, ClientID: %s\n", * lease->expirytime, lease->mac, lease->ipaddr, * lease->hostname, lease->clientid); * * virNetworkDHCPLeaseFree(leases[i]); * } * * free(leases); * */ int virNetworkGetDHCPLeases(virNetworkPtr network, const char *mac, virNetworkDHCPLeasePtr **leases, unsigned int flags) { virConnectPtr conn; VIR_DEBUG("network=%p, mac='%s' leases=%p, flags=0x%x", network, NULLSTR(mac), leases, flags); virResetLastError(); if (leases) *leases = NULL; virCheckNetworkReturn(network, -1); conn = network->conn; if (conn->networkDriver && conn->networkDriver->networkGetDHCPLeases) { int ret; ret = conn->networkDriver->networkGetDHCPLeases(network, mac, leases, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(network->conn); return -1; }
/** * virConnectListDefinedNetworks: * @conn: pointer to the hypervisor connection * @names: pointer to an array to store the names * @maxnames: size of the array * * list the inactive networks, stores the pointers to the names in @names * * For more control over the results, see virConnectListAllNetworks(). * * Returns the number of names provided in the array or -1 in case of error. * Note that this command is inherently racy; a network can be defined between * a call to virConnectNumOfDefinedNetworks() and this call; you are only * guaranteed that all currently defined networks were listed if the return * is less than @maxnames. The client must call free() on each returned name. */ int virConnectListDefinedNetworks(virConnectPtr conn, char **const names, int maxnames) { VIR_DEBUG("conn=%p, names=%p, maxnames=%d", conn, names, maxnames); virResetLastError(); virCheckConnectReturn(conn, -1); virCheckNonNullArgGoto(names, error); virCheckNonNegativeArgGoto(maxnames, error); if (conn->networkDriver && conn->networkDriver->connectListDefinedNetworks) { int ret; ret = conn->networkDriver->connectListDefinedNetworks(conn, names, maxnames); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return -1; }
/** * virConnectNetworkEventDeregisterAny: * @conn: pointer to the connection * @callbackID: the callback identifier * * Removes an event callback. The callbackID parameter should be the * value obtained from a previous virConnectNetworkEventRegisterAny() method. * * Returns 0 on success, -1 on failure */ int virConnectNetworkEventDeregisterAny(virConnectPtr conn, int callbackID) { VIR_DEBUG("conn=%p, callbackID=%d", conn, callbackID); virResetLastError(); virCheckConnectReturn(conn, -1); virCheckNonNegativeArgGoto(callbackID, error); if (conn->networkDriver && conn->networkDriver->connectNetworkEventDeregisterAny) { int ret; ret = conn->networkDriver->connectNetworkEventDeregisterAny(conn, callbackID); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return -1; }
/** * virConnectListAllNWFilters: * @conn: Pointer to the hypervisor connection. * @filters: Pointer to a variable to store the array containing the network * filter objects or NULL if the list is not required (just returns * number of network filters). * @flags: extra flags; not used yet, so callers should always pass 0 * * Collect the list of network filters, and allocate an array to store those * objects. * * Returns the number of network filters found or -1 and sets @filters to NULL * in case of error. On success, the array stored into @filters is guaranteed to * have an extra allocated element set to NULL but not included in the return count, * to make iteration easier. The caller is responsible for calling * virNWFilterFree() on each array element, then calling free() on @filters. */ int virConnectListAllNWFilters(virConnectPtr conn, virNWFilterPtr **filters, unsigned int flags) { VIR_DEBUG("conn=%p, filters=%p, flags=0x%x", conn, filters, flags); virResetLastError(); if (filters) *filters = NULL; virCheckConnectReturn(conn, -1); if (conn->nwfilterDriver && conn->nwfilterDriver->connectListAllNWFilters) { int ret; ret = conn->nwfilterDriver->connectListAllNWFilters(conn, filters, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return -1; }
/** * virNWFilterBindingGetXMLDesc: * @binding: a binding object * @flags: extra flags; not used yet, so callers should always pass 0 * * Provide an XML description of the network filter. The description may be * reused later to redefine the network filter with virNWFilterCreateXML(). * * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error. * the caller must free() the returned value. */ char * virNWFilterBindingGetXMLDesc(virNWFilterBindingPtr binding, unsigned int flags) { virConnectPtr conn; VIR_DEBUG("binding=%p, flags=0x%x", binding, flags); virResetLastError(); virCheckNWFilterBindingReturn(binding, NULL); conn = binding->conn; if (conn->nwfilterDriver && conn->nwfilterDriver->nwfilterBindingGetXMLDesc) { char *ret; ret = conn->nwfilterDriver->nwfilterBindingGetXMLDesc(binding, flags); if (!ret) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(binding->conn); return NULL; }
/** * virNodeDeviceLookupSCSIHostByWWN: * @conn: pointer to the hypervisor connection * @wwnn: WWNN of the SCSI Host. * @wwpn: WWPN of the SCSI Host. * @flags: extra flags; not used yet, so callers should always pass 0 * * Lookup SCSI Host which is capable with 'fc_host' by its WWNN and WWPN. * * virNodeDeviceFree should be used to free the resources after the * node device object is no longer needed. * * Returns a virNodeDevicePtr if found, NULL otherwise. */ virNodeDevicePtr virNodeDeviceLookupSCSIHostByWWN(virConnectPtr conn, const char *wwnn, const char *wwpn, unsigned int flags) { VIR_DEBUG("conn=%p, wwnn=%p, wwpn=%p, flags=%x", conn, wwnn, wwpn, flags); virResetLastError(); virCheckConnectReturn(conn, NULL); virCheckNonNullArgGoto(wwnn, error); virCheckNonNullArgGoto(wwpn, error); if (conn->nodeDeviceDriver && conn->nodeDeviceDriver->nodeDeviceLookupSCSIHostByWWN) { virNodeDevicePtr ret; ret = conn->nodeDeviceDriver->nodeDeviceLookupSCSIHostByWWN(conn, wwnn, wwpn, flags); if (!ret) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return NULL; }
/** * virNetworkGetXMLDesc: * @network: a network object * @flags: bitwise-OR of virNetworkXMLFlags * * Provide an XML description of the network. The description may be reused * later to relaunch the network with virNetworkCreateXML(). * * Normally, if a network included a physical function, the output includes * all virtual functions tied to that physical interface. If @flags includes * VIR_NETWORK_XML_INACTIVE, then the expansion of virtual interfaces is * not performed. * * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error. * the caller must free() the returned value. */ char * virNetworkGetXMLDesc(virNetworkPtr network, unsigned int flags) { virConnectPtr conn; VIR_DEBUG("network=%p, flags=0x%x", network, flags); virResetLastError(); virCheckNetworkReturn(network, NULL); conn = network->conn; if (conn->networkDriver && conn->networkDriver->networkGetXMLDesc) { char *ret; ret = conn->networkDriver->networkGetXMLDesc(network, flags); if (!ret) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(network->conn); return NULL; }
/** * virNodeDeviceListCaps: * @dev: the device * @names: array to collect the list of capability names * @maxnames: size of @names * * Lists the names of the capabilities supported by the device. * * Returns the number of capability names listed in @names or -1 * in case of error. */ int virNodeDeviceListCaps(virNodeDevicePtr dev, char **const names, int maxnames) { VIR_DEBUG("dev=%p, conn=%p, names=%p, maxnames=%d", dev, dev ? dev->conn : NULL, names, maxnames); virResetLastError(); virCheckNodeDeviceReturn(dev, -1); virCheckNonNullArgGoto(names, error); virCheckNonNegativeArgGoto(maxnames, error); if (dev->conn->nodeDeviceDriver && dev->conn->nodeDeviceDriver->nodeDeviceListCaps) { int ret; ret = dev->conn->nodeDeviceDriver->nodeDeviceListCaps(dev, names, maxnames); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(dev->conn); return -1; }
/** * virNetworkGetBridgeName: * @network: a network object * * Provides a bridge interface name to which a domain may connect * a network interface in order to join the network. * * Returns a 0 terminated interface name, or NULL in case of error. * the caller must free() the returned value. */ char * virNetworkGetBridgeName(virNetworkPtr network) { virConnectPtr conn; VIR_DEBUG("network=%p", network); virResetLastError(); virCheckNetworkReturn(network, NULL); conn = network->conn; if (conn->networkDriver && conn->networkDriver->networkGetBridgeName) { char *ret; ret = conn->networkDriver->networkGetBridgeName(network); if (!ret) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(network->conn); return NULL; }
/** * virNodeDeviceCreateXML: * @conn: pointer to the hypervisor connection * @xmlDesc: string containing an XML description of the device to be created * @flags: extra flags; not used yet, so callers should always pass 0 * * Create a new device on the VM host machine, for example, virtual * HBAs created using vport_create. * * virNodeDeviceFree should be used to free the resources after the * node device object is no longer needed. * * Returns a node device object if successful, NULL in case of failure */ virNodeDevicePtr virNodeDeviceCreateXML(virConnectPtr conn, const char *xmlDesc, unsigned int flags) { VIR_DEBUG("conn=%p, xmlDesc=%s, flags=%x", conn, xmlDesc, flags); virResetLastError(); virCheckConnectReturn(conn, NULL); virCheckReadOnlyGoto(conn->flags, error); virCheckNonNullArgGoto(xmlDesc, error); if (conn->nodeDeviceDriver && conn->nodeDeviceDriver->nodeDeviceCreateXML) { virNodeDevicePtr dev = conn->nodeDeviceDriver->nodeDeviceCreateXML(conn, xmlDesc, flags); if (dev == NULL) goto error; return dev; } virReportUnsupportedError(); error: virDispatchError(conn); return NULL; }
/** * virConnectListAllNetworks: * @conn: Pointer to the hypervisor connection. * @nets: Pointer to a variable to store the array containing the network * objects or NULL if the list is not required (just returns number * of networks). * @flags: bitwise-OR of virConnectListAllNetworksFlags. * * Collect the list of networks, and allocate an array to store those * objects. This API solves the race inherent between virConnectListNetworks * and virConnectListDefinedNetworks. * * Normally, all networks are returned; however, @flags can be used to * filter the results for a smaller list of targeted networks. The valid * flags are divided into groups, where each group contains bits that * describe mutually exclusive attributes of a network, and where all bits * within a group describe all possible networks. * * The first group of @flags is VIR_CONNECT_LIST_NETWORKS_ACTIVE (up) and * VIR_CONNECT_LIST_NETWORKS_INACTIVE (down) to filter the networks by state. * * The second group of @flags is VIR_CONNECT_LIST_NETWORKS_PERSISTENT (defined) * and VIR_CONNECT_LIST_NETWORKS_TRANSIENT (running but not defined), to filter * the networks by whether they have persistent config or not. * * The third group of @flags is VIR_CONNECT_LIST_NETWORKS_AUTOSTART * and VIR_CONNECT_LIST_NETWORKS_NO_AUTOSTART, to filter the networks by * whether they are marked as autostart or not. * * Returns the number of networks found or -1 and sets @nets to NULL in case * of error. On success, the array stored into @nets is guaranteed to have an * extra allocated element set to NULL but not included in the return count, * to make iteration easier. The caller is responsible for calling * virNetworkFree() on each array element, then calling free() on @nets. */ int virConnectListAllNetworks(virConnectPtr conn, virNetworkPtr **nets, unsigned int flags) { VIR_DEBUG("conn=%p, nets=%p, flags=0x%x", conn, nets, flags); virResetLastError(); if (nets) *nets = NULL; virCheckConnectReturn(conn, -1); if (conn->networkDriver && conn->networkDriver->connectListAllNetworks) { int ret; ret = conn->networkDriver->connectListAllNetworks(conn, nets, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return -1; }
int virSecurityManagerVerify(virSecurityManagerPtr mgr, virDomainDefPtr def) { virSecurityLabelDefPtr secdef; if (mgr == NULL || mgr->drv == NULL) return 0; /* NULL model == dynamic labelling, with whatever driver * is active, so we can short circuit verify check to * avoid drivers de-referencing NULLs by accident */ secdef = virDomainDefGetSecurityLabelDef(def, mgr->drv->name); if (secdef == NULL || secdef->model == NULL) return 0; if (mgr->drv->domainSecurityVerify) { int ret; virObjectLock(mgr); ret = mgr->drv->domainSecurityVerify(mgr, def); virObjectUnlock(mgr); return ret; } virReportUnsupportedError(); return -1; }
/** * virNetworkSetAutostart: * @network: a network object * @autostart: whether the network should be automatically started 0 or 1 * * Configure the network to be automatically started * when the host machine boots. * * Returns -1 in case of error, 0 in case of success */ int virNetworkSetAutostart(virNetworkPtr network, int autostart) { virConnectPtr conn; VIR_DEBUG("network=%p, autostart=%d", network, autostart); virResetLastError(); virCheckNetworkReturn(network, -1); conn = network->conn; virCheckReadOnlyGoto(conn->flags, error); if (conn->networkDriver && conn->networkDriver->networkSetAutostart) { int ret; ret = conn->networkDriver->networkSetAutostart(network, autostart); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(network->conn); return -1; }
/** * virDomainQemuAgentCommand: * @domain: a domain object * @cmd: the guest agent command string * @timeout: timeout seconds * @flags: execution flags * * Execute an arbitrary Guest Agent command. * * Issue @cmd to the guest agent running in @domain. * @timeout must be -2, -1, 0 or positive. * VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK(-2): meaning to block forever waiting for * a result. * VIR_DOMAIN_QEMU_AGENT_COMMAND_DEFAULT(-1): use default timeout value. * VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT(0): does not wait. * positive value: wait for @timeout seconds * * Returns strings if success, NULL in failure. */ char * virDomainQemuAgentCommand(virDomainPtr domain, const char *cmd, int timeout, unsigned int flags) { virConnectPtr conn; char *ret; VIR_DOMAIN_DEBUG(domain, "cmd=%s, timeout=%d, flags=%x", cmd, timeout, flags); virResetLastError(); virCheckDomainReturn(domain, NULL); conn = domain->conn; virCheckReadOnlyGoto(conn->flags, error); if (conn->driver->domainQemuAgentCommand) { ret = conn->driver->domainQemuAgentCommand(domain, cmd, timeout, flags); if (!ret) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return NULL; }
/** * virDomainLxcOpenNamespace: * @domain: a domain object * @fdlist: pointer to an array to be filled with FDs * @flags: currently unused, pass 0 * * This API is LXC specific, so it will only work with hypervisor * connections to the LXC driver. * * Open the namespaces associated with the container @domain. * The @fdlist array will be allocated to a suitable size, * and filled with file descriptors for the namespaces. It * is the caller's responsibility to close the file descriptors * * The returned file descriptors are intended to be used with * the setns() system call. * * Returns the number of opened file descriptors, or -1 on error */ int virDomainLxcOpenNamespace(virDomainPtr domain, int **fdlist, unsigned int flags) { virConnectPtr conn; VIR_DOMAIN_DEBUG(domain, "fdlist=%p flags=%x", fdlist, flags); virResetLastError(); virCheckDomainReturn(domain, -1); conn = domain->conn; virCheckNonNullArgGoto(fdlist, error); virCheckReadOnlyGoto(conn->flags, error); if (conn->driver->domainLxcOpenNamespace) { int ret; ret = conn->driver->domainLxcOpenNamespace(domain, fdlist, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return -1; }
/** * virDomainSnapshotDelete: * @snapshot: a domain snapshot object * @flags: bitwise-OR of supported virDomainSnapshotDeleteFlags * * Delete the snapshot. * * If @flags is 0, then just this snapshot is deleted, and changes * from this snapshot are automatically merged into children * snapshots. If @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN, * then this snapshot and any descendant snapshots are deleted. If * @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY, then any * descendant snapshots are deleted, but this snapshot remains. These * two flags are mutually exclusive. * * If @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_METADATA_ONLY, then * any snapshot metadata tracked by libvirt is removed while keeping * the snapshot contents intact; if a hypervisor does not require any * libvirt metadata to track snapshots, then this flag is silently * ignored. * * Returns 0 if the selected snapshot(s) were successfully deleted, * -1 on error. */ int virDomainSnapshotDelete(virDomainSnapshotPtr snapshot, unsigned int flags) { virConnectPtr conn; VIR_DEBUG("snapshot=%p, flags=0x%x", snapshot, flags); virResetLastError(); virCheckDomainSnapshotReturn(snapshot, -1); conn = snapshot->domain->conn; virCheckReadOnlyGoto(conn->flags, error); VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN, VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY, error); if (conn->driver->domainSnapshotDelete) { int ret = conn->driver->domainSnapshotDelete(snapshot, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return -1; }
/** * virConnectListAllNodeDevices: * @conn: Pointer to the hypervisor connection. * @devices: Pointer to a variable to store the array containing the node * device objects or NULL if the list is not required (just returns * number of node devices). * @flags: bitwise-OR of virConnectListAllNodeDevices. * * Collect the list of node devices, and allocate an array to store those * objects. * * Normally, all node devices are returned; however, @flags can be used to * filter the results for a smaller list of targeted node devices. The valid * flags are divided into groups, where each group contains bits that * describe mutually exclusive attributes of a node device, and where all bits * within a group describe all possible node devices. * * Only one group of the @flags is provided to filter the node devices by * capability type, flags include: * VIR_CONNECT_LIST_NODE_DEVICES_CAP_SYSTEM * VIR_CONNECT_LIST_NODE_DEVICES_CAP_PCI_DEV * VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_DEV * VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_INTERFACE * VIR_CONNECT_LIST_NODE_DEVICES_CAP_NET * VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_HOST * VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_TARGET * VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI * VIR_CONNECT_LIST_NODE_DEVICES_CAP_STORAGE * VIR_CONNECT_LIST_NODE_DEVICES_CAP_FC_HOST * VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPORTS * VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_GENERIC * * Returns the number of node devices found or -1 and sets @devices to NULL in * case of error. On success, the array stored into @devices is guaranteed to * have an extra allocated element set to NULL but not included in the return * count, to make iteration easier. The caller is responsible for calling * virNodeDeviceFree() on each array element, then calling free() on * @devices. */ int virConnectListAllNodeDevices(virConnectPtr conn, virNodeDevicePtr **devices, unsigned int flags) { VIR_DEBUG("conn=%p, devices=%p, flags=%x", conn, devices, flags); virResetLastError(); if (devices) *devices = NULL; virCheckConnectReturn(conn, -1); if (conn->nodeDeviceDriver && conn->nodeDeviceDriver->connectListAllNodeDevices) { int ret; ret = conn->nodeDeviceDriver->connectListAllNodeDevices(conn, devices, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return -1; }
/** * virDomainListAllSnapshots: * @domain: a domain object * @snaps: pointer to variable to store the array containing snapshot objects * or NULL if the list is not required (just returns number of * snapshots) * @flags: bitwise-OR of supported virDomainSnapshotListFlags * * Collect the list of domain snapshots for the given domain and allocate * an array to store those objects. This API solves the race inherent in * virDomainSnapshotListNames(). * * If @flags contains VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL and @snaps * is non-NULL, and no other connection is modifying snapshots, then * it is guaranteed that for any snapshot in the resulting list, no * snapshots later in the list can be reached by a sequence of * virDomainSnapshotGetParent() starting from that earlier snapshot; * otherwise, the order of snapshots in the resulting list is * unspecified. * * By default, this command covers all snapshots. It is also possible * to limit things to just snapshots with no parents, when @flags * includes VIR_DOMAIN_SNAPSHOT_LIST_ROOTS. Additional filters are * provided in groups listed below. Within a group, bits are mutually * exclusive, where all possible snapshots are described by exactly * one bit from the group. Some hypervisors might reject particular * flags where it cannot make a distinction for filtering. If the set * of filter flags selected forms an impossible combination, the * hypervisor may return either 0 or an error. * * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that * have no further children (a leaf snapshot). * * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on * whether they have metadata that would prevent the removal of the last * reference to a domain. * * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE, * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY, * for filtering snapshots based on what domain state is tracked by the * snapshot. * * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on * whether the snapshot is stored inside the disk images or as * additional files. * * Returns the number of domain snapshots found or -1 and sets @snaps to * NULL in case of error. On success, the array stored into @snaps is * guaranteed to have an extra allocated element set to NULL but not included * in the return count, to make iteration easier. The caller is responsible * for calling virDomainSnapshotFree() on each array element, then calling * free() on @snaps. */ int virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps, unsigned int flags) { virConnectPtr conn; VIR_DOMAIN_DEBUG(domain, "snaps=%p, flags=0x%x", snaps, flags); virResetLastError(); if (snaps) *snaps = NULL; virCheckDomainReturn(domain, -1); conn = domain->conn; if (conn->driver->domainListAllSnapshots) { int ret = conn->driver->domainListAllSnapshots(domain, snaps, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return -1; }
/** * virNodeListDevices: * @conn: pointer to the hypervisor connection * @cap: capability name * @names: array to collect the list of node device names * @maxnames: size of @names * @flags: extra flags; not used yet, so callers should always pass 0 * * Collect the list of node devices, and store their names in @names * * For more control over the results, see virConnectListAllNodeDevices(). * * If the optional 'cap' argument is non-NULL, then the count * will be restricted to devices with the specified capability * * Returns the number of node devices found or -1 in case of error */ int virNodeListDevices(virConnectPtr conn, const char *cap, char **const names, int maxnames, unsigned int flags) { VIR_DEBUG("conn=%p, cap=%s, names=%p, maxnames=%d, flags=%x", conn, cap, names, maxnames, flags); virResetLastError(); virCheckConnectReturn(conn, -1); virCheckNonNullArgGoto(names, error); virCheckNonNegativeArgGoto(maxnames, error); if (conn->nodeDeviceDriver && conn->nodeDeviceDriver->nodeListDevices) { int ret; ret = conn->nodeDeviceDriver->nodeListDevices(conn, cap, names, maxnames, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return -1; }
/** * virDomainSnapshotListAllChildren: * @snapshot: a domain snapshot object * @snaps: pointer to variable to store the array containing snapshot objects * or NULL if the list is not required (just returns number of * snapshots) * @flags: bitwise-OR of supported virDomainSnapshotListFlags * * Collect the list of domain snapshots that are children of the given * snapshot, and allocate an array to store those objects. This API solves * the race inherent in virDomainSnapshotListChildrenNames(). * * If @flags lacks VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS or contains * VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL, @snaps is non-NULL, and no * other connection is modifying snapshots, then it is guaranteed that * for any snapshot in the resulting list, no snapshots later in the * list can be reached by a sequence of virDomainSnapshotGetParent() * starting from that earlier snapshot; otherwise, the order of * snapshots in the resulting list is unspecified. * * By default, this command covers only direct children. It is also * possible to expand things to cover all descendants, when @flags * includes VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Additional filters * are provided via the remaining @flags values as documented in * virDomainListAllSnapshots(), with the exception that * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS is not supported (in fact, * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS has the same bit value but * opposite semantics of widening rather than narrowing the listing). * * Returns the number of domain snapshots found or -1 and sets @snaps to * NULL in case of error. On success, the array stored into @snaps is * guaranteed to have an extra allocated element set to NULL but not included * in the return count, to make iteration easier. The caller is responsible * for calling virDomainSnapshotFree() on each array element, then calling * free() on @snaps. */ int virDomainSnapshotListAllChildren(virDomainSnapshotPtr snapshot, virDomainSnapshotPtr **snaps, unsigned int flags) { virConnectPtr conn; VIR_DEBUG("snapshot=%p, snaps=%p, flags=0x%x", snapshot, snaps, flags); virResetLastError(); if (snaps) *snaps = NULL; virCheckDomainSnapshotReturn(snapshot, -1); conn = snapshot->domain->conn; if (conn->driver->domainSnapshotListAllChildren) { int ret = conn->driver->domainSnapshotListAllChildren(snapshot, snaps, flags); if (ret < 0) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return -1; }
/** * virNWFilterBindingCreateXML: * @conn: pointer to the hypervisor connection * @xml: an XML description of the binding * @flags: currently unused, pass 0 * * Define a new network filter, based on an XML description * similar to the one returned by virNWFilterGetXMLDesc(). This * API may be used to associate a filter with a currently running * guest that does not have a filter defined for a specific network * port. Since the bindings are generally automatically managed by * the hypervisor, using this command to define a filter for a network * port and then starting the guest afterwards may prevent the guest * from starting if it attempts to use the network port and finds a * filter already defined. * * virNWFilterFree should be used to free the resources after the * binding object is no longer needed. * * Returns a new binding object or NULL in case of failure */ virNWFilterBindingPtr virNWFilterBindingCreateXML(virConnectPtr conn, const char *xml, unsigned int flags) { VIR_DEBUG("conn=%p, xml=%s", conn, NULLSTR(xml)); virResetLastError(); virCheckConnectReturn(conn, NULL); virCheckNonNullArgGoto(xml, error); virCheckReadOnlyGoto(conn->flags, error); if (conn->nwfilterDriver && conn->nwfilterDriver->nwfilterBindingCreateXML) { virNWFilterBindingPtr ret; ret = conn->nwfilterDriver->nwfilterBindingCreateXML(conn, xml, flags); if (!ret) goto error; return ret; } virReportUnsupportedError(); error: virDispatchError(conn); return NULL; }