diff --git a/ChangeLog b/ChangeLog index ae44ca4c23..b5a1100634 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +Fri Aug 1 08:40:48 CEST 2008 Daniel Veillard + + * docs/formatdomain.html docs/formatdomain.html.in docs/libvirt-api.xml + docs/libvirt-refs.xml docs/html/libvirt-libvirt.html src/libvirt.c: + fixed somedocs and API entry point descriptions as suggested by + Charles Duffy and regenerated the API descriptions. + Fri Aug 1 08:22:08 CEST 2008 Daniel Veillard * src/qemu_driver.c: apply patch from Charles Duffy fixing erro diff --git a/docs/devhelp/libvirt-libvirt.html b/docs/devhelp/libvirt-libvirt.html index 54303c22d9..ba31c012cd 100644 --- a/docs/devhelp/libvirt-libvirt.html +++ b/docs/devhelp/libvirt-libvirt.html @@ -689,11 +689,11 @@ The content of this structure is not made public by the API.
domain:pointer to a defined domain
Returns:0 in case of success, -1 in case of error

virDomainCreateLinux ()

virDomainPtr	virDomainCreateLinux	(virConnectPtr conn, 
					 const char * xmlDesc, 
					 unsigned int flags)

-

Launch a new Linux guest domain, based on an XML description similar to the one returned by virDomainGetXMLDesc() This function may requires privileged access to the hypervisor.

+

Launch a new Linux guest domain, based on an XML description similar to the one returned by virDomainGetXMLDesc() This function may requires privileged access to the hypervisor. The domain is not persistent, so its definition will disappear when it is destroyed, or if the host is restarted (see virDomainDefineXML() to define persistent domains).

conn:pointer to the hypervisor connection
xmlDesc:string containing an XML description of the domain
flags:an optional set of virDomainFlags
Returns:a new domain object or NULL in case of failure

virDomainDefineXML ()

virDomainPtr	virDomainDefineXML	(virConnectPtr conn, 
					 const char * xml)

-

define a domain, but does not start it

+

Define a domain, but does not start it. This definition is persistent, until explicitly undefined with virDomainUndefine().

conn:pointer to the hypervisor connection
xml:the XML description for the domain, preferably in UTF-8
Returns:NULL in case of error, a pointer to the domain otherwise

virDomainDestroy ()

int	virDomainDestroy		(virDomainPtr domain)

@@ -841,7 +841,7 @@ The content of this structure is not made public by the API.
 
domain:a domain object
Returns:0 in case of success and -1 in case of failure.

virDomainUndefine ()

int	virDomainUndefine		(virDomainPtr domain)

-

undefine a domain but does not stop it if it is running

+

Undefine a domain but does not stop it if it is running

domain:pointer to a defined domain
Returns:0 in case of success, -1 in case of error

virGetVersion ()

int	virGetVersion			(unsigned long * libVer, 
					 const char * type, 
					 unsigned long * typeVer)

diff --git a/docs/formatdomain.html b/docs/formatdomain.html
index 80faade33b..2efbeb63dd 100644
--- a/docs/formatdomain.html
+++ b/docs/formatdomain.html
@@ -649,8 +649,10 @@
         
graphics
The graphics element has a mandatory type
 	attribute which takes the value "sdl" or "vnc". The former displays
 	a window on the host desktop, while the latter activates a VNC server.
-	If the latter is used the port attributes specifies the
-	TCP port number (with -1 indicating that it should be auto-allocated).
+	If the latter is used the port attribute specifies the TCP
+	port number (with -1 as legacy syntax indicating that it should be
+	auto-allocated). The autoport attribute is the new
+	preferred syntax for indicating autoallocation of the TCP port to use.
 	The listen attribute is an IP address for the server to
 	listen on. The password attribute provides a VNC password
 	in clear text.

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 70b9c4ac06..71779655b2 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -584,8 +584,10 @@
       
The graphics element has a mandatory type
 	attribute which takes the value "sdl" or "vnc". The former displays
 	a window on the host desktop, while the latter activates a VNC server.
-	If the latter is used the port attributes specifies the
-	TCP port number (with -1 indicating that it should be auto-allocated).
+	If the latter is used the port attribute specifies the TCP
+	port number (with -1 as legacy syntax indicating that it should be
+	auto-allocated). The autoport attribute is the new
+	preferred syntax for indicating autoallocation of the TCP port to use.
 	The listen attribute is an IP address for the server to
 	listen on. The password attribute provides a VNC password
 	in clear text.

diff --git a/docs/html/libvirt-libvirt.html b/docs/html/libvirt-libvirt.html
index b6959b4ebb..e0d04b0e17 100644
--- a/docs/html/libvirt-libvirt.html
+++ b/docs/html/libvirt-libvirt.html
@@ -286,8 +286,8 @@ char *	virStorageVolGetXMLDesc		(
This function returns block device (disk) stats for block devices attached to the domain. The path parameter is the name of the block device. Get this by calling virDomainGetXMLDesc and finding the <target dev='...'> attribute within //domain/devices/disk. (For example, "xvda"). Domains may have more than one block device. To get stats for each you should make multiple calls to this function. Individual fields within the stats structure may be returned as -1, which indicates that the hypervisor does not support that particular statistic.
dom:pointer to the domain object
path:path to the block device
stats:block device stats (returned)
size:size of stats structure
Returns:0 in case of success or -1 in case of failure.
virDomainCoreDump
int	virDomainCoreDump		(virDomainPtr domain, 
					 const char * to, 
					 int flags)

 
This method will dump the core of a domain on a given file for analysis. Note that for remote Xen Daemon the file path will be interpreted in the remote host.
domain:a domain object
to:path for the core file
flags:extra flags, currently unused
Returns:0 in case of success and -1 in case of failure.
virDomainCreate
int	virDomainCreate			(virDomainPtr domain)

 
launch a defined domain. If the call succeed the domain moves from the defined to the running domains pools.
domain:pointer to a defined domain
Returns:0 in case of success, -1 in case of error
virDomainCreateLinux
virDomainPtr	virDomainCreateLinux	(virConnectPtr conn, 
					 const char * xmlDesc, 
					 unsigned int flags)

-
Launch a new Linux guest domain, based on an XML description similar to the one returned by virDomainGetXMLDesc() This function may requires privileged access to the hypervisor.
conn:pointer to the hypervisor connection
xmlDesc:string containing an XML description of the domain
flags:an optional set of virDomainFlags
Returns:a new domain object or NULL in case of failure
virDomainDefineXML
virDomainPtr	virDomainDefineXML	(virConnectPtr conn, 
					 const char * xml)

-
define a domain, but does not start it
conn:pointer to the hypervisor connection
xml:the XML description for the domain, preferably in UTF-8
Returns:NULL in case of error, a pointer to the domain otherwise
virDomainDestroy
int	virDomainDestroy		(virDomainPtr domain)

+
Launch a new Linux guest domain, based on an XML description similar to the one returned by virDomainGetXMLDesc() This function may requires privileged access to the hypervisor. The domain is not persistent, so its definition will disappear when it is destroyed, or if the host is restarted (see virDomainDefineXML() to define persistent domains).
conn:pointer to the hypervisor connection
xmlDesc:string containing an XML description of the domain
flags:an optional set of virDomainFlags
Returns:a new domain object or NULL in case of failure
virDomainDefineXML
virDomainPtr	virDomainDefineXML	(virConnectPtr conn, 
					 const char * xml)

+
Define a domain, but does not start it. This definition is persistent, until explicitly undefined with virDomainUndefine().
conn:pointer to the hypervisor connection
xml:the XML description for the domain, preferably in UTF-8
Returns:NULL in case of error, a pointer to the domain otherwise
virDomainDestroy
int	virDomainDestroy		(virDomainPtr domain)

 
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. This does not free the associated virDomainPtr object. This function may require privileged access
domain:a domain object
Returns:0 in case of success and -1 in case of failure.
virDomainDetachDevice
int	virDomainDetachDevice		(virDomainPtr domain, 
					 const char * xml)

 
Destroy a virtual device attachment to backend.
domain:pointer to domain object
xml:pointer to XML description of one device
Returns:0 in case of success, -1 in case of failure.
virDomainFree
int	virDomainFree			(virDomainPtr domain)

 
Free the domain object. The running instance is kept alive. The data structure is freed and should not be used thereafter.
domain:a domain object
Returns:0 in case of success and -1 in case of failure.
virDomainGetAutostart
int	virDomainGetAutostart		(virDomainPtr domain, 
					 int * autostart)

@@ -324,7 +324,7 @@ char *	virStorageVolGetXMLDesc		(
Dynamically change the number of virtual CPUs used by the domain. Note that this call may fail if the underlying virtualization hypervisor does not support it or if growing the number is arbitrary limited. This function requires privileged access to the hypervisor.
domain:pointer to domain object, or NULL for Domain0
nvcpus:the new number of virtual CPUs for this domain
Returns:0 in case of success, -1 in case of failure.
virDomainShutdown
int	virDomainShutdown		(virDomainPtr domain)

 
Shutdown a domain, the domain object is still usable there after but the domain OS is being stopped. Note that the guest OS may ignore the request. TODO: should we add an option for reboot, knowing it may not be doable in the general case ?
domain:a domain object
Returns:0 in case of success and -1 in case of failure.
virDomainSuspend
int	virDomainSuspend		(virDomainPtr domain)

 
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. This function may requires privileged access.
domain:a domain object
Returns:0 in case of success and -1 in case of failure.
virDomainUndefine
int	virDomainUndefine		(virDomainPtr domain)

-
undefine a domain but does not stop it if it is running
domain:pointer to a defined domain
Returns:0 in case of success, -1 in case of error
virGetVersion
int	virGetVersion			(unsigned long * libVer, 
					 const char * type, 
					 unsigned long * typeVer)

+
Undefine a domain but does not stop it if it is running
domain:pointer to a defined domain
Returns:0 in case of success, -1 in case of error
virGetVersion
int	virGetVersion			(unsigned long * libVer, 
					 const char * type, 
					 unsigned long * typeVer)

 
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 available, an error code will be returned and @typeVer will be 0.
libVer:return value for the library version (OUT)
type:the type of connection/driver looked at
typeVer:return value for the version of the hypervisor (OUT)
Returns:-1 in case of failure, 0 otherwise, and values for @libVer and @typeVer have the format major * 1,000,000 + minor * 1,000 + release.
virInitialize
int	virInitialize			(void)

 
Initialize the library. It's better to call this routine at startup in multithreaded applications to avoid potential race when initializing the library.
Returns:0 in case of success, -1 in case of error
virNetworkCreate
int	virNetworkCreate		(virNetworkPtr network)

 
Create and start a defined network. If the call succeed the network moves from the defined to the running networks pools.
network:pointer to a defined network
Returns:0 in case of success, -1 in case of error
virNetworkCreateXML
virNetworkPtr	virNetworkCreateXML	(virConnectPtr conn, 
					 const char * xmlDesc)

diff --git a/docs/libvirt-api.xml b/docs/libvirt-api.xml
index 136ba0d756..a8b0361435 100644
--- a/docs/libvirt-api.xml
+++ b/docs/libvirt-api.xml
@@ -854,14 +854,14 @@ see note above'/>
       
     
     
-      Launch a new Linux guest domain, based on an XML description similar to the one returned by virDomainGetXMLDesc() This function may requires privileged access to the hypervisor.
+      Launch a new Linux guest domain, based on an XML description similar to the one returned by virDomainGetXMLDesc() This function may requires privileged access to the hypervisor. The domain is not persistent, so its definition will disappear when it is destroyed, or if the host is restarted (see virDomainDefineXML() to define persistent domains).
       
       
       
       
     
     
-      define a domain, but does not start it
+      Define a domain, but does not start it. This definition is persistent, until explicitly undefined with virDomainUndefine().
       
       
       
@@ -1088,7 +1088,7 @@ see note above'/>
       
     
     
-      undefine a domain but does not stop it if it is running
+      Undefine a domain but does not stop it if it is running
       
       
     
diff --git a/docs/libvirt-refs.xml b/docs/libvirt-refs.xml
index 9504755e50..d5ed07ff4d 100644
--- a/docs/libvirt-refs.xml
+++ b/docs/libvirt-refs.xml
@@ -1420,6 +1420,7 @@
           
         
         
+          
           
           
         
@@ -1813,6 +1814,7 @@
           
         
         
+          
           
           
         
@@ -2610,7 +2612,7 @@
           
         
         
-          
+          
         
         
           
@@ -2624,6 +2626,8 @@
           
         
         
+          
+          
           
         
         
@@ -2656,6 +2660,7 @@
           
         
         
+          
           
           
         
@@ -2687,6 +2692,7 @@
           
         
         
+          
           
         
         
@@ -2733,6 +2739,7 @@
           
           
           
+          
           
           
         
@@ -2818,6 +2825,7 @@
           
         
         
+          
           
         
         
@@ -3162,6 +3170,7 @@
         
           
           
+          
           
           
           
@@ -3329,6 +3338,7 @@
           
         
         
+          
           
           
           
@@ -4012,6 +4022,8 @@
           
         
         
+          
+          
           
           
           
@@ -4274,6 +4286,7 @@
           
         
         
+          
           
           
           
@@ -4398,6 +4411,7 @@
         
         
           
+          
           
           
           
@@ -4806,10 +4820,8 @@
     
     
       
-        
-          
-        
         
+          
           
         
         
@@ -4844,6 +4856,7 @@
           
         
         
+          
           
         
         
@@ -5002,6 +5015,9 @@
         
           
         
+        
+          
+        
         
           
           
@@ -5049,6 +5065,9 @@
         
           
         
+        
+          
+        
         
           
           
@@ -5141,6 +5160,8 @@
           
         
       
+    
+    
       
         
           
@@ -5161,6 +5182,7 @@
           
         
         
+          
           
           
           
@@ -5222,6 +5244,7 @@
           
           
           
+          
           
           
           
@@ -5283,8 +5306,6 @@
           
         
       
-    
-    
       
         
           
@@ -5327,8 +5348,8 @@
       
       
       
-      
-      
+      
+      
     
   
 
diff --git a/src/libvirt.c b/src/libvirt.c
index 434ab69a05..1bbe92adf0 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -1217,6 +1217,9 @@ virDomainGetConnect (virDomainPtr dom)
  * Launch a new Linux guest domain, based on an XML description similar
  * to the one returned by virDomainGetXMLDesc()
  * This function may requires privileged access to the hypervisor.
+ * The domain is not persistent, so its definition will disappear when it
+ * is destroyed, or if the host is restarted (see virDomainDefineXML() to
+ * define persistent domains).
  *
  * Returns a new domain object or NULL in case of failure
  */
@@ -2778,7 +2781,9 @@ virDomainMemoryPeek (virDomainPtr dom,
  * @conn: pointer to the hypervisor connection
  * @xml: the XML description for the domain, preferably in UTF-8
  *
- * define a domain, but does not start it
+ * Define a domain, but does not start it.
+ * This definition is persistent, until explicitly undefined with
+ * virDomainUndefine().
  *
  * Returns NULL in case of error, a pointer to the domain otherwise
  */
@@ -2810,7 +2815,7 @@ virDomainDefineXML(virConnectPtr conn, const char *xml) {
  * virDomainUndefine:
  * @domain: pointer to a defined domain
  *
- * undefine a domain but does not stop it if it is running
+ * Undefine a domain but does not stop it if it is running
  *
  * Returns 0 in case of success, -1 in case of error
  */