[libvirt] [PATCH 3/7] qemu_api: Add comments for API virDomainQemuMonitorCommand

And fix argument @pid's type of virDomainQemuAttach. --- src/libvirt-qemu.c | 41 ++++++++++++++++++++++++++++++++++++++--- 1 files changed, 38 insertions(+), 3 deletions(-) diff --git a/src/libvirt-qemu.c b/src/libvirt-qemu.c index 9481e01..b46868f 100644 --- a/src/libvirt-qemu.c +++ b/src/libvirt-qemu.c @@ -36,6 +36,43 @@ virReportErrorHelper(VIR_FROM_DOM, error, NULL, __FUNCTION__, \ __LINE__, info) +/** + * virDomainQemuMonitorCommand: + * @domain: a domain object + * @cmd: the qemu monitor command string + * @result: a string returned by @cmd + * @flags: bitwise-or of supported virDomainQemuMonitorCommandFlags + * + * This API is QEMU specific, so will only work with hypervisor + * connections to the QEMU driver. + * + * Send an arbitrary monitor command @cmd to @domain through the + * qemu monitor. There are several requirements to safely and + * succcesfully to use this API: + * + * - It must have been started with a monitor socket using the UNIX + * domain socket protocol. + * - No other operations which are changing the domain state or + * configuration at the same time, e.g. domain saving, it might + * cause libvirtd crashed. + * - If the @cmd is intend to change domain configuration, it must + * be no or other configuration changes can have been made via + * the monitor since it started. + * - The '-name' and '-uuid' arguments should have been set (not + * mandatory, but strongly recommended) + * + * If VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP is set, the command is + * considered to be a human monitor command and libvirt will automatically + * convert it into QMP if needed. In that case the @result will also + * be converted back from QMP. + * + * If successful, @result will be filled as a string with the output + * of the @cmd. And other APIs should operate normally (provided the + * above requirements were honoured + * + * Returns 0 in case of success, -1 in case of failure + * + */ int virDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd, char **result, unsigned int flags) @@ -81,8 +118,6 @@ error: return -1; } - - /** * virDomainQemuAttach: * @conn: pointer to a hypervisor connection @@ -111,7 +146,7 @@ error: */ virDomainPtr virDomainQemuAttach(virConnectPtr conn, - unsigned pid, + unsigned int pid, unsigned int flags) { VIR_DEBUG("conn=%p, pid=%u, flags=%x", conn, pid, flags); -- 1.7.6