From nobody Tue Apr 15 03:52:45 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 15064358645901007.9085377597764; Tue, 26 Sep 2017 07:24:24 -0700 (PDT) Received: from localhost ([::1]:47775 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dwqmQ-0002n9-KR for importer@patchew.org; Tue, 26 Sep 2017 10:24:10 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:60942) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dwqkH-0001LE-Oz for qemu-devel@nongnu.org; Tue, 26 Sep 2017 10:22:00 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dwqkG-0005ID-Oj for qemu-devel@nongnu.org; Tue, 26 Sep 2017 10:21:57 -0400 Received: from mx1.redhat.com ([209.132.183.28]:60180) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dwqk5-0005Ao-8t; Tue, 26 Sep 2017 10:21:45 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 5CB0B806C1; Tue, 26 Sep 2017 14:21:44 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-117-39.ams2.redhat.com [10.36.117.39]) by smtp.corp.redhat.com (Postfix) with ESMTP id 465FF66D5A; Tue, 26 Sep 2017 14:21:43 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 5CB0B806C1 Authentication-Results: ext-mx02.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx02.extmail.prod.ext.phx2.redhat.com; spf=fail smtp.mailfrom=kwolf@redhat.com From: Kevin Wolf To: qemu-block@nongnu.org Date: Tue, 26 Sep 2017 16:21:11 +0200 Message-Id: <20170926142133.2498-3-kwolf@redhat.com> In-Reply-To: <20170926142133.2498-1-kwolf@redhat.com> References: <20170926142133.2498-1-kwolf@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.26]); Tue, 26 Sep 2017 14:21:44 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PULL 02/24] qemu-img: Clarify about relative backing file options X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: kwolf@redhat.com, peter.maydell@linaro.org, qemu-devel@nongnu.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" From: Fam Zheng It's not too surprising when a user specifies the backing file relative to the current working directory instead of the top layer image. This causes error when they differ. Though the error message has enough information to infer the fact about the misunderstanding, it is better if we document this explicitly, so that users don't have to learn from mistakes. Signed-off-by: Fam Zheng Reviewed-by: Eric Blake Reviewed-by: Jeff Cody Reviewed-by: Stefan Hajnoczi Signed-off-by: Kevin Wolf --- qemu-img.texi | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/qemu-img.texi b/qemu-img.texi index 72dabd6b3e..90c7eab4a8 100644 --- a/qemu-img.texi +++ b/qemu-img.texi @@ -244,6 +244,9 @@ only the differences from @var{backing_file}. No size n= eeds to be specified in this case. @var{backing_file} will never be modified unless you use the @code{commit} monitor command (or qemu-img commit). =20 +If a relative path name is given, the backing file is looked up relative to +the directory containing @var{filename}. + Note that a given backing file will be opened to check that it is valid. U= se the @code{-u} option to enable unsafe backing file mode, which means that = the image will be created even if the associated backing file cannot be opened= . A @@ -343,6 +346,9 @@ created as a copy on write image of the specified base = image; the @var{backing_file} should have the same content as the input's base image, however the path, image format, etc may differ. =20 +If a relative path name is given, the backing file is looked up relative to +the directory containing @var{output_filename}. + If the @code{-n} option is specified, the target volume creation will be skipped. This is useful for formats such as @code{rbd} if the target volume has already been created with site specific options that cannot @@ -490,6 +496,9 @@ The backing file is changed to @var{backing_file} and (= if the image format of string), then the image is rebased onto no backing file (i.e. it will exist independently of any backing file). =20 +If a relative path name is given, the backing file is looked up relative to +the directory containing @var{filename}. + @var{cache} specifies the cache mode to be used for @var{filename}, whereas @var{src_cache} specifies the cache mode for reading backing files. =20 --=20 2.13.5