From nobody Sun May 5 21:48:14 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) client-ip=205.139.110.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1594914341; cv=none; d=zohomail.com; s=zohoarc; b=Sxa8kr7ys/LoRM154jU6SabT0WEa87xLtn6B6Wp+ilWJ/ojzJ49p5RlHQg9S0RwyfOCxdQEtK5r02rIn0AxdNEmu1NMeSyK045Xgta48JoCpVj3vIm18tzegBmiZVQgACQHrwiEKKYisCy5UZY8iSDIA4EneG4Ea7JvlPHKIvhE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1594914341; h=Content-Type:Content-Transfer-Encoding:Date:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=/oE5FeUw5J/6sfVvtfo8ZltTYeHC8C0MpMM/g1gvTXw=; b=OseUazo2XeZsTaVcLIj106Kw4Jvpqd9XSPGKk95Qkd6uYi1++PikAaDbSbfeohEdRCeNtgW57UvHJTjTl1gYyM39vgoHckGegJuFT9Nhq3KbnGTXP6dWu6g0pDlq5QLRoJTd4H+tOzufKSWFXMtM5aGUQ9U8kYCpVd1pR/awUIs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [205.139.110.120]) by mx.zohomail.com with SMTPS id 15949143412951021.090764083778; Thu, 16 Jul 2020 08:45:41 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-506-sVhREGvZM8a7LzsBZdRKew-1; Thu, 16 Jul 2020 11:45:37 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 50E0C18A1DE8; Thu, 16 Jul 2020 15:45:31 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 8BBA919C58; Thu, 16 Jul 2020 15:45:29 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 770E21809554; Thu, 16 Jul 2020 15:45:27 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 06GFjQw1006360 for ; Thu, 16 Jul 2020 11:45:26 -0400 Received: by smtp.corp.redhat.com (Postfix) id 1C16679D1F; Thu, 16 Jul 2020 15:45:26 +0000 (UTC) Received: from paraplu.localdomain (ovpn-112-157.ams2.redhat.com [10.36.112.157]) by smtp.corp.redhat.com (Postfix) with ESMTP id 197E97B40B; Thu, 16 Jul 2020 15:45:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1594914339; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=/oE5FeUw5J/6sfVvtfo8ZltTYeHC8C0MpMM/g1gvTXw=; b=S4ezShqD0vvhfwbQNH+eLDUwYfqtdfT0WbxyZR+nvtKSMbay5jWB591wR+CA4S94QxQ39T ml1PX+NqBu4FfMmvmd9LRYBaJ6KoBQ/Wk9RGu9ouo51IqlBixtHB2qEGx+xXXR/Ei4+ITT mLCs1DAFPJtEzzi8VAj4mvhSwirLe/c= X-MC-Unique: sVhREGvZM8a7LzsBZdRKew-1 From: Kashyap Chamarthy To: libvir-list@redhat.com Subject: [libvirt PATCH] manpages/virsh: Clarify the meaning of the '--current' flag Date: Thu, 16 Jul 2020 17:45:21 +0200 Message-Id: <20200716154521.120051-1-kchamart@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Currently the documentation says: "If *--current* is specified, affect the current guest state." It's not entirely clear what states can "current" imply. E.g. `virsh detach-device --current [...]` =E2=80=94 does this affect the live guest s= tate or offline state? Answer: It affects the "current" state, which can either be live or offline. Spell that out; it's clearer that way. Fix all occurrences (i.e. as many as I could spot) of this. (Thanks: Dan Berrang=C3=A9 on IRC for clarifying.) Signed-off-by: Kashyap Chamarthy --- For 'iothreadset', the documentation says: "If *--current* is specified or *--live* is not specified, then handle as if *--live* was specified." Does the above make sense? I don't know the implementation detail here. So I just added a parenthetical note on what the word "current" means. --- docs/manpages/virsh.rst | 84 ++++++++++++++++++++++++++--------------- 1 file changed, 54 insertions(+), 30 deletions(-) diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst index 1a2cf09fb7..3c8d0434ab 100644 --- a/docs/manpages/virsh.rst +++ b/docs/manpages/virsh.rst @@ -1090,7 +1090,8 @@ reset the value back to the default. =20 If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. When setting the disk io parameters both *--live* and *--config* flags may= be given, but *--current* is exclusive. For querying only one of *--live*, *--config* or *--current* can be specified. If no flag is specified, behav= ior @@ -1152,7 +1153,8 @@ any existing per-device write_bytes_sec for other dev= ices remain unchanged. =20 If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -1986,7 +1988,8 @@ respectfully with average value of zero. =20 If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -2089,7 +2092,8 @@ The *--live*, *--config*, and *--current* flags are o= nly valid when using the *--period* option in order to set the collection period for the balloon driver. If *--live* is specified, only the running guest collection period is affected. If *--config* is specified, affect the next boot of a persist= ent -guest. If *--current* is specified, affect the current guest state. +guest. If *--current* is specified, affect the current guest state, +which can either be live or offline. =20 Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending @@ -2582,7 +2586,8 @@ See ``vcpupin`` for *cpulist*. =20 If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given if *cpulist* is present, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -2746,7 +2751,7 @@ If *--live* is specified, affect a running guest. If = the guest is not running an error is returned. If *--config* is specified, affect the next boot of a persistent guest. If *--current* is specified or *--live* and *--config* are not specified, -affect the current guest state. +affect the current guest state, which can either be live or offline. =20 =20 iothreaddel @@ -2767,7 +2772,7 @@ If *--live* is specified, affect a running guest. If = the guest is not running an error is returned. If *--config* is specified, affect the next boot of a persistent guest. If *--current* is specified or *--live* and *--config* are not specified, -affect the current guest state. +affect the current guest state, which can either be live or offline. =20 =20 iothreadinfo @@ -2787,7 +2792,8 @@ the guest is not running, an error is returned. If *--config* is specified, get the IOThreads data from the next boot of a persistent guest. If *--current* is specified or *--live* and *--config* are not specified, -then get the IOThread data based on the current guest state. +then get the IOThread data based on the current guest state, which can +either be live or offline. =20 =20 iothreadpin @@ -2814,7 +2820,7 @@ If *--live* is specified, affect a running guest. If = the guest is not running, an error is returned. If *--config* is specified, affect the next boot of a persistent guest. If *--current* is specified or *--live* and *--config* are not specified, -affect the current guest state. +affect the current guest state, which can either be live or offline. Both *--live* and *--config* flags may be given if *cpulist* is present, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -2851,7 +2857,8 @@ next start, restore, etc. If *--live* is specified, affect a running guest. If the guest is not running an error is returned. If *--current* is specified or *--live* is not specified, then handle -as if *--live* was specified. +as if *--live* was specified. (Where "current" here means whatever the +present guest state is: live or offline.) =20 =20 managedsave @@ -2998,7 +3005,8 @@ For example, vSphere/ESX rounds the parameter up to m= ebibytes (1024 kibibytes). =20 If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -3393,7 +3401,8 @@ excluding a node. =20 If *--live* is specified, set scheduler information of a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. =20 For running guests in Linux hosts, the changes made in the domain's numa parameters does not imply that the guest memory will be moved to a @@ -3486,7 +3495,8 @@ the *--perf* flag. =20 If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -3715,7 +3725,8 @@ ESX (allocation scheduler): reservation, limit, shares =20 If *--live* is specified, set scheduler information of a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. =20 ``Note``: The cpu_shares parameter has a valid value range of 0-262144; Ne= gative values are wrapped to positive, and larger values are capped at the maximu= m. @@ -3957,7 +3968,8 @@ setmaxmem Change the maximum memory allocation limit for a guest domain. If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -3988,7 +4000,8 @@ setmem Change the memory allocation for a guest domain. If *--live* is specified, perform a memory balloon of a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -4038,7 +4051,8 @@ specified together if supported by the hypervisor. I= f this command is run before the guest has finished booting, the guest may fail to process the change. =20 -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. =20 When no flags are given, the *--live* flag is assumed and the guest domain must be active. In this situation it @@ -4084,9 +4098,9 @@ others. =20 If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. This is the -default. Both *--live* and *--config* flags may be given, but *--current* = is -exclusive. +If *--current* is specified, affect the current domain state, which can +either be live or offline. This is the default. Both *--live* and +*--config* flags may be given, but *--current* is exclusive. =20 =20 shutdown @@ -4356,7 +4370,8 @@ also be allowed. The '-' denotes the range and the '^= ' denotes exclusive. For pinning the *vcpu* to all physical cpus specify 'r' as a *cpulist*. If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given if *cpulist* is present, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -4411,7 +4426,8 @@ needed if the PCI device does not use managed mode. =20 If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. When no flag is specified legacy API is used whose behavior dep= ends on the hypervisor driver. @@ -4480,7 +4496,8 @@ is printed instead. =20 If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. When no flag is specified legacy API is used whose behavior dep= ends on the hypervisor driver. @@ -4568,7 +4585,8 @@ attached is printed instead. =20 If ``--live`` is specified, affect a running domain. If ``--config`` is specified, affect the next startup of a persistent doma= in. -If ``--current`` is specified, affect the current domain state. +If ``--current`` is specified, affect the current domain state, which +can either be live or offline. Both ``--live`` and ``--config`` flags may be given, but ``--current`` is exclusive. When no flag is specified legacy API is used whose behavior depends on the hypervisor driver. @@ -4615,7 +4633,8 @@ returns. =20 If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. When no flag is specified legacy API is used whose behavior dep= ends on the hypervisor driver. @@ -4643,7 +4662,8 @@ removal of the device is notified asynchronously via = libvirt events =20 If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. =20 @@ -4663,7 +4683,8 @@ from the domain. =20 If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. When no flag is specified legacy API is used whose behavior dep= ends on the hypervisor driver. @@ -4699,7 +4720,8 @@ present on the domain. =20 If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. When no flag is specified legacy API is used whose behavior dep= ends on the hypervisor driver. @@ -4732,7 +4754,8 @@ libvirt XML format for a device. =20 If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. Not specifying any flag is the same as specifying *--current*. =20 @@ -5223,7 +5246,8 @@ instance of will get the modification. =20 If *--live* is specified, affect a running network. If *--config* is specified, affect the next startup of a persistent networ= k. -If *--current* is specified, affect the current network state. +If *--current* is specified, affect the current network state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. Not specifying any flag is the same as specifying *--current*. =20 --=20 2.26.2