guest-file-seek accepts both symbolic and numeric @whence values, but
the former is documented as "preferred interface".  Remove or replace
mentions of numeric values by symbolic ones.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qga/qapi-schema.json | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 040c932310..576ce7fea8 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -342,11 +342,11 @@
 #
 # Symbolic names for use in `guest-file-seek`
 #
-# @set: Set to the specified offset (same effect as 'whence':0)
+# @set: Set to the specified offset
 #
-# @cur: Add offset to the current location (same effect as 'whence':1)
+# @cur: Add offset to the current location
 #
-# @end: Add offset to the end of the file (same effect as 'whence':2)
+# @end: Add offset to the end of the file
 #
 # Since: 2.6
 ##
@@ -373,7 +373,7 @@
 #
 # Seek to a position in the file, as with fseek(), and return the
 # current file position afterward.  Also encapsulates ftell()'s
-# functionality, with offset=0 and whence=1.
+# functionality, with offset=0 and whence="cur".
 #
 # @handle: filehandle returned by `guest-file-open`
 #
-- 
2.55.0

On Wed, Sep 23, 2026 at 3:03 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> guest-file-seek accepts both symbolic and numeric @whence values, but
> the former is documented as "preferred interface".  Remove or replace
> mentions of numeric values by symbolic ones.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Sure. The equivalences are still documented in `GuestFileWhence`, so
this seems fine. If the symbolic names are preferred, it seems fine
that looking up the symbol doesn't give you a crappier, non-preferred
way to specify it. By contrast, if you look up the numbers, it should
tell you what the equivalent preferred enum is.

(make "upgrading" easy, make "downgrading" hard.)

yadda yadda

Reviewed-by: John Snow <jsnow@redhat.com>

> ---
>  qga/qapi-schema.json | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
> index 040c932310..576ce7fea8 100644
> --- a/qga/qapi-schema.json
> +++ b/qga/qapi-schema.json
> @@ -342,11 +342,11 @@
>  #
>  # Symbolic names for use in `guest-file-seek`
>  #
> -# @set: Set to the specified offset (same effect as 'whence':0)
> +# @set: Set to the specified offset
>  #
> -# @cur: Add offset to the current location (same effect as 'whence':1)
> +# @cur: Add offset to the current location
>  #
> -# @end: Add offset to the end of the file (same effect as 'whence':2)
> +# @end: Add offset to the end of the file
>  #
>  # Since: 2.6
>  ##
> @@ -373,7 +373,7 @@
>  #
>  # Seek to a position in the file, as with fseek(), and return the
>  # current file position afterward.  Also encapsulates ftell()'s
> -# functionality, with offset=0 and whence=1.
> +# functionality, with offset=0 and whence="cur".
>  #
>  # @handle: filehandle returned by `guest-file-open`
>  #
> --
> 2.55.0
>