From: Peter Krempa <pkrempa@redhat.com>
Date: Mon, 5 May 2025 14:33:32 +0000 (+0200)
Subject: API: Clarify behaviour of autostart vs autostart once
X-Git-Tag: v11.4.0-rc1~80
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=dd8573b3ea52981aaf22a4555f3981aa7aa67ef9;p=thirdparty%2Flibvirt.git

API: Clarify behaviour of autostart vs autostart once

If either of the autostart settings is enabled the VM will be
autostarted. Attempt to clarify that.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
---

diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index f788fa9a58..93e8f5b853 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -7322,9 +7322,8 @@ virDomainCreateWithFiles(virDomainPtr domain, unsigned int nfiles,
  * @domain: a domain object
  * @autostart: the value returned
  *
- * Provides a boolean value indicating whether the domain
- * configured to be automatically started when the host
- * machine boots.
+ * Provides a boolean value indicating whether the domain is configured to be
+ * automatically started each time when the host machine boots.
  *
  * Returns -1 in case of error, 0 in case of success
  *
@@ -7366,8 +7365,8 @@ virDomainGetAutostart(virDomainPtr domain,
  * @domain: a domain object
  * @autostart: whether the domain should be automatically started 0 or 1
  *
- * Configure the domain to be automatically started
- * when the host machine boots.
+ * Configure the domain to be automatically started each time when the host
+ * machine boots.
  *
  * Returns -1 in case of error, 0 in case of success
  *
@@ -7409,9 +7408,12 @@ virDomainSetAutostart(virDomainPtr domain,
  * @domain: a domain object
  * @autostart: the value returned
  *
- * Provides a boolean value indicating whether the domain
- * is configured to be automatically started the next time
- * the host machine boots only.
+ * Provides a boolean value indicating whether the domain is configured to be
+ * automatically started next time when the host machine boots.
+ *
+ * Note that autostart configured via the virDomain[Set|Get]AutostartOnce APIs
+ * is independent from the autostart configured via virDomain[Set|Get]Autostart.
+ * Enabling either of them will cause the VM to be started on the next boot.
  *
  * Returns -1 in case of error, 0 in case of success
  *
@@ -7453,8 +7455,12 @@ virDomainGetAutostartOnce(virDomainPtr domain,
  * @domain: a domain object
  * @autostart: whether the domain should be automatically started 0 or 1
  *
- * Configure the domain to be automatically started
- * the next time the host machine boots only.
+ * Configure the domain to be automatically started the next when the host
+ * machine boots.
+ *
+ * Note that autostart configured via the virDomain[Set|Get]AutostartOnce APIs
+ * is independent from the autostart configured via virDomain[Set|Get]Autostart.
+ * Enabling either of them will cause the VM to be started on the next boot.
  *
  * Returns -1 in case of error, 0 in case of success
  *