Provides APIs for the management of interfaces
typedef enum virConnectListAllInterfacesFlags typedef struct _virInterface virInterface typedef enum virInterfaceDefineFlags typedef virInterface * virInterfacePtr typedef enum virInterfaceXMLFlags
int virConnectListAllInterfaces (virConnectPtr conn,
virInterfacePtr ** ifaces,
unsigned int flags) int virConnectListDefinedInterfaces (virConnectPtr conn,
char ** const names,
int maxnames) int virConnectListInterfaces (virConnectPtr conn,
char ** const names,
int maxnames) int virConnectNumOfDefinedInterfaces (virConnectPtr conn) int virConnectNumOfInterfaces (virConnectPtr conn) int virInterfaceChangeBegin (virConnectPtr conn,
unsigned int flags) int virInterfaceChangeCommit (virConnectPtr conn,
unsigned int flags) int virInterfaceChangeRollback (virConnectPtr conn,
unsigned int flags) int virInterfaceCreate (virInterfacePtr iface,
unsigned int flags) virInterfacePtr virInterfaceDefineXML (virConnectPtr conn,
const char * xml,
unsigned int flags) int virInterfaceDestroy (virInterfacePtr iface,
unsigned int flags) int virInterfaceFree (virInterfacePtr iface) virConnectPtr virInterfaceGetConnect (virInterfacePtr iface) const char * virInterfaceGetMACString (virInterfacePtr iface) const char * virInterfaceGetName (virInterfacePtr iface) char * virInterfaceGetXMLDesc (virInterfacePtr iface,
unsigned int flags) int virInterfaceIsActive (virInterfacePtr iface) virInterfacePtr virInterfaceLookupByMACString (virConnectPtr conn,
const char * macstr) virInterfacePtr virInterfaceLookupByName (virConnectPtr conn,
const char * name) int virInterfaceRef (virInterfacePtr iface) int virInterfaceUndefine (virInterfacePtr iface)
virConnectListAllInterfacesFlags¶Flags used to filter the returned interfaces.
enum virConnectListAllInterfacesFlags {
| VIR_CONNECT_LIST_INTERFACES_INACTIVE | = | 1 (0x1; 1 << 0) | |
| VIR_CONNECT_LIST_INTERFACES_ACTIVE | = | 2 (0x2; 1 << 1) |
}
virInterface¶struct virInterface {
}
virInterfaceDefineFlags¶enum virInterfaceDefineFlags {
| VIR_INTERFACE_DEFINE_VALIDATE | = | 1 (0x1; 1 << 0) | Validate the XML document against schema |
}
virInterfacePtr¶typedef virInterface * virInterfacePtr;a virInterfacePtr is pointer to a virInterface private structure, this is the type used to reference a virtual interface in the API.
virInterfaceXMLFlags¶enum virInterfaceXMLFlags {
| VIR_INTERFACE_XML_INACTIVE | = | 1 (0x1; 1 << 0) | dump inactive interface information |
}
virConnectListAllInterfaces¶int virConnectListAllInterfaces (virConnectPtr conn, virInterfacePtr ** ifaces, unsigned int flags)
Collect the list of interfaces, and allocate an array to store those objects. This API solves the race inherent between virConnectListInterfaces and virConnectListDefinedInterfaces.
Normally, all interfaces are returned; however, flags can be used to filter the results for a smaller list of targeted interfaces. The valid flags are divided into groups, where each group contains bits that describe mutually exclusive attributes of a interface, and where all bits within a group describe all possible interfaces.
The only group of flags is VIR_CONNECT_LIST_INTERFACES_ACTIVE (up) and VIR_CONNECT_LIST_INTERFACES_INACTIVE (down) to filter the interfaces by state.
ifaces to NULL in case of error. On success, the array stored into ifaces 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 virStorageInterfaceFree() on each array element, then calling free() on ifaces.| Object | Permission | Condition |
|---|---|---|
| connect | search-interfaces | - |
| Object | Permission |
|---|---|
| interface | getattr |
virConnectListDefinedInterfaces¶int virConnectListDefinedInterfaces (virConnectPtr conn, char ** const names, int maxnames)
Collect the list of defined (inactive) physical host interfaces, and store their names in names.
The use of this function is discouraged. Instead, use virConnectListAllInterfaces().
namesmaxnames. The client must call free() on each returned name.| Object | Permission | Condition |
|---|---|---|
| connect | search-interfaces | - |
| Object | Permission |
|---|---|
| interface | getattr |
virConnectListInterfaces¶int virConnectListInterfaces (virConnectPtr conn, char ** const names, int maxnames)
Collect the list of active physical host interfaces, and store their names in names
The use of this function is discouraged. Instead, use virConnectListAllInterfaces().
namesmaxnames. The client must call free() on each returned name.| Object | Permission | Condition |
|---|---|---|
| connect | search-interfaces | - |
| Object | Permission |
|---|---|
| interface | getattr |
virConnectNumOfDefinedInterfaces¶int virConnectNumOfDefinedInterfaces (virConnectPtr conn)
Provides the number of defined (inactive) interfaces on the physical host.
| Object | Permission | Condition |
|---|---|---|
| connect | search-interfaces | - |
| Object | Permission |
|---|---|
| interface | getattr |
virConnectNumOfInterfaces¶int virConnectNumOfInterfaces (virConnectPtr conn)
Provides the number of active interfaces on the physical host.
| Object | Permission | Condition |
|---|---|---|
| connect | search-interfaces | - |
| Object | Permission |
|---|---|
| interface | getattr |
virInterfaceChangeBegin¶int virInterfaceChangeBegin (virConnectPtr conn, unsigned int flags)
This function creates a restore point to which one can return later by calling virInterfaceChangeRollback(). This function should be called before any transaction with interface configuration. Once it is known that a new configuration works, it can be committed via virInterfaceChangeCommit(), which frees the restore point.
If virInterfaceChangeBegin() is called when a transaction is already opened, this function will fail, and a VIR_ERR_INVALID_OPERATION will be logged.
| Object | Permission | Condition |
|---|---|---|
| connect | interface-transaction | - |
virInterfaceChangeCommit¶int virInterfaceChangeCommit (virConnectPtr conn, unsigned int flags)
This commits the changes made to interfaces and frees the restore point created by virInterfaceChangeBegin().
If virInterfaceChangeCommit() is called when a transaction is not opened, this function will fail, and a VIR_ERR_INVALID_OPERATION will be logged.
| Object | Permission | Condition |
|---|---|---|
| connect | interface-transaction | - |
virInterfaceChangeRollback¶int virInterfaceChangeRollback (virConnectPtr conn, unsigned int flags)
This cancels changes made to interfaces settings by restoring previous state created by virInterfaceChangeBegin().
If virInterfaceChangeRollback() is called when a transaction is not opened, this function will fail, and a VIR_ERR_INVALID_OPERATION will be logged.
| Object | Permission | Condition |
|---|---|---|
| connect | interface-transaction | - |
virInterfaceCreate¶int virInterfaceCreate (virInterfacePtr iface, unsigned int flags)
Activate an interface (i.e. call "ifup").
If there was an open network config transaction at the time this interface was defined (that is, if virInterfaceChangeBegin() had been called), the interface will be brought back down (and then undefined) if virInterfaceChangeRollback() is called.
virInterfaceDefineXML¶virInterfacePtr virInterfaceDefineXML (virConnectPtr conn, const char * xml, unsigned int flags)
Define an inactive persistent physical host interface or modify an existing persistent one from the XML description.
Normally this change in the interface configuration is immediately permanent/persistent, but if virInterfaceChangeBegin() has been previously called (i.e. if an interface config transaction is open), the new interface definition will only become permanent if virInterfaceChangeCommit() is called prior to the next reboot of the system running libvirtd. Prior to that time, it can be explicitly removed using virInterfaceChangeRollback(), or will be automatically removed during the next reboot of the system running libvirtd.
virInterfaceFree should be used to free the resources after the interface object is no longer needed.
virInterfaceDestroy¶int virInterfaceDestroy (virInterfacePtr iface, unsigned int flags)
deactivate an interface (ie call "ifdown") This does not remove the interface from the config, and does not free the associated virInterfacePtr object.
If there is an open network config transaction at the time this interface is destroyed (that is, if virInterfaceChangeBegin() had been called), and if the interface is later undefined and then virInterfaceChangeRollback() is called, the restoral of the interface definition will also bring the interface back up.
virInterfaceFree¶int virInterfaceFree (virInterfacePtr iface)
Free the interface object. The interface itself is unaltered. The data structure is freed and should not be used thereafter.
virInterfaceGetConnect¶virConnectPtr virInterfaceGetConnect (virInterfacePtr iface)
Provides the connection pointer associated with an interface. The reference counter on the connection is not increased by this call.
virInterfaceGetMACString¶const char * virInterfaceGetMACString (virInterfacePtr iface)
Get the MAC for an interface as string. For more information about MAC see RFC4122.
virInterfaceGetName¶const char * virInterfaceGetName (virInterfacePtr iface)
Get the public name for that interface
virInterfaceGetXMLDesc¶char * virInterfaceGetXMLDesc (virInterfacePtr iface, unsigned int flags)
VIR_INTERFACE_XML_INACTIVE - return the static configuration, suitable for use redefining the interface via virInterfaceDefineXML()
Provide an XML description of the interface. If VIR_INTERFACE_XML_INACTIVE is set, the description may be reused later to redefine the interface with virInterfaceDefineXML(). If it is not set, the ip address and netmask will be the current live setting of the interface, not the settings from the config files.
virInterfaceIsActive¶int virInterfaceIsActive (virInterfacePtr iface)
Determine if the interface is currently running
virInterfaceLookupByMACString¶virInterfacePtr virInterfaceLookupByMACString (virConnectPtr conn, const char * macstr)
Try to lookup an interface on the given hypervisor based on its MAC.
virInterfaceFree should be used to free the resources after the interface object is no longer needed.
virInterfaceLookupByName¶virInterfacePtr virInterfaceLookupByName (virConnectPtr conn, const char * name)
Try to lookup an interface on the given hypervisor based on its name.
virInterfaceFree should be used to free the resources after the interface object is no longer needed.
virInterfaceRef¶int virInterfaceRef (virInterfacePtr iface)
Increment the reference count on the interface. For each additional call to this method, there shall be a corresponding call to virInterfaceFree to release the reference count, once the caller no longer needs the reference to this object.
This method is typically useful for applications where multiple threads are using a connection, and it is required that the connection remain open until all threads have finished using it. ie, each new thread using an interface would increment the reference count.
virInterfaceUndefine¶int virInterfaceUndefine (virInterfacePtr iface)
Undefine an interface, ie remove it from the config. This does not free the associated virInterfacePtr object.
Normally this change in the interface configuration is permanent/persistent, but if virInterfaceChangeBegin() has been previously called (i.e. if an interface config transaction is open), the removal of the interface definition will only become permanent if virInterfaceChangeCommit() is called prior to the next reboot of the system running libvirtd. Prior to that time, the definition can be explicitly restored using virInterfaceChangeRollback(), or will be automatically restored during the next reboot of the system running libvirtd.