</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">Structure <ahref="#virConnect">virConnect</a><br/>struct _virConnect
The content of this structure is not made public by the API.
<preclass="programlisting">unsigned long <ahref="#virConnectGetVersion">virConnectGetVersion</a> (<ahref="libxml-libvir.html#virConnectPtr">virConnectPtr</a> conn)</pre>
<preclass="programlisting">int <ahref="#virConnectListDomains">virConnectListDomains</a> (<ahref="libxml-libvir.html#virConnectPtr">virConnectPtr</a> conn, <br/> int * ids, <br/> int maxids)</pre>
<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>
</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="virConnectGetVersion"id="virConnectGetVersion"></a>Function: virConnectGetVersion</h3><preclass="programlisting">unsigned long virConnectGetVersion (<ahref="libxml-libvir.html#virConnectPtr">virConnectPtr</a> conn)<br/>
</pre><p>Get the version level of the Hypervisor running.</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>-1 in case of error or major * 10,000 + minor * 100 + rev otherwise</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/>
</pre><p>Collect the list of active domains, and store their ID in @maxids</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>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/>
</pre><p></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>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.</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><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>
