</style><title>Module libvir from libvir</title></head><bodybgcolor="#8b7765"text="#000000"link="#a06060"vlink="#000000"><tableborder="0"width="100%"cellpadding="5"cellspacing="0"align="center"><tr><tdwidth="120"><ahref="http://www.redhat.com/"><imgsrc="../redhat.gif"alt="Red Hat Logo"/></a></td><td><tableborder="0"width="90%"cellpadding="2"cellspacing="0"align="center"bgcolor="#000000"><tr><td><tablewidth="100%"border="0"cellspacing="1"cellpadding="3"bgcolor="#fffacd"><tr><tdalign="center"><h1></h1><h2>Module libvir from libvir</h2></td></tr></table></td></tr></table></td></tr></table><tableborder="0"cellpadding="4"cellspacing="0"width="100%"align="center"><tr><tdbgcolor="#8b7765"><tableborder="0"cellspacing="0"cellpadding="2"width="100%"><tr><tdvalign="top"width="200"bgcolor="#8b7765"><tableborder="0"cellspacing="0"cellpadding="1"width="100%"bgcolor="#000000"><tr><td><tablewidth="100%"border="0"cellspacing="1"cellpadding="3"><tr><tdcolspan="1"bgcolor="#eecfa1"align="center"><center><b>API Menu</b></center></td></tr><tr><tdbgcolor="#fffacd"><formaction="../search.php"enctype="application/x-www-form-urlencoded"method="get"><inputname="query"type="text"size="20"value=""/><inputname="submit"type="submit"value="Search ..."/></form><ul><li><astyle="font-weight:bold"href="../index.html">Main Menu</a></li><li><astyle="font-weight:bold"href="index.html">API Menu</a></li><li><ahref="../ChangeLog.html">ChangeLog</a></li></ul></td></tr></table><tablewidth="100%"border="0"cellspacing="1"cellpadding="3"><tr><tdcolspan="1"bgcolor="#eecfa1"align="center"><center><b>API Indexes</b></center></td></tr><tr><tdbgcolor="#fffacd"><ul><li><ahref="../APIchunk0.html">Alphabetic</a></li><li><ahref="../APIconstructors.html">Constructors</a></li><li><ahref="../APIfunctions.html">Functions/Types</a></li><li><ahref="../APIfiles.html">Modules</a></li><li><ahref="../APIsymbols.html">Symbols</a></li></ul></td></tr></table><tablewidth="100%"border="0"cellspacing="1"cellpadding="3"><tr><tdcolspan="1"bgcolor="#eecfa1"align="center"><center><b>Related links</b></center></td></tr><tr><tdbgcolor="#fffacd"><ul><li><ahref="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><ahref="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li></ul></td></tr></table></td></tr></table></td><tdvalign="top"bgcolor="#8b7765"><tableborder="0"cellspacing="0"cellpadding="1"width="100%"><tr><td><tableborder="0"cellspacing="0"cellpadding="1"width="100%"bgcolor="#000000"><tr><td><tableborder="0"cellpadding="3"cellspacing="1"width="100%"><tr><tdbgcolor="#fffacd"><tableclass="navigation"width="100%"summary="Navigation header"cellpadding="2"cellspacing="2"><trvalign="middle"><td><aaccesskey="u"href="index.html"><imgsrc="up.png"width="24"height="24"border="0"alt="Up"/></a></td><thalign="left"><ahref="index.html">API documentation</a></th><td><aaccesskey="h"href="../index.html"><imgsrc="home.png"width="24"height="24"border="0"alt="Home"/></a></td><thalign="center"><ahref="../index.html">The XML C parser and toolkit of Gnome</a></th></tr></table><p>Provides the interfaces of the libvir library to handle Xen domains from a process running in domain 0 </p><h2>Table of Contents</h2><preclass="programlisting">#define <ahref="#LIBVIR_VERSION_NUMBER">LIBVIR_VERSION_NUMBER</a></pre><preclass="programlisting">Structure <ahref="#virConnect">virConnect</a><br/>struct _virConnect
<preclass="programlisting">unsigned int <ahref="#virDomainGetID">virDomainGetID</a> (<ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> domain)</pre>
<preclass="programlisting">unsigned long <ahref="#virDomainGetMaxMemory">virDomainGetMaxMemory</a> (<ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> domain)</pre>
<h3><aname="LIBVIR_VERSION_NUMBER"id="LIBVIR_VERSION_NUMBER"></a>Macro: LIBVIR_VERSION_NUMBER</h3><pre>#define LIBVIR_VERSION_NUMBER</pre><p>Macro providing the version of the library as version * 1,000,000 + minor * 1000 + micro</p>
</pre><p>This function closes the connection to the Hypervisor. This should not be called if further interaction with the Hypervisor are needed especially if there is running domain which need further monitoring by the application.</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>conn</tt></i>:</span></td><td>pointer to the hypervisor connection</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>0 in case of success or -1 in case of error.</td></tr></tbody></table></div><h3><aname="virConnectGetType"id="virConnectGetType"></a>Function: virConnectGetType</h3><preclass="programlisting">const char * virConnectGetType (<ahref="libxml-libvir.html#virConnectPtr">virConnectPtr</a> conn)<br/>
</pre><p>Get the name of the Hypervisor software used.</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>conn</tt></i>:</span></td><td>pointer to the hypervisor connection</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>NULL in case of error, a static zero terminated string otherwise.</td></tr></tbody></table></div><h3><aname="virConnectGetVersion"id="virConnectGetVersion"></a>Function: virConnectGetVersion</h3><preclass="programlisting">int virConnectGetVersion (<ahref="libxml-libvir.html#virConnectPtr">virConnectPtr</a> conn, <br/> unsigned long * hvVer)<br/>
</pre><p>Get the version level of the Hypervisor running. This may work only with hypervisor call, i.e. with priviledged access to the hypervisor, not with a Read-Only connection.</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>conn</tt></i>:</span></td><td>pointer to the hypervisor connection</td></tr><tr><td><spanclass="term"><i><tt>hvVer</tt></i>:</span></td><td>return value for the version of the running hypervisor (OUT)</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>-1 in case of error, 0 otherwise. if the version can't be extracted by lack of capacities returns 0 and @hvVer is 0, otherwise @hvVer value is major * 1,000,000 + minor * 1,000 + release</td></tr></tbody></table></div><h3><aname="virConnectListDomains"id="virConnectListDomains"></a>Function: virConnectListDomains</h3><preclass="programlisting">int virConnectListDomains (<ahref="libxml-libvir.html#virConnectPtr">virConnectPtr</a> conn, <br/> int * ids, <br/> int maxids)<br/>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>conn</tt></i>:</span></td><td>pointer to the hypervisor connection</td></tr><tr><td><spanclass="term"><i><tt>ids</tt></i>:</span></td><td>array to collect the list of IDs of active domains</td></tr><tr><td><spanclass="term"><i><tt>maxids</tt></i>:</span></td><td>size of @ids</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>the number of domain found or -1 in case of error</td></tr></tbody></table></div><h3><aname="virConnectNumOfDomains"id="virConnectNumOfDomains"></a>Function: virConnectNumOfDomains</h3><preclass="programlisting">int virConnectNumOfDomains (<ahref="libxml-libvir.html#virConnectPtr">virConnectPtr</a> conn)<br/>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>conn</tt></i>:</span></td><td>pointer to the hypervisor connection</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>the number of domain found or -1 in case of error</td></tr></tbody></table></div><h3><aname="virConnectOpen"id="virConnectOpen"></a>Function: virConnectOpen</h3><preclass="programlisting"><ahref="libxml-libvir.html#virConnectPtr">virConnectPtr</a> virConnectOpen (const char * name)<br/>
</pre><p>This function should be called first to get a connection to the Hypervisor and xen store</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>name</tt></i>:</span></td><td>optional argument currently unused, pass NULL</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>a pointer to the hypervisor connection or NULL in case of error</td></tr></tbody></table></div><h3><aname="virConnectOpenReadOnly"id="virConnectOpenReadOnly"></a>Function: virConnectOpenReadOnly</h3><preclass="programlisting"><ahref="libxml-libvir.html#virConnectPtr">virConnectPtr</a> virConnectOpenReadOnly (const char * name)<br/>
</pre><p>This function should be called first to get a read-only connection to the xen store. The set of APIs usable are then restricted.</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>name</tt></i>:</span></td><td>optional argument currently unused, pass NULL</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>a pointer to the hypervisor connection or NULL in case of error</td></tr></tbody></table></div><h3><aname="virDomainCreateLinux"id="virDomainCreateLinux"></a>Function: virDomainCreateLinux</h3><preclass="programlisting"><ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> virDomainCreateLinux (<ahref="libxml-libvir.html#virConnectPtr">virConnectPtr</a> conn, <br/> const char * kernel_path, <br/> const char * initrd_path, <br/> const char * cmdline, <br/> unsigned long memory, <br/> unsigned int flags)<br/>
</pre><p>Launch a new Linux guest domain</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>conn</tt></i>:</span></td><td>pointer to the hypervisor connection</td></tr><tr><td><spanclass="term"><i><tt>kernel_path</tt></i>:</span></td><td>the file path to the kernel image</td></tr><tr><td><spanclass="term"><i><tt>initrd_path</tt></i>:</span></td><td>an optional file path to an initrd</td></tr><tr><td><spanclass="term"><i><tt>cmdline</tt></i>:</span></td><td>optional command line parameters for the kernel</td></tr><tr><td><spanclass="term"><i><tt>memory</tt></i>:</span></td><td>the memory size in kilobytes</td></tr><tr><td><spanclass="term"><i><tt>flags</tt></i>:</span></td><td>an optional set of <ahref="libxml-libvir.html#virDomainFlags">virDomainFlags</a></td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>a new domain object or NULL in case of failure</td></tr></tbody></table></div><h3><aname="virDomainDestroy"id="virDomainDestroy"></a>Function: virDomainDestroy</h3><preclass="programlisting">int virDomainDestroy (<ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> domain)<br/>
</pre><p>Destroy the domain object. The running instance is shutdown if not down already and all resources used by it are given back to the hypervisor. The data structure is freed and should not be used thereafter if the call does not return an error.</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>domain</tt></i>:</span></td><td>a domain object</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>0 in case of success and -1 in case of failure.</td></tr></tbody></table></div><h3><aname="virDomainGetID"id="virDomainGetID"></a>Function: virDomainGetID</h3><preclass="programlisting">unsigned int virDomainGetID (<ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> domain)<br/>
</pre><p>Get the hypervisor ID number for the domain</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>domain</tt></i>:</span></td><td>a domain object</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>the domain ID number or (unsigned int) -1 in case of error</td></tr></tbody></table></div><h3><aname="virDomainGetInfo"id="virDomainGetInfo"></a>Function: virDomainGetInfo</h3><preclass="programlisting">int virDomainGetInfo (<ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> domain, <br/><ahref="libxml-libvir.html#virDomainInfoPtr">virDomainInfoPtr</a> info)<br/>
</pre><p>Extract information about a domain. Note that if the connection used to get the domain is limited only a partial set of the informations can be extracted.</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>domain</tt></i>:</span></td><td>a domain object or NULL</td></tr><tr><td><spanclass="term"><i><tt>info</tt></i>:</span></td><td>pointer to a <ahref="libxml-libvir.html#virDomainInfo">virDomainInfo</a> structure allocated by the user</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>0 in case of success and -1 in case of failure.</td></tr></tbody></table></div><h3><aname="virDomainGetMaxMemory"id="virDomainGetMaxMemory"></a>Function: virDomainGetMaxMemory</h3><preclass="programlisting">unsigned long virDomainGetMaxMemory (<ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> domain)<br/>
</pre><p>Retrieve the maximum amount of physical memory allocated to a domain. If domain is NULL, then this get the amount of memory reserved to Domain0 i.e. the domain where the application runs.</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>domain</tt></i>:</span></td><td>a domain object or NULL</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>the memory size in kilobytes or 0 in case of error.</td></tr></tbody></table></div><h3><aname="virDomainGetName"id="virDomainGetName"></a>Function: virDomainGetName</h3><preclass="programlisting">const char * virDomainGetName (<ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> domain)<br/>
</pre><p>Get the public name for that domain</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>domain</tt></i>:</span></td><td>a domain object</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>a pointer to the name or NULL, the string need not be deallocated its lifetime will be the same as the domain object.</td></tr></tbody></table></div><h3><aname="virDomainLookupByID"id="virDomainLookupByID"></a>Function: virDomainLookupByID</h3><preclass="programlisting"><ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> virDomainLookupByID (<ahref="libxml-libvir.html#virConnectPtr">virConnectPtr</a> conn, <br/> int id)<br/>
</pre><p>Try to find a domain based on the hypervisor ID number</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>conn</tt></i>:</span></td><td>pointer to the hypervisor connection</td></tr><tr><td><spanclass="term"><i><tt>id</tt></i>:</span></td><td>the domain ID number</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>a new domain object or NULL in case of failure</td></tr></tbody></table></div><h3><aname="virDomainLookupByName"id="virDomainLookupByName"></a>Function: virDomainLookupByName</h3><preclass="programlisting"><ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> virDomainLookupByName (<ahref="libxml-libvir.html#virConnectPtr">virConnectPtr</a> conn, <br/> const char * name)<br/>
</pre><p>Try to lookup a domain on the given hypervisor</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>conn</tt></i>:</span></td><td>pointer to the hypervisor connection</td></tr><tr><td><spanclass="term"><i><tt>name</tt></i>:</span></td><td>name for the domain</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>a new domain object or NULL in case of failure</td></tr></tbody></table></div><h3><aname="virDomainResume"id="virDomainResume"></a>Function: virDomainResume</h3><preclass="programlisting">int virDomainResume (<ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> domain)<br/>
</pre><p>Resume an suspended domain, the process is restarted from the state where it was frozen by calling virSuspendDomain().</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>domain</tt></i>:</span></td><td>a domain object</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>0 in case of success and -1 in case of failure.</td></tr></tbody></table></div><h3><aname="virDomainSetMaxMemory"id="virDomainSetMaxMemory"></a>Function: virDomainSetMaxMemory</h3><preclass="programlisting">int virDomainSetMaxMemory (<ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> domain, <br/> unsigned long memory)<br/>
</pre><p>Dynamically change the maximum amount of physical memory allocated to a domain. If domain is NULL, then this change the amount of memory reserved to Domain0 i.e. the domain where the application runs.</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>domain</tt></i>:</span></td><td>a domain object or NULL</td></tr><tr><td><spanclass="term"><i><tt>memory</tt></i>:</span></td><td>the memory size in kilobytes</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>0 in case of success and -1 in case of failure.</td></tr></tbody></table></div><h3><aname="virDomainSuspend"id="virDomainSuspend"></a>Function: virDomainSuspend</h3><preclass="programlisting">int virDomainSuspend (<ahref="libxml-libvir.html#virDomainPtr">virDomainPtr</a> domain)<br/>
</pre><p>Suspends an active domain, the process is frozen without further access to CPU resources and I/O but the memory used by the domain at the hypervisor level will stay allocated. Use virDomainResume() to reactivate the domain.</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>domain</tt></i>:</span></td><td>a domain object</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>0 in case of success and -1 in case of failure.</td></tr></tbody></table></div><h3><aname="virGetVersion"id="virGetVersion"></a>Function: virGetVersion</h3><preclass="programlisting">int virGetVersion (unsigned long * libVer, <br/> const char * type, <br/> unsigned long * typeVer)<br/>
</pre><p>Provides two information back, @libVer is the version of the library while @typeVer will be the version of the hypervisor type @type against which the library was compiled. If @type is NULL, "Xen" is assumed, if @type is unknown or not availble, an error code will be returned and @typeVer will be 0.</p>
<divclass="variablelist"><tableborder="0"><colalign="left"/><tbody><tr><td><spanclass="term"><i><tt>libVer</tt></i>:</span></td><td>return value for the library version (OUT)</td></tr><tr><td><spanclass="term"><i><tt>type</tt></i>:</span></td><td>hypervisor type</td></tr><tr><td><spanclass="term"><i><tt>typeVer</tt></i>:</span></td><td>return value for the version of the hypervisor (OUT)</td></tr><tr><td><spanclass="term"><i><tt>Returns</tt></i>:</span></td><td>-1 in case of failure, 0 otherwise, and values for @libVer and @typeVer have the format major * 1,000,000 + minor * 1,000 + release.</td></tr></tbody></table></div><p><ahref="../bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
