'guest-get-time',
'guest-set-vcpus',
'guest-sync',
- 'guest-sync-delimited' ] } }
+ 'guest-sync-delimited' ],
+ # Types and commands with undocumented members:
+ 'documentation-exceptions': [
+ 'GuestNVMeSmart' ] } }
##
# @guest-sync-delimited:
# @time: time of nanoseconds, relative to the Epoch of 1970-01-01 in
# UTC.
#
-# Returns: Nothing on success.
-#
# Since: 1.5
##
{ 'command': 'guest-set-time',
#
# @mode: open mode, as per fopen(), "r" is the default.
#
-# Returns: Guest file handle on success.
+# Returns: Guest file handle
#
# Since: 0.15.0
##
#
# @handle: filehandle returned by guest-file-open
#
-# Returns: Nothing on success.
-#
# Since: 0.15.0
##
{ 'command': 'guest-file-close',
# @count: maximum number of bytes to read (default is 4KB, maximum is
# 48MB)
#
-# Returns: @GuestFileRead on success.
+# Returns: @GuestFileRead
#
# Since: 0.15.0
##
# @count: bytes to write (actual bytes, after base64-decode), default
# is all content in buf-b64 buffer after base64 decoding
#
-# Returns: @GuestFileWrite on success.
+# Returns: @GuestFileWrite
#
# Since: 0.15.0
##
#
# @whence: Symbolic or numeric code for interpreting offset
#
-# Returns: @GuestFileSeek on success.
+# Returns: @GuestFileSeek
#
# Since: 0.15.0
##
#
# @handle: filehandle returned by guest-file-open
#
-# Returns: Nothing on success.
-#
# Since: 0.15.0
##
{ 'command': 'guest-file-flush',
# command succeeded, you may call @guest-fsfreeze-thaw later to
# unfreeze.
#
+# On error, all filesystems will be thawed. If no filesystems are
+# frozen as a result of this call, then @guest-fsfreeze-status will
+# remain "thawed" and calling @guest-fsfreeze-thaw is not necessary.
+#
+# Returns: Number of file systems currently frozen.
+#
# Note: On Windows, the command is implemented with the help of a
# Volume Shadow-copy Service DLL helper. The frozen state is
# limited for up to 10 seconds by VSS.
#
-# Returns: Number of file systems currently frozen. On error, all
-# filesystems will be thawed. If no filesystems are frozen as a
-# result of this call, then @guest-fsfreeze-status will remain
-# "thawed" and calling @guest-fsfreeze-thaw is not necessary.
-#
# Since: 0.15.0
##
{ 'command': 'guest-fsfreeze-freeze',
# Sync and freeze specified guest filesystems. See also
# @guest-fsfreeze-freeze.
#
+# On error, all filesystems will be thawed.
+#
# @mountpoints: an array of mountpoints of filesystems to be frozen.
# If omitted, every mounted filesystem is frozen. Invalid mount
# points are ignored.
#
-# Returns: Number of file systems currently frozen. On error, all
-# filesystems will be thawed.
+# Returns: Number of file systems currently frozen.
#
# Since: 2.2
##
# could also exit (or set its status to "shutdown") due to other
# reasons.
#
-# The following errors may be returned:
-#
-# - If suspend to disk is not supported, Unsupported
+# Errors:
+# - If suspend to disk is not supported, Unsupported
#
# Notes: It's strongly recommended to issue the guest-sync command
# before sending commands when the guest resumes
# 2. Issue the query-status QMP command to confirm the VM status is
# "suspended"
#
-# The following errors may be returned:
-#
-# - If suspend to ram is not supported, Unsupported
+# Errors:
+# - If suspend to ram is not supported, Unsupported
#
# Notes: It's strongly recommended to issue the guest-sync command
# before sending commands when the guest resumes
# 2. Issue the query-status QMP command to confirm the VM status is
# "suspended"
#
-# The following errors may be returned:
-#
-# - If hybrid suspend is not supported, Unsupported
+# Errors:
+# - If hybrid suspend is not supported, Unsupported
#
# Notes: It's strongly recommended to issue the guest-sync command
# before sending commands when the guest resumes
#
# Get list of guest IP addresses, MAC addresses and netmasks.
#
-# Returns: List of GuestNetworkInterface on success.
+# Returns: List of GuestNetworkInterface
#
# Since: 1.1
##
# Attempt to reconfigure (currently: enable/disable) logical
# processors inside the guest.
#
-# The input list is processed node by node in order. In each node
-# @logical-id is used to look up the guest VCPU, for which @online
-# specifies the requested state. The set of distinct @logical-id's is
-# only required to be a subset of the guest-supported identifiers.
-# There's no restriction on list length or on repeating the same
-# @logical-id (with possibly different @online field). Preferably the
-# input list should describe a modified subset of @guest-get-vcpus'
-# return value.
+# @vcpus: The logical processors to be reconfigured. This list is
+# processed node by node in order. In each node @logical-id is
+# used to look up the guest VCPU, for which @online specifies the
+# requested state. The set of distinct @logical-id's is only
+# required to be a subset of the guest-supported identifiers.
+# There's no restriction on list length or on repeating the same
+# @logical-id (with possibly different @online field). Preferably
+# the input list should describe a modified subset of
+# @guest-get-vcpus' return value.
#
# Returns: The length of the initial sublist that has been
# successfully processed. The guest agent maximizes this value.
# - 0:
# if the @vcpus list was empty on input. Guest state has not
# been changed. Otherwise,
-# - Error:
-# processing the first node of @vcpus failed for the reason
-# returned. Guest state has not been changed. Otherwise,
# - < length(@vcpus):
# more than zero initial nodes have been processed, but not the
# entire @vcpus list. Guest state has changed accordingly. To
# - length(@vcpus):
# call successful.
#
+# Errors:
+# - If the reconfiguration of the first node in @vcpus failed.
+# Guest state has not been changed.
+#
# Since: 1.5
##
{ 'command': 'guest-set-vcpus',
# NVMe smart information, based on NVMe specification, section
# <SMART / Health Information (Log Identifier 02h)>
#
+# TODO: document members briefly
+#
# Since: 7.1
##
{ 'struct': 'GuestNVMeSmart',
#
# Disk type related smart information.
#
-# - @nvme: NVMe disk smart
+# @type: disk bus type
#
# Since: 7.1
##
#
# @used-bytes: file system used bytes (since 3.0)
#
-# @total-bytes: non-root file system total bytes (since 3.0)
+# @total-bytes: filesystem capacity in bytes for unprivileged users (since 3.0)
+#
+# @total-bytes-privileged: filesystem capacity in bytes for privileged users
+# (since 9.1)
#
# @disk: an array of disk hardware information that the volume lies
# on, which may be empty if the disk type is not supported
{ 'struct': 'GuestFilesystemInfo',
'data': {'name': 'str', 'mountpoint': 'str', 'type': 'str',
'*used-bytes': 'uint64', '*total-bytes': 'uint64',
- 'disk': ['GuestDiskAddress']} }
+ '*total-bytes-privileged': 'uint64', 'disk': ['GuestDiskAddress']} }
##
# @guest-get-fsinfo:
# transmission, even if already crypt()d, to ensure it is 8-bit safe
# when passed as JSON.
#
-# Returns: Nothing on success.
-#
# Since: 2.3
##
{ 'command': 'guest-set-user-password',
# Attempt to reconfigure (currently: enable/disable) state of memory
# blocks inside the guest.
#
-# The input list is processed node by node in order. In each node
-# @phys-index is used to look up the guest MEMORY BLOCK, for which
-# @online specifies the requested state. The set of distinct
-# @phys-index's is only required to be a subset of the guest-supported
-# identifiers. There's no restriction on list length or on repeating
-# the same @phys-index (with possibly different @online field).
-# Preferably the input list should describe a modified subset of
-# @guest-get-memory-blocks' return value.
+# @mem-blks: The memory blocks to be reconfigured. This list is
+# processed node by node in order. In each node @phys-index is
+# used to look up the guest MEMORY BLOCK, for which @online
+# specifies the requested state. The set of distinct
+# @phys-index's is only required to be a subset of the
+# guest-supported identifiers. There's no restriction on list
+# length or on repeating the same @phys-index (with possibly
+# different @online field). Preferably the input list should
+# describe a modified subset of @guest-get-memory-blocks' return
+# value.
#
# Returns: The operation results, it is a list of
# @GuestMemoryBlockResponse, which is corresponding to the input
# list.
#
-# Note: it will return NULL if the @mem-blks list was empty on
-# input, or there is an error, and in this case, guest state will
-# not be changed.
+# Note: it will return an empty list if the @mem-blks list was
+# empty on input, or there is an error, and in this case, guest
+# state will not be changed.
#
# Since: 2.3
##
# @signal: signal number (linux) or unhandled exception code (windows)
# if the process was abnormally terminated.
#
-# @out-data: base64-encoded stdout of the process
+# @out-data: base64-encoded stdout of the process. This field will
+# only be populated after the process exits.
#
-# @err-data: base64-encoded stderr of the process Note: @out-data and
-# @err-data are present only if 'capture-output' was specified for
-# 'guest-exec'
+# @err-data: base64-encoded stderr of the process. Note: @out-data
+# and @err-data are present only if 'capture-output' was specified
+# for 'guest-exec'. This field will only be populated after the
+# process exits.
#
# @out-truncated: true if stdout was not fully captured due to size
# limitation.
#
# @pid: pid returned from guest-exec
#
-# Returns: GuestExecStatus on success.
+# Returns: GuestExecStatus
#
# Since: 2.5
##
# An enumeration of guest-exec capture modes.
#
# @none: do not capture any output
+#
# @stdout: only capture stdout
+#
# @stderr: only capture stderr
+#
# @separated: capture both stdout and stderr, but separated into
-# GuestExecStatus out-data and err-data, respectively
-# @merged: capture both stdout and stderr, but merge together
-# into out-data. not effective on windows guests.
+# GuestExecStatus out-data and err-data, respectively
+#
+# @merged: capture both stdout and stderr, but merge together into
+# out-data. Not effective on windows guests.
#
# Since: 8.0
##
#
# Controls what guest-exec output gets captures.
#
-# @flag: captures both stdout and stderr if true. Equivalent
-# to GuestExecCaptureOutputMode::all. (since 2.5)
+# @flag: captures both stdout and stderr if true. Equivalent to
+# GuestExecCaptureOutputMode::all. (since 2.5)
+#
# @mode: capture mode; preferred interface
#
# Since: 8.0
# @input-data: data to be passed to process stdin (base64 encoded)
#
# @capture-output: bool flag to enable capture of stdout/stderr of
-# running process. defaults to false.
+# running process. Defaults to false.
#
-# Returns: PID on success.
+# Returns: PID
#
# Since: 2.5
##
# or even present in DNS or some other name service at all. It need
# not even be unique on your local network or site, but usually it is.
#
-# Returns: the host name of the machine on success
+# Returns: the host name of the machine
#
# Since: 2.10
##
##
# @GuestDeviceType:
+#
+# @pci: PCI device
##
{ 'enum': 'GuestDeviceType',
'data': [ 'pci' ] }
##
# @GuestDeviceId:
#
-# Id of the device - @pci: PCI ID, since: 5.2
+# Id of the device
+#
+# @type: device type
#
# Since: 5.2
##
{ 'struct': 'GuestAuthorizedKeys',
'data': {
'keys': ['str']
- },
- 'if': 'CONFIG_POSIX' }
-
+ }
+}
##
# @guest-ssh-get-authorized-keys:
#
-# @username: the user account to add the authorized keys
-#
# Return the public keys from user .ssh/authorized_keys on Unix
# systems (not implemented for other systems).
#
+# @username: the user account to add the authorized keys
+#
# Returns: @GuestAuthorizedKeys
#
# Since: 5.2
##
{ 'command': 'guest-ssh-get-authorized-keys',
'data': { 'username': 'str' },
- 'returns': 'GuestAuthorizedKeys',
- 'if': 'CONFIG_POSIX' }
+ 'returns': 'GuestAuthorizedKeys'
+}
##
# @guest-ssh-add-authorized-keys:
#
+# Append public keys to user .ssh/authorized_keys on Unix systems (not
+# implemented for other systems).
+#
# @username: the user account to add the authorized keys
#
# @keys: the public keys to add (in OpenSSH/sshd(8) authorized_keys
#
# @reset: ignore the existing content, set it with the given keys only
#
-# Append public keys to user .ssh/authorized_keys on Unix systems (not
-# implemented for other systems).
-#
-# Returns: Nothing on success.
-#
# Since: 5.2
##
{ 'command': 'guest-ssh-add-authorized-keys',
- 'data': { 'username': 'str', 'keys': ['str'], '*reset': 'bool' },
- 'if': 'CONFIG_POSIX' }
+ 'data': { 'username': 'str', 'keys': ['str'], '*reset': 'bool' }
+}
##
# @guest-ssh-remove-authorized-keys:
#
-# @username: the user account to remove the authorized keys
-#
-# @keys: the public keys to remove (in OpenSSH/sshd(8) authorized_keys
-# format)
-#
# Remove public keys from the user .ssh/authorized_keys on Unix
# systems (not implemented for other systems). It's not an error if
# the key is already missing.
#
-# Returns: Nothing on success.
+# @username: the user account to remove the authorized keys
+#
+# @keys: the public keys to remove (in OpenSSH/sshd(8) authorized_keys
+# format)
#
# Since: 5.2
##
{ 'command': 'guest-ssh-remove-authorized-keys',
- 'data': { 'username': 'str', 'keys': ['str'] },
- 'if': 'CONFIG_POSIX' }
+ 'data': { 'username': 'str', 'keys': ['str'] }
+}
##
# @GuestDiskStats:
# @major: major device number of disk
#
# @minor: minor device number of disk
+#
+# @stats: I/O statistics
##
{ 'struct': 'GuestDiskStatsInfo',
'data': {'name': 'str',
##
# @GuestCpuStatsType:
#
-# An enumeration of OS type
+# Guest operating systems supporting CPU statistics
+#
+# @linux: Linux
#
# Since: 7.1
##
#
# Get statistics of each CPU in millisecond.
#
-# - @linux: Linux style CPU statistics
+# @type: guest operating system
#
# Since: 7.1
##
projects / mirror_qemu.git / blobdiff