[libvirt] [PATCH 0/3] virsh: add command and option aliases
I'm tired of publicizing typos. These patches preserve full back-compat (scripts that used the old spelling will continue to work), we just don't document the old spellings. I started this patch because we have the memory commands that take a --kilobyte argument when they really mean KiB (kibibyte or 1024); I plan to use the aliasing feature in my later units cleanup series to fix this naming to instead take scaled sizes (such as --size=1M or --size=1024bytes); at which point --kilobyte will be the undocumented alias so that we no longer document a name that might then be confused for 1000. Eric Blake (3): virsh: add option aliases virsh: use option aliases virsh: add command aliases, and rename nodedev-detach tests/virshtest.c | 6 +++ tools/virsh.c | 107 +++++++++++++++++++++++++++++++++++++--------------- tools/virsh.pod | 28 +++++++------ 3 files changed, 97 insertions(+), 44 deletions(-) -- 1.7.7.6
In the past, we have created some virsh options with less-than-stellar names. For back-compat reasons, those names must continue to parse, but we don't want to document them in help output. This introduces a new option type, an alias, which points to a canonical option name later in the option list. I'm actually quite impressed that our code has already been factored to do all option parsing through common entry points, such that I got this added in relatively few lines of code! * tools/virsh.c (VSH_OT_ALIAS): New option type. (opts_echo): Hook up an alias, for easy testing. (vshCmddefOptParse, vshCmddefHelp, vshCmddefGetOption): Allow for aliases. * tests/virshtest.c (mymain): Test new feature. --- tests/virshtest.c | 6 ++++++ tools/virsh.c | 28 ++++++++++++++++++++++++++-- 2 files changed, 32 insertions(+), 2 deletions(-) diff --git a/tests/virshtest.c b/tests/virshtest.c index 6474c19..87b1336 100644 --- a/tests/virshtest.c +++ b/tests/virshtest.c @@ -386,6 +386,12 @@ mymain(void) DO_TEST(30, "--shell a\n", "echo \t '-'\"-\" \t --shell \t a"); + /* Tests of alias handling. */ + DO_TEST(31, "hello\n", "echo", "--string", "hello"); + DO_TEST(32, "hello\n", "echo --string hello"); + DO_TEST(33, "hello\n", "echo", "--str", "hello"); + DO_TEST(34, "hello\n", "echo --str hello"); + # undef DO_TEST VIR_FREE(custom_uri); diff --git a/tools/virsh.c b/tools/virsh.c index aef050f..77cf4ac 100644 --- a/tools/virsh.c +++ b/tools/virsh.c @@ -138,7 +138,8 @@ typedef enum { VSH_OT_STRING, /* optional string option */ VSH_OT_INT, /* optional or mandatory int option */ VSH_OT_DATA, /* string data (as non-option) */ - VSH_OT_ARGV /* remaining arguments */ + VSH_OT_ARGV, /* remaining arguments */ + VSH_OT_ALIAS, /* alternate spelling for a later argument */ } vshCmdOptType; /* @@ -190,7 +191,8 @@ typedef struct { const char *name; /* the name of option, or NULL for list end */ vshCmdOptType type; /* option type */ unsigned int flags; /* flags */ - const char *help; /* non-NULL help string */ + const char *help; /* non-NULL help string; or for VSH_OT_ALIAS + * the name of a later public option */ } vshCmdOptDef; /* @@ -15209,6 +15211,7 @@ static const vshCmdInfo info_echo[] = { static const vshCmdOptDef opts_echo[] = { {"shell", VSH_OT_BOOL, 0, N_("escape for shell use")}, {"xml", VSH_OT_BOOL, 0, N_("escape for XML use")}, + {"str", VSH_OT_ALIAS, 0, "string"}, {"string", VSH_OT_ARGV, 0, N_("arguments to echo")}, {NULL, 0, 0, NULL} }; @@ -17256,6 +17259,18 @@ vshCmddefOptParse(const vshCmdDef *cmd, uint32_t *opts_need_arg, return -1; /* bool options can't be mandatory */ continue; } + if (opt->type == VSH_OT_ALIAS) { + int j; + if (opt->flags || !opt->help) + return -1; /* alias options are tracked by the original name */ + for (j = i + 1; cmd->opts[j].name; j++) { + if (STREQ(opt->help, cmd->opts[j].name)) + break; + } + if (!cmd->opts[j].name) + return -1; /* alias option must map to a later option name */ + continue; + } if (opt->flags & VSH_OFLAG_REQ_OPT) { if (opt->flags & VSH_OFLAG_REQ) *opts_required |= 1 << i; @@ -17287,6 +17302,10 @@ vshCmddefGetOption(vshControl *ctl, const vshCmdDef *cmd, const char *name, const vshCmdOptDef *opt = &cmd->opts[i]; if (STREQ(opt->name, name)) { + if (opt->type == VSH_OT_ALIAS) { + name = opt->help; + continue; + } if ((*opts_seen & (1 << i)) && opt->type != VSH_OT_ARGV) { vshError(ctl, _("option --%s already seen"), name); return NULL; @@ -17465,6 +17484,9 @@ vshCmddefHelp(vshControl *ctl, const char *cmdname) : _("[<%s>]..."); } break; + case VSH_OT_ALIAS: + /* aliases are intentionally undocumented */ + continue; default: assert(0); } @@ -17506,6 +17528,8 @@ vshCmddefHelp(vshControl *ctl, const char *cmdname) shortopt ? _("[--%s] <string>") : _("<%s>"), opt->name); break; + case VSH_OT_ALIAS: + continue; default: assert(0); } -- 1.7.7.6
On 03/03/2012 09:02 AM, Eric Blake wrote:
In the past, we have created some virsh options with less-than-stellar names. For back-compat reasons, those names must continue to parse, but we don't want to document them in help output. This introduces a new option type, an alias, which points to a canonical option name later in the option list.
I'm actually quite impressed that our code has already been factored to do all option parsing through common entry points, such that I got this added in relatively few lines of code!
* tools/virsh.c (VSH_OT_ALIAS): New option type. (opts_echo): Hook up an alias, for easy testing. (vshCmddefOptParse, vshCmddefHelp, vshCmddefGetOption): Allow for aliases. * tests/virshtest.c (mymain): Test new feature. --- tests/virshtest.c | 6 ++++++ tools/virsh.c | 28 ++++++++++++++++++++++++++-- 2 files changed, 32 insertions(+), 2 deletions(-)
diff --git a/tests/virshtest.c b/tests/virshtest.c index 6474c19..87b1336 100644 --- a/tests/virshtest.c +++ b/tests/virshtest.c @@ -386,6 +386,12 @@ mymain(void) DO_TEST(30, "--shell a\n", "echo \t '-'\"-\" \t --shell \t a");
+ /* Tests of alias handling. */ + DO_TEST(31, "hello\n", "echo", "--string", "hello"); + DO_TEST(32, "hello\n", "echo --string hello"); + DO_TEST(33, "hello\n", "echo", "--str", "hello"); + DO_TEST(34, "hello\n", "echo --str hello"); + # undef DO_TEST
VIR_FREE(custom_uri); diff --git a/tools/virsh.c b/tools/virsh.c index aef050f..77cf4ac 100644 --- a/tools/virsh.c +++ b/tools/virsh.c @@ -138,7 +138,8 @@ typedef enum { VSH_OT_STRING, /* optional string option */ VSH_OT_INT, /* optional or mandatory int option */ VSH_OT_DATA, /* string data (as non-option) */ - VSH_OT_ARGV /* remaining arguments */ + VSH_OT_ARGV, /* remaining arguments */ + VSH_OT_ALIAS, /* alternate spelling for a later argument */ } vshCmdOptType;
/* @@ -190,7 +191,8 @@ typedef struct { const char *name; /* the name of option, or NULL for list end */ vshCmdOptType type; /* option type */ unsigned int flags; /* flags */ - const char *help; /* non-NULL help string */ + const char *help; /* non-NULL help string; or for VSH_OT_ALIAS + * the name of a later public option */ } vshCmdOptDef;
/* @@ -15209,6 +15211,7 @@ static const vshCmdInfo info_echo[] = { static const vshCmdOptDef opts_echo[] = { {"shell", VSH_OT_BOOL, 0, N_("escape for shell use")}, {"xml", VSH_OT_BOOL, 0, N_("escape for XML use")}, + {"str", VSH_OT_ALIAS, 0, "string"}, {"string", VSH_OT_ARGV, 0, N_("arguments to echo")}, {NULL, 0, 0, NULL} }; @@ -17256,6 +17259,18 @@ vshCmddefOptParse(const vshCmdDef *cmd, uint32_t *opts_need_arg, return -1; /* bool options can't be mandatory */ continue; } + if (opt->type == VSH_OT_ALIAS) { + int j; + if (opt->flags || !opt->help) + return -1; /* alias options are tracked by the original name */ + for (j = i + 1; cmd->opts[j].name; j++) { + if (STREQ(opt->help, cmd->opts[j].name)) + break; + } + if (!cmd->opts[j].name) + return -1; /* alias option must map to a later option name */ + continue; + } if (opt->flags& VSH_OFLAG_REQ_OPT) { if (opt->flags& VSH_OFLAG_REQ) *opts_required |= 1<< i; @@ -17287,6 +17302,10 @@ vshCmddefGetOption(vshControl *ctl, const vshCmdDef *cmd, const char *name, const vshCmdOptDef *opt =&cmd->opts[i];
if (STREQ(opt->name, name)) { + if (opt->type == VSH_OT_ALIAS) { + name = opt->help; + continue; + } if ((*opts_seen& (1<< i))&& opt->type != VSH_OT_ARGV) { vshError(ctl, _("option --%s already seen"), name); return NULL; @@ -17465,6 +17484,9 @@ vshCmddefHelp(vshControl *ctl, const char *cmdname) : _("[<%s>]..."); } break; + case VSH_OT_ALIAS: + /* aliases are intentionally undocumented */ + continue; default: assert(0); } @@ -17506,6 +17528,8 @@ vshCmddefHelp(vshControl *ctl, const char *cmdname) shortopt ? _("[--%s]<string>") : _("<%s>"), opt->name); break; + case VSH_OT_ALIAS: + continue; default: assert(0); }
Ah, I could recall we talked about this half year before, for creating alias ("--config") for the options "--persistent" of commands like "attach-device", then I forgot it to do it. Looks good, ACK. Osier
On 03/07/2012 03:33 PM, Osier Yang wrote:
On 03/03/2012 09:02 AM, Eric Blake wrote:
In the past, we have created some virsh options with less-than-stellar names. For back-compat reasons, those names must continue to parse, but we don't want to document them in help output. This introduces a new option type, an alias, which points to a canonical option name later in the option list.
I'm actually quite impressed that our code has already been factored to do all option parsing through common entry points, such that I got this added in relatively few lines of code!
* tools/virsh.c (VSH_OT_ALIAS): New option type. (opts_echo): Hook up an alias, for easy testing. (vshCmddefOptParse, vshCmddefHelp, vshCmddefGetOption): Allow for aliases. * tests/virshtest.c (mymain): Test new feature. --- tests/virshtest.c | 6 ++++++ tools/virsh.c | 28 ++++++++++++++++++++++++++-- 2 files changed, 32 insertions(+), 2 deletions(-)
diff --git a/tests/virshtest.c b/tests/virshtest.c index 6474c19..87b1336 100644 --- a/tests/virshtest.c +++ b/tests/virshtest.c @@ -386,6 +386,12 @@ mymain(void) DO_TEST(30, "--shell a\n", "echo \t '-'\"-\" \t --shell \t a");
+ /* Tests of alias handling. */ + DO_TEST(31, "hello\n", "echo", "--string", "hello"); + DO_TEST(32, "hello\n", "echo --string hello"); + DO_TEST(33, "hello\n", "echo", "--str", "hello"); + DO_TEST(34, "hello\n", "echo --str hello"); + # undef DO_TEST
VIR_FREE(custom_uri); diff --git a/tools/virsh.c b/tools/virsh.c index aef050f..77cf4ac 100644 --- a/tools/virsh.c +++ b/tools/virsh.c @@ -138,7 +138,8 @@ typedef enum { VSH_OT_STRING, /* optional string option */ VSH_OT_INT, /* optional or mandatory int option */ VSH_OT_DATA, /* string data (as non-option) */ - VSH_OT_ARGV /* remaining arguments */ + VSH_OT_ARGV, /* remaining arguments */ + VSH_OT_ALIAS, /* alternate spelling for a later argument */ } vshCmdOptType;
/* @@ -190,7 +191,8 @@ typedef struct { const char *name; /* the name of option, or NULL for list end */ vshCmdOptType type; /* option type */ unsigned int flags; /* flags */ - const char *help; /* non-NULL help string */ + const char *help; /* non-NULL help string; or for VSH_OT_ALIAS + * the name of a later public option */ } vshCmdOptDef;
/* @@ -15209,6 +15211,7 @@ static const vshCmdInfo info_echo[] = { static const vshCmdOptDef opts_echo[] = { {"shell", VSH_OT_BOOL, 0, N_("escape for shell use")}, {"xml", VSH_OT_BOOL, 0, N_("escape for XML use")}, + {"str", VSH_OT_ALIAS, 0, "string"}, {"string", VSH_OT_ARGV, 0, N_("arguments to echo")}, {NULL, 0, 0, NULL} }; @@ -17256,6 +17259,18 @@ vshCmddefOptParse(const vshCmdDef *cmd, uint32_t *opts_need_arg, return -1; /* bool options can't be mandatory */ continue; } + if (opt->type == VSH_OT_ALIAS) { + int j; + if (opt->flags || !opt->help) + return -1; /* alias options are tracked by the original name */ + for (j = i + 1; cmd->opts[j].name; j++) { + if (STREQ(opt->help, cmd->opts[j].name)) + break; + } + if (!cmd->opts[j].name) + return -1; /* alias option must map to a later option name */ + continue; + } if (opt->flags& VSH_OFLAG_REQ_OPT) { if (opt->flags& VSH_OFLAG_REQ) *opts_required |= 1<< i; @@ -17287,6 +17302,10 @@ vshCmddefGetOption(vshControl *ctl, const vshCmdDef *cmd, const char *name, const vshCmdOptDef *opt =&cmd->opts[i];
if (STREQ(opt->name, name)) { + if (opt->type == VSH_OT_ALIAS) { + name = opt->help; + continue; + } if ((*opts_seen& (1<< i))&& opt->type != VSH_OT_ARGV) { vshError(ctl, _("option --%s already seen"), name); return NULL; @@ -17465,6 +17484,9 @@ vshCmddefHelp(vshControl *ctl, const char *cmdname) : _("[<%s>]..."); } break; + case VSH_OT_ALIAS: + /* aliases are intentionally undocumented */ + continue; default: assert(0); } @@ -17506,6 +17528,8 @@ vshCmddefHelp(vshControl *ctl, const char *cmdname) shortopt ? _("[--%s]<string>") : _("<%s>"), opt->name); break; + case VSH_OT_ALIAS: + continue; default: assert(0); }
Ah, I could recall we talked about this half year before, for creating alias ("--config") for the options "--persistent" of commands like "attach-device", then I forgot it to do it.
I created a patch which can be served as 4/4 of these series, for the "--persistent" changes. Osier
Command line interfaces should use dash, not underscore, as many keyboard layouts allow that to be typed with fewer shift key presses. Also, the US spelling of --tunneled gets more google hits than the UK spelling of --tunnelled. * tools/virsh.c (opts_migrate): Allow US variant. (opts_blkdeviotune): Prefer - over _. * tools/virsh.pod (blkdeviotune): Fix spelling. --- tools/virsh.c | 49 +++++++++++++++++++++++++++++++------------------ tools/virsh.pod | 18 +++++++++--------- 2 files changed, 40 insertions(+), 27 deletions(-) diff --git a/tools/virsh.c b/tools/virsh.c index 77cf4ac..75a1a3b 100644 --- a/tools/virsh.c +++ b/tools/virsh.c @@ -6879,6 +6879,7 @@ static const vshCmdOptDef opts_migrate[] = { {"live", VSH_OT_BOOL, 0, N_("live migration")}, {"p2p", VSH_OT_BOOL, 0, N_("peer-2-peer migration")}, {"direct", VSH_OT_BOOL, 0, N_("direct migration")}, + {"tunneled", VSH_OT_ALIAS, 0, "tunnelled"}, {"tunnelled", VSH_OT_BOOL, 0, N_("tunnelled migration")}, {"persistent", VSH_OT_BOOL, 0, N_("persist VM on destination")}, {"undefinesource", VSH_OT_BOOL, 0, N_("undefine VM on source")}, @@ -7574,17 +7575,23 @@ static const vshCmdInfo info_blkdeviotune[] = { static const vshCmdOptDef opts_blkdeviotune[] = { {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")}, {"device", VSH_OT_DATA, VSH_OFLAG_REQ, N_("block device")}, - {"total_bytes_sec", VSH_OT_INT, VSH_OFLAG_NONE, + {"total_bytes_sec", VSH_OT_ALIAS, 0, "total-bytes-sec"}, + {"total-bytes-sec", VSH_OT_INT, VSH_OFLAG_NONE, N_("total throughput limit in bytes per second")}, - {"read_bytes_sec", VSH_OT_INT, VSH_OFLAG_NONE, + {"read_bytes_sec", VSH_OT_ALIAS, 0, "read-bytes-sec"}, + {"read-bytes-sec", VSH_OT_INT, VSH_OFLAG_NONE, N_("read throughput limit in bytes per second")}, - {"write_bytes_sec", VSH_OT_INT, VSH_OFLAG_NONE, + {"write_bytes_sec", VSH_OT_ALIAS, 0, "write-bytes-sec"}, + {"write-bytes-sec", VSH_OT_INT, VSH_OFLAG_NONE, N_("write throughput limit in bytes per second")}, - {"total_iops_sec", VSH_OT_INT, VSH_OFLAG_NONE, + {"total_iops_sec", VSH_OT_ALIAS, 0, "total-iops-sec"}, + {"total-iops-sec", VSH_OT_INT, VSH_OFLAG_NONE, N_("total I/O operations limit per second")}, - {"read_iops_sec", VSH_OT_INT, VSH_OFLAG_NONE, + {"read_iops_sec", VSH_OT_ALIAS, 0, "read-iops-sec"}, + {"read-iops-sec", VSH_OT_INT, VSH_OFLAG_NONE, N_("read I/O operations limit per second")}, - {"write_iops_sec", VSH_OT_INT, VSH_OFLAG_NONE, + {"write_iops_sec", VSH_OT_ALIAS, 0, "write-iops-sec"}, + {"write-iops-sec", VSH_OT_INT, VSH_OFLAG_NONE, N_("write I/O operations limit per second")}, {"config", VSH_OT_BOOL, 0, N_("affect next boot")}, {"live", VSH_OT_BOOL, 0, N_("affect running domain")}, @@ -7630,7 +7637,8 @@ cmdBlkdeviotune(vshControl *ctl, const vshCmd *cmd) if (vshCommandOptString(cmd, "device", &disk) < 0) goto cleanup; - if ((rv = vshCommandOptULongLong(cmd, "total_bytes_sec", &total_bytes_sec)) < 0) { + if ((rv = vshCommandOptULongLong(cmd, "total-bytes-sec", + &total_bytes_sec)) < 0) { vshError(ctl, "%s", _("Unable to parse integer parameter")); goto cleanup; @@ -7638,7 +7646,8 @@ cmdBlkdeviotune(vshControl *ctl, const vshCmd *cmd) nparams++; } - if ((rv = vshCommandOptULongLong(cmd, "read_bytes_sec", &read_bytes_sec)) < 0) { + if ((rv = vshCommandOptULongLong(cmd, "read-bytes-sec", + &read_bytes_sec)) < 0) { vshError(ctl, "%s", _("Unable to parse integer parameter")); goto cleanup; @@ -7646,7 +7655,8 @@ cmdBlkdeviotune(vshControl *ctl, const vshCmd *cmd) nparams++; } - if ((rv = vshCommandOptULongLong(cmd, "write_bytes_sec", &write_bytes_sec)) < 0) { + if ((rv = vshCommandOptULongLong(cmd, "write-bytes-sec", + &write_bytes_sec)) < 0) { vshError(ctl, "%s", _("Unable to parse integer parameter")); goto cleanup; @@ -7654,7 +7664,8 @@ cmdBlkdeviotune(vshControl *ctl, const vshCmd *cmd) nparams++; } - if ((rv = vshCommandOptULongLong(cmd, "total_iops_sec", &total_iops_sec)) < 0) { + if ((rv = vshCommandOptULongLong(cmd, "total-iops-sec", + &total_iops_sec)) < 0) { vshError(ctl, "%s", _("Unable to parse integer parameter")); goto cleanup; @@ -7662,7 +7673,8 @@ cmdBlkdeviotune(vshControl *ctl, const vshCmd *cmd) nparams++; } - if ((rv = vshCommandOptULongLong(cmd, "read_iops_sec", &read_iops_sec)) < 0) { + if ((rv = vshCommandOptULongLong(cmd, "read-iops-sec", + &read_iops_sec)) < 0) { vshError(ctl, "%s", _("Unable to parse integer parameter")); goto cleanup; @@ -7670,7 +7682,8 @@ cmdBlkdeviotune(vshControl *ctl, const vshCmd *cmd) nparams++; } - if ((rv = vshCommandOptULongLong(cmd, "write_iops_sec", &write_iops_sec)) < 0) { + if ((rv = vshCommandOptULongLong(cmd, "write-iops-sec", + &write_iops_sec)) < 0) { vshError(ctl, "%s", _("Unable to parse integer parameter")); goto cleanup; @@ -7712,7 +7725,7 @@ cmdBlkdeviotune(vshControl *ctl, const vshCmd *cmd) params = vshCalloc(ctl, nparams, sizeof(*params)); i = 0; - if ((i < nparams) && (vshCommandOptBool(cmd, "total_bytes_sec"))) { + if ((i < nparams) && (vshCommandOptBool(cmd, "total-bytes-sec"))) { temp = ¶ms[i]; temp->type = VIR_TYPED_PARAM_ULLONG; strncpy(temp->field, VIR_DOMAIN_BLOCK_IOTUNE_TOTAL_BYTES_SEC, @@ -7721,7 +7734,7 @@ cmdBlkdeviotune(vshControl *ctl, const vshCmd *cmd) i++; } - if ((i < nparams) && (vshCommandOptBool(cmd, "read_bytes_sec"))) { + if ((i < nparams) && (vshCommandOptBool(cmd, "read-bytes-sec"))) { temp = ¶ms[i]; temp->type = VIR_TYPED_PARAM_ULLONG; strncpy(temp->field, VIR_DOMAIN_BLOCK_IOTUNE_READ_BYTES_SEC, @@ -7730,7 +7743,7 @@ cmdBlkdeviotune(vshControl *ctl, const vshCmd *cmd) i++; } - if ((i < nparams) && (vshCommandOptBool(cmd, "write_bytes_sec"))) { + if ((i < nparams) && (vshCommandOptBool(cmd, "write-bytes-sec"))) { temp = ¶ms[i]; temp->type = VIR_TYPED_PARAM_ULLONG; strncpy(temp->field, VIR_DOMAIN_BLOCK_IOTUNE_WRITE_BYTES_SEC, @@ -7739,7 +7752,7 @@ cmdBlkdeviotune(vshControl *ctl, const vshCmd *cmd) i++; } - if ((i < nparams) && (vshCommandOptBool(cmd, "total_iops_sec"))) { + if ((i < nparams) && (vshCommandOptBool(cmd, "total-iops-sec"))) { temp = ¶ms[i]; temp->type = VIR_TYPED_PARAM_ULLONG; strncpy(temp->field, VIR_DOMAIN_BLOCK_IOTUNE_TOTAL_IOPS_SEC, @@ -7748,7 +7761,7 @@ cmdBlkdeviotune(vshControl *ctl, const vshCmd *cmd) i++; } - if ((i < nparams) && (vshCommandOptBool(cmd, "read_iops_sec"))) { + if ((i < nparams) && (vshCommandOptBool(cmd, "read-iops-sec"))) { temp = ¶ms[i]; temp->type = VIR_TYPED_PARAM_ULLONG; strncpy(temp->field, VIR_DOMAIN_BLOCK_IOTUNE_READ_IOPS_SEC, @@ -7757,7 +7770,7 @@ cmdBlkdeviotune(vshControl *ctl, const vshCmd *cmd) i++; } - if ((i < nparams) && (vshCommandOptBool(cmd, "write_iops_sec"))) { + if ((i < nparams) && (vshCommandOptBool(cmd, "write-iops-sec"))) { temp = ¶ms[i]; temp->type = VIR_TYPED_PARAM_ULLONG; strncpy(temp->field, VIR_DOMAIN_BLOCK_IOTUNE_WRITE_IOPS_SEC, diff --git a/tools/virsh.pod b/tools/virsh.pod index 8f6a2d6..1bc55c4 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -614,8 +614,8 @@ I<bandwidth> specifies copying bandwidth limit in Mbps. =item B<blkdeviotune> I<domain> I<device> [[I<--config>] [I<--live>] | [I<--current>]] -[[I<total_bytes_sec>] | [I<read_bytes_sec>] [I<write_bytes_sec>]] -[[I<total_iops_sec>] | [I<read_iops_sec>] [I<write_iops_sec>]] +[[I<total-bytes-sec>] | [I<read-bytes-sec>] [I<write-bytes-sec>]] +[[I<total-iops-sec>] | [I<read-iops-sec>] [I<write-iops-sec>]] Set or query the block disk io parameters for a block device of I<domain>. I<device> specifies a unique target name (<target dev='name'/>) or source @@ -624,15 +624,15 @@ I<domain> (see also B<domblklist> for listing these names). If no limit is specified, it will query current I/O limits setting. Otherwise, alter the limits with these flags: -I<--total_bytes_sec> specifies total throughput limit in bytes per second. -I<--read_bytes_sec> specifies read throughput limit in bytes per second. -I<--write_bytes_sec> specifies write throughput limit in bytes per second. -I<--total_iops_sec> specifies total I/O operations limit per second. -I<--read_iops_sec> specifies read I/O operations limit per second. -I<--write_iops_sec> specifies write I/O operations limit per second. +I<--total-bytes-sec> specifies total throughput limit in bytes per second. +I<--read-bytes-sec> specifies read throughput limit in bytes per second. +I<--write-bytes-sec> specifies write throughput limit in bytes per second. +I<--total-iops-sec> specifies total I/O operations limit per second. +I<--read-iops-sec> specifies read I/O operations limit per second. +I<--write-iops-sec> specifies write I/O operations limit per second. Bytes and iops values are independent, but setting only one value (such -as --read_bytes_sec) resets the other two in that category to unlimited. +as --read-bytes-sec) resets the other two in that category to unlimited. An explicit 0 also clears any limit. A non-zero value for a given total cannot be mixed with non-zero values for read or write. -- 1.7.7.6
On 03/03/2012 09:02 AM, Eric Blake wrote:
Command line interfaces should use dash, not underscore, as many keyboard layouts allow that to be typed with fewer shift key presses.
Also, the US spelling of --tunneled gets more google hits than the UK spelling of --tunnelled.
* tools/virsh.c (opts_migrate): Allow US variant. (opts_blkdeviotune): Prefer - over _. * tools/virsh.pod (blkdeviotune): Fix spelling. --- tools/virsh.c | 49 +++++++++++++++++++++++++++++++------------------ tools/virsh.pod | 18 +++++++++--------- 2 files changed, 40 insertions(+), 27 deletions(-)
ACK
Just because our public API has a typo doesn't mean that virsh has to keep the typo. * tools/virsh.c (VSH_CMD_FLAG_ALIAS): New flag. (nodedevCmds): Use it. (cmdHelp): Omit alias commands. (cmdNodeDeviceDettach): Rename... (cmdNodeDeviceDetach): ...to this. * tools/virsh.pod (nodedev-detach): Document it. --- tools/virsh.c | 30 +++++++++++++++++++----------- tools/virsh.pod | 10 ++++++---- 2 files changed, 25 insertions(+), 15 deletions(-) diff --git a/tools/virsh.c b/tools/virsh.c index 75a1a3b..4361a6b 100644 --- a/tools/virsh.c +++ b/tools/virsh.c @@ -212,6 +212,7 @@ typedef struct vshCmdOpt { */ enum { VSH_CMD_FLAG_NOCONNECT = (1 << 0), /* no prior connection needed */ + VSH_CMD_FLAG_ALIAS = (1 << 1), /* command is an alias */ }; /* @@ -685,9 +686,12 @@ cmdHelp(vshControl *ctl, const vshCmd *cmd) vshPrint(ctl, _(" %s (help keyword '%s'):\n"), grp->name, grp->keyword); - for (def = grp->commands; def->name; def++) + for (def = grp->commands; def->name; def++) { + if (def->flags & VSH_CMD_FLAG_ALIAS) + continue; vshPrint(ctl, " %-30s %s\n", def->name, _(vshCmddefGetInfo(def, "help"))); + } vshPrint(ctl, "\n"); } @@ -12939,22 +12943,22 @@ cmdNodeDeviceDumpXML (vshControl *ctl, const vshCmd *cmd) } /* - * "nodedev-dettach" command + * "nodedev-detach" command */ -static const vshCmdInfo info_node_device_dettach[] = { - {"help", N_("dettach node device from its device driver")}, - {"desc", N_("Dettach node device from its device driver before assigning to a domain.")}, +static const vshCmdInfo info_node_device_detach[] = { + {"help", N_("detach node device from its device driver")}, + {"desc", N_("Detach node device from its device driver before assigning to a domain.")}, {NULL, NULL} }; -static const vshCmdOptDef opts_node_device_dettach[] = { +static const vshCmdOptDef opts_node_device_detach[] = { {"device", VSH_OT_DATA, VSH_OFLAG_REQ, N_("device key")}, {NULL, 0, 0, NULL} }; static bool -cmdNodeDeviceDettach (vshControl *ctl, const vshCmd *cmd) +cmdNodeDeviceDetach (vshControl *ctl, const vshCmd *cmd) { const char *name = NULL; virNodeDevicePtr device; @@ -12969,10 +12973,12 @@ cmdNodeDeviceDettach (vshControl *ctl, const vshCmd *cmd) return false; } + /* Yes, our public API is misspelled. At least virsh can accept + * either spelling. */ if (virNodeDeviceDettach(device) == 0) { - vshPrint(ctl, _("Device %s dettached\n"), name); + vshPrint(ctl, _("Device %s detached\n"), name); } else { - vshError(ctl, _("Failed to dettach device %s"), name); + vshError(ctl, _("Failed to detach device %s"), name); ret = false; } virNodeDeviceFree(device); @@ -17090,8 +17096,10 @@ static const vshCmdDef nodedevCmds[] = { info_node_device_create, 0}, {"nodedev-destroy", cmdNodeDeviceDestroy, opts_node_device_destroy, info_node_device_destroy, 0}, - {"nodedev-dettach", cmdNodeDeviceDettach, opts_node_device_dettach, - info_node_device_dettach, 0}, + {"nodedev-detach", cmdNodeDeviceDetach, opts_node_device_detach, + info_node_device_detach, 0}, + {"nodedev-dettach", cmdNodeDeviceDetach, opts_node_device_detach, + info_node_device_detach, VSH_CMD_FLAG_ALIAS}, {"nodedev-dumpxml", cmdNodeDeviceDumpXML, opts_node_device_dumpxml, info_node_device_dumpxml, 0}, {"nodedev-list", cmdNodeListDevices, opts_node_list_devices, diff --git a/tools/virsh.pod b/tools/virsh.pod index 1bc55c4..b365624 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -1442,7 +1442,7 @@ Attach a device to the domain, using a device definition in an XML file. See the documentation to learn about libvirt XML format for a device. For cdrom and floppy devices, this command only replaces the media within the single existing device; consider using B<update-device> for this usage. -For passthrough host devices, see also B<nodedev-dettach>, needed if +For passthrough host devices, see also B<nodedev-detach>, needed if the device does not use managed mode. =item B<attach-disk> I<domain-id> I<source> I<target> @@ -1571,7 +1571,7 @@ guest domains, nor by multiple active guests at once. If the <hostdev> description includes the attribute B<managed='yes'>, and the hypervisor driver supports it, then the device is in managed mode, and attempts to use that passthrough device in an active guest will -automatically behave as if B<nodedev-dettach> (guest start, device +automatically behave as if B<nodedev-detach> (guest start, device hot-plug) and B<nodedev-reattach> (guest stop, device hot-unplug) were called at the right points (currently, qemu does this for PCI devices, but not USB). If a device is not marked as managed, then it must @@ -1596,11 +1596,13 @@ Destroy (stop) a device on the host. Note that this makes libvirt quit managing a host device, and may even make that device unusable by the rest of the physical host until a reboot. -=item B<nodedev-dettach> I<nodedev> +=item B<nodedev-detach> I<nodedev> Detach I<nodedev> from the host, so that it can safely be used by guests via <hostdev> passthrough. This is reversed with B<nodedev-reattach>, and is done automatically for managed devices. +For compatibility purposes, this command can also be spelled +B<nodedev-dettach>. =item B<nodedev-dumpxml> I<nodedev> @@ -1621,7 +1623,7 @@ formatted in a tree representing parents of each node. Declare that I<nodedev> is no longer in use by any guests, and that the host can resume normal use of the device. This is done automatically for devices in managed mode, but must be done explicitly -to match any explicit B<nodedev-dettach>. +to match any explicit B<nodedev-detach>. =item B<nodedev-reset> I<nodedev> -- 1.7.7.6
On 03/03/2012 09:02 AM, Eric Blake wrote:
Just because our public API has a typo doesn't mean that virsh has to keep the typo.
* tools/virsh.c (VSH_CMD_FLAG_ALIAS): New flag. (nodedevCmds): Use it. (cmdHelp): Omit alias commands. (cmdNodeDeviceDettach): Rename... (cmdNodeDeviceDetach): ...to this. * tools/virsh.pod (nodedev-detach): Document it. --- tools/virsh.c | 30 +++++++++++++++++++----------- tools/virsh.pod | 10 ++++++---- 2 files changed, 25 insertions(+), 15 deletions(-)
ACK, guy who plays with hostdev passthrough with be happly with the changes. :-) Osier
Since VIR_DOMAIN_AFFECT_{LIVE,CONFIG,CURRENT} was created, all new virsh commands use "--config" to represents the persistent changing. This patch add "--config" option for the old commands which still use "--persistent", and "--persistent" is now alias of "--config". tools/virsh.c: (use "--config", and "--persistent" is alias of "--config" now). cmdDomIfSetLink, cmdDomIfGetLink, cmdAttachDevice, cmdDetachDevice, cmdUpdateDevice, cmdAttachInterface, cmdDetachInterface, cmdAttachDisk, cmdDetachDisk toos/virsh.pod: Update docs of the changed commands, and add some missed docs for "--config" (detach-interface, detach-disk, and detach-device). --- tools/virsh.c | 51 ++++++++++++++++++++++++++++++--------------------- tools/virsh.pod | 36 ++++++++++++++++++++++-------------- 2 files changed, 52 insertions(+), 35 deletions(-) diff --git a/tools/virsh.c b/tools/virsh.c index ba3ea1c..3535ad1 100644 --- a/tools/virsh.c +++ b/tools/virsh.c @@ -1635,7 +1635,8 @@ static const vshCmdOptDef opts_domif_setlink[] = { {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")}, {"interface", VSH_OT_DATA, VSH_OFLAG_REQ, N_("interface device (MAC Address)")}, {"state", VSH_OT_DATA, VSH_OFLAG_REQ, N_("new state of the device")}, - {"persistent", VSH_OT_BOOL, 0, N_("persist interface state")}, + {"persistent", VSH_OT_ALIAS, 0, "config"}, + {"config", VSH_OT_BOOL, 0, N_("affect next boot")}, {NULL, 0, 0, NULL} }; @@ -1650,7 +1651,7 @@ cmdDomIfSetLink (vshControl *ctl, const vshCmd *cmd) unsigned char macaddr[VIR_MAC_BUFLEN]; const char *element; const char *attr; - bool persistent; + bool config; bool ret = false; unsigned int flags = 0; int i; @@ -1672,7 +1673,7 @@ cmdDomIfSetLink (vshControl *ctl, const vshCmd *cmd) if (vshCommandOptString(cmd, "state", &state) <= 0) goto cleanup; - persistent = vshCommandOptBool(cmd, "persistent"); + config = vshCommandOptBool(cmd, "config"); if (STRNEQ(state, "up") && STRNEQ(state, "down")) { vshError(ctl, _("invalid link state '%s'"), state); @@ -1680,13 +1681,13 @@ cmdDomIfSetLink (vshControl *ctl, const vshCmd *cmd) } /* get persistent or live description of network device */ - desc = virDomainGetXMLDesc(dom, persistent?VIR_DOMAIN_XML_INACTIVE:0); + desc = virDomainGetXMLDesc(dom, config ? VIR_DOMAIN_XML_INACTIVE : 0); if (desc == NULL) { vshError(ctl, _("Failed to get domain description xml")); goto cleanup; } - if (persistent) + if (config) flags = VIR_DOMAIN_AFFECT_CONFIG; else flags = VIR_DOMAIN_AFFECT_LIVE; @@ -1810,7 +1811,8 @@ static const vshCmdInfo info_domif_getlink[] = { static const vshCmdOptDef opts_domif_getlink[] = { {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")}, {"interface", VSH_OT_DATA, VSH_OFLAG_REQ, N_("interface device (MAC Address)")}, - {"persistent", VSH_OT_BOOL, 0, N_("Get persistent interface state")}, + {"persistent", VSH_OT_ALIAS, 0, "config"}, + {"config", VSH_OT_BOOL, 0, N_("Get persistent interface state")}, {NULL, 0, 0, NULL} }; @@ -1844,7 +1846,7 @@ cmdDomIfGetLink (vshControl *ctl, const vshCmd *cmd) return false; } - if (vshCommandOptBool(cmd, "persistent")) + if (vshCommandOptBool(cmd, "config")) flags = VIR_DOMAIN_XML_INACTIVE; desc = virDomainGetXMLDesc(dom, flags); @@ -13439,7 +13441,8 @@ static const vshCmdInfo info_attach_device[] = { static const vshCmdOptDef opts_attach_device[] = { {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")}, {"file", VSH_OT_DATA, VSH_OFLAG_REQ, N_("XML file")}, - {"persistent", VSH_OT_BOOL, 0, N_("persist device attachment")}, + {"persistent", VSH_OT_ALIAS, 0, "config"}, + {"config", VSH_OT_BOOL, 0, N_("affect next boot")}, {NULL, 0, 0, NULL} }; @@ -13469,7 +13472,7 @@ cmdAttachDevice(vshControl *ctl, const vshCmd *cmd) return false; } - if (vshCommandOptBool(cmd, "persistent")) { + if (vshCommandOptBool(cmd, "config")) { flags = VIR_DOMAIN_AFFECT_CONFIG; if (virDomainIsActive(dom) == 1) flags |= VIR_DOMAIN_AFFECT_LIVE; @@ -13750,7 +13753,8 @@ static const vshCmdInfo info_detach_device[] = { static const vshCmdOptDef opts_detach_device[] = { {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")}, {"file", VSH_OT_DATA, VSH_OFLAG_REQ, N_("XML file")}, - {"persistent", VSH_OT_BOOL, 0, N_("persist device detachment")}, + {"persistent", VSH_OT_ALIAS, 0, "config"}, + {"config", VSH_OT_BOOL, 0, N_("affect next boot")}, {NULL, 0, 0, NULL} }; @@ -13778,7 +13782,7 @@ cmdDetachDevice(vshControl *ctl, const vshCmd *cmd) goto cleanup; } - if (vshCommandOptBool(cmd, "persistent")) { + if (vshCommandOptBool(cmd, "config")) { flags = VIR_DOMAIN_AFFECT_CONFIG; if (virDomainIsActive(dom) == 1) flags |= VIR_DOMAIN_AFFECT_LIVE; @@ -13814,7 +13818,8 @@ static const vshCmdInfo info_update_device[] = { static const vshCmdOptDef opts_update_device[] = { {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")}, {"file", VSH_OT_DATA, VSH_OFLAG_REQ, N_("XML file")}, - {"persistent", VSH_OT_BOOL, 0, N_("persist device update")}, + {"persistent", VSH_OT_ALIAS, 0, "config"}, + {"config", VSH_OT_BOOL, 0, N_("affect next boot")}, {"force", VSH_OT_BOOL, 0, N_("force device update")}, {NULL, 0, 0, NULL} }; @@ -13845,7 +13850,7 @@ cmdUpdateDevice(vshControl *ctl, const vshCmd *cmd) return false; } - if (vshCommandOptBool(cmd, "persistent")) { + if (vshCommandOptBool(cmd, "config")) { flags = VIR_DOMAIN_AFFECT_CONFIG; if (virDomainIsActive(dom) == 1) flags |= VIR_DOMAIN_AFFECT_LIVE; @@ -13889,7 +13894,8 @@ static const vshCmdOptDef opts_attach_interface[] = { {"mac", VSH_OT_DATA, 0, N_("MAC address")}, {"script", VSH_OT_DATA, 0, N_("script used to bridge network interface")}, {"model", VSH_OT_DATA, 0, N_("model type")}, - {"persistent", VSH_OT_BOOL, 0, N_("persist interface attachment")}, + {"persistent", VSH_OT_ALIAS, 0, "config"}, + {"config", VSH_OT_BOOL, 0, N_("affect next boot")}, {"inbound", VSH_OT_DATA, VSH_OFLAG_NONE, N_("control domain's incoming traffics")}, {"outbound", VSH_OT_DATA, VSH_OFLAG_NONE, N_("control domain's outgoing traffics")}, {NULL, 0, 0, NULL} @@ -14046,7 +14052,7 @@ cmdAttachInterface(vshControl *ctl, const vshCmd *cmd) xml = virBufferContentAndReset(&buf); - if (vshCommandOptBool(cmd, "persistent")) { + if (vshCommandOptBool(cmd, "config")) { flags = VIR_DOMAIN_AFFECT_CONFIG; if (virDomainIsActive(dom) == 1) flags |= VIR_DOMAIN_AFFECT_LIVE; @@ -14084,7 +14090,8 @@ static const vshCmdOptDef opts_detach_interface[] = { {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")}, {"type", VSH_OT_DATA, VSH_OFLAG_REQ, N_("network interface type")}, {"mac", VSH_OT_STRING, 0, N_("MAC address")}, - {"persistent", VSH_OT_BOOL, 0, N_("persist interface detachment")}, + {"persistent", VSH_OT_ALIAS, 0, "config"}, + {"config", VSH_OT_BOOL, 0, N_("affect next boot")}, {NULL, 0, 0, NULL} }; @@ -14178,7 +14185,7 @@ cmdDetachInterface(vshControl *ctl, const vshCmd *cmd) goto cleanup; } - if (vshCommandOptBool(cmd, "persistent")) { + if (vshCommandOptBool(cmd, "config")) { flags = VIR_DOMAIN_AFFECT_CONFIG; if (virDomainIsActive(dom) == 1) flags |= VIR_DOMAIN_AFFECT_LIVE; @@ -14225,7 +14232,8 @@ static const vshCmdOptDef opts_attach_disk[] = { {"cache", VSH_OT_STRING, 0, N_("cache mode of disk device")}, {"type", VSH_OT_STRING, 0, N_("target device type")}, {"mode", VSH_OT_STRING, 0, N_("mode of device reading and writing")}, - {"persistent", VSH_OT_BOOL, 0, N_("persist disk attachment")}, + {"persistent", VSH_OT_ALIAS, 0, "config"}, + {"config", VSH_OT_BOOL, 0, N_("affect next boot")}, {"sourcetype", VSH_OT_STRING, 0, N_("type of source (block|file)")}, {"serial", VSH_OT_STRING, 0, N_("serial of disk device")}, {"shareable", VSH_OT_BOOL, 0, N_("shareable between domains")}, @@ -14534,7 +14542,7 @@ cmdAttachDisk(vshControl *ctl, const vshCmd *cmd) xml = virBufferContentAndReset(&buf); - if (vshCommandOptBool(cmd, "persistent")) { + if (vshCommandOptBool(cmd, "config")) { flags = VIR_DOMAIN_AFFECT_CONFIG; if (virDomainIsActive(dom) == 1) flags |= VIR_DOMAIN_AFFECT_LIVE; @@ -14784,7 +14792,8 @@ static const vshCmdInfo info_detach_disk[] = { static const vshCmdOptDef opts_detach_disk[] = { {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")}, {"target", VSH_OT_DATA, VSH_OFLAG_REQ, N_("target of disk device")}, - {"persistent", VSH_OT_BOOL, 0, N_("persist disk detachment")}, + {"persistent", VSH_OT_ALIAS, 0, "config"}, + {"config", VSH_OT_BOOL, 0, N_("affect next boot")}, {NULL, 0, 0, NULL} }; @@ -14820,7 +14829,7 @@ cmdDetachDisk(vshControl *ctl, const vshCmd *cmd) VSH_PREPARE_DISK_XML_NONE))) goto cleanup; - if (vshCommandOptBool(cmd, "persistent")) { + if (vshCommandOptBool(cmd, "config")) { flags = VIR_DOMAIN_AFFECT_CONFIG; if (virDomainIsActive(dom) == 1) flags |= VIR_DOMAIN_AFFECT_LIVE; diff --git a/tools/virsh.pod b/tools/virsh.pod index 54aef05..e91a2bf 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -526,16 +526,16 @@ B<Explanation of fields> (fields appear in the folowing order): Get network interface stats for a running domain. -=item B<domif-setlink> I<domain> I<interface-device> I<state> I<--persistent> +=item B<domif-setlink> I<domain> I<interface-device> I<state> [I<--config>] Modify link state of the domain's virtual interface. Possible values for -state are "up" and "down. If --persistent is specified, only the persistent +state are "up" and "down. If I<--config> is specified, only the persistent configuration of the domain is modified. I<interface-device> can be the interface's target name or the MAC address. -=item B<domif-getlink> I<domain> I<interface-device> I<--persistent> +=item B<domif-getlink> I<domain> I<interface-device> [I<--config>] -Query link state of the domain's virtual interface. If --persistent +Query link state of the domain's virtual interface. If I<--config> is specified, query the persistent configuration. I<interface-device> can be the interface's target name or the MAC address. @@ -1444,10 +1444,12 @@ format of the device sections to get the most accurate set of accepted values. =over 4 -=item B<attach-device> I<domain-id> I<FILE> +=item B<attach-device> I<domain-id> I<FILE> [I<--config>] Attach a device to the domain, using a device definition in an XML file. See the documentation to learn about libvirt XML format for a device. +If I<--config> is specified, alter persistent configuration, effect observed +on next boot. For cdrom and floppy devices, this command only replaces the media within the single existing device; consider using B<update-device> for this usage. For passthrough host devices, see also B<nodedev-dettach>, needed if @@ -1455,7 +1457,7 @@ the device does not use managed mode. =item B<attach-disk> I<domain-id> I<source> I<target> [I<--driver driver>] [I<--subdriver subdriver>] [I<--cache cache>] -[I<--type type>] [I<--mode mode>] [I<--persistent>] [I<--sourcetype soucetype>] +[I<--type type>] [I<--mode mode>] [I<--config>] [I<--sourcetype soucetype>] [I<--serial serial>] [I<--shareable>] [I<--rawio>] [I<--address address>] [I<--multifunction>] @@ -1467,7 +1469,7 @@ I<type> can indicate I<cdrom> or I<floppy> as alternative to the disk default, although this use only replaces the media within the existing virtual cdrom or floppy device; consider using B<update-device> for this usage instead. I<mode> can specify the two specific mode I<readonly> or I<shareable>. -I<persistent> indicates the changes will affect the next boot of the domain. +I<--config> indicates the changes will affect the next boot of the domain. I<sourcetype> can indicate the type of source (block|file) I<cache> can be one of "default", "none", "writethrough", "writeback", "directsync" or "unsafe". @@ -1481,7 +1483,7 @@ address. =item B<attach-interface> I<domain-id> I<type> I<source> [I<--target target>] [I<--mac mac>] [I<--script script>] [I<--model model>] -[I<--persistent>] [I<--inbound average,peak,burst>] [I<--outbound average,peak,burst>] +[I<--config>] [I<--inbound average,peak,burst>] [I<--outbound average,peak,burst>] Attach a new network interface to the domain. I<type> can be either I<network> to indicate a physical network device or @@ -1492,7 +1494,7 @@ I<mac> allows to specify the MAC address of the network interface. I<script> allows to specify a path to a script handling a bridge instead of the default one. I<model> allows to specify the model type. -I<persistent> indicates the changes will affect the next boot of the domain. +I<--config> indicates the changes will affect the next boot of the domain. I<inbound> and I<outbound> control the bandwidth of the interface. I<peak> and I<burst> are optional, so "average,peak", "average,,burst" and "average" are also legal. @@ -1501,30 +1503,36 @@ B<Note>: the optional target value is the name of a device to be created as the back-end on the node. If not provided a device named "vnetN" or "vifN" will be created automatically. -=item B<detach-device> I<domain-id> I<FILE> +=item B<detach-device> I<domain-id> I<FILE> [I<--config>] Detach a device from the domain, takes the same kind of XML descriptions as command B<attach-device>. +If I<--config> is specified, alter persistent configuration, effect observed +on next boot. For passthrough host devices, see also B<nodedev-reattach>, needed if the device does not use managed mode. -=item B<detach-disk> I<domain-id> I<target> +=item B<detach-disk> I<domain-id> I<target> [I<--config>] Detach a disk device from a domain. The I<target> is the device as seen from the domain. +If I<--config> is specified, alter persistent configuration, effect observed +on next boot. -=item B<detach-interface> I<domain-id> I<type> [I<--mac mac>] +=item B<detach-interface> I<domain-id> I<type> [I<--mac mac>] [I<--config>] Detach a network interface from a domain. I<type> can be either I<network> to indicate a physical network device or I<bridge> to indicate a bridge to a device. It is recommended to use the I<mac> option to distinguish between the interfaces if more than one are present on the domain. +If I<--config> is specified, alter persistent configuration, effect observed +on next boot. -=item B<update-device> I<domain-id> I<file> [I<--persistent>] [I<--force>] +=item B<update-device> I<domain-id> I<file> [I<--config>] [I<--force>] Update the characteristics of a device associated with I<domain-id>, based on -the device definition in an XML I<file>. If the I<--persistent> option is +the device definition in an XML I<file>. If the I<--config> option is used, the changes will affect the next boot of the domain. The I<--force> option can be used to force device update, e.g., to eject a CD-ROM even if it is locked/mounted in the domain. See the documentation to learn about libvirt -- 1.7.1
On 03/07/2012 03:17 AM, Osier Yang wrote:
Since VIR_DOMAIN_AFFECT_{LIVE,CONFIG,CURRENT} was created, all new virsh commands use "--config" to represents the persistent changing. This patch add "--config" option for the old commands which still use "--persistent", and "--persistent" is now alias of "--config".
tools/virsh.c: (use "--config", and "--persistent" is alias of "--config" now). cmdDomIfSetLink, cmdDomIfGetLink, cmdAttachDevice, cmdDetachDevice, cmdUpdateDevice, cmdAttachInterface, cmdDetachInterface, cmdAttachDisk, cmdDetachDisk
toos/virsh.pod: Update docs of the changed commands, and add some missed docs for "--config" (detach-interface, detach-disk, and detach-device). --- tools/virsh.c | 51 ++++++++++++++++++++++++++++++--------------------- tools/virsh.pod | 36 ++++++++++++++++++++++-------------- 2 files changed, 52 insertions(+), 35 deletions(-)
The code looks fine. Per the previous patches, we should document in virsh.pod that older versions of virsh understood --persistent, so it's probably worth a v2 to make sure we like the docs. -- Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
participants (2)
-
Eric Blake -
Osier Yang