tools/vsh.h

   1 /*
   2  * vsh.h: common data to be used by clients to exercise the libvirt API
   3  *
   4  * Copyright (C) 2005, 2007-2015 Red Hat, Inc.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library.  If not, see
  18  * <http://www.gnu.org/licenses/>.
  19  */
  20
  21 #pragma once
  22
  23 #include <stdarg.h>
  24 #ifndef WIN32
  25 # include <termios.h>
  26 #endif
  27
  28 #include "internal.h"
  29 #include "virthread.h"
  30
  31 #define VIR_FROM_THIS VIR_FROM_NONE
  32
  33 #define VSH_MAX_XML_FILE (10*1024*1024)
  34 #define VSH_MATCH(FLAG) (flags & (FLAG))
  35
  36 /**
  37  * The log configuration
  38  */
  39 #define MSG_BUFFER    4096
  40 #define DIR_MODE      (S_IWUSR | S_IRUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH)  /* 0755 */
  41 #define FILE_MODE     (S_IWUSR | S_IRUSR | S_IRGRP | S_IROTH)                                /* 0644 */
  42 #define LOCK_MODE     (S_IWUSR | S_IRUSR)                                                    /* 0600 */
  43 #define LVL_DEBUG     "DEBUG"
  44 #define LVL_INFO      "INFO"
  45 #define LVL_NOTICE    "NOTICE"
  46 #define LVL_WARNING   "WARNING"
  47 #define LVL_ERROR     "ERROR"
  48
  49 /**
  50  * vshErrorLevel:
  51  *
  52  * Indicates the level of a log message
  53  */
  54 typedef enum {
  55     VSH_ERR_DEBUG = 0,
  56     VSH_ERR_INFO,
  57     VSH_ERR_NOTICE,
  58     VSH_ERR_WARNING,
  59     VSH_ERR_ERROR
  60 } vshErrorLevel;
  61
  62 #define VSH_DEBUG_DEFAULT VSH_ERR_ERROR
  63
  64 /*
  65  * virsh command line grammar:
  66  *
  67  *    command_line    =     <command>\n | <command>; <command>; ...
  68  *
  69  *    command         =    <keyword> <option> [--] <data>
  70  *
  71  *    option          =     <bool_option> | <int_option> | <string_option>
  72  *    data            =     <string>
  73  *
  74  *    bool_option     =     --optionname
  75  *    int_option      =     --optionname <number> | --optionname=<number>
  76  *    string_option   =     --optionname <string> | --optionname=<string>
  77  *
  78  *    keyword         =     [a-zA-Z][a-zA-Z-]*
  79  *    number          =     [0-9]+
  80  *    string          =     ('[^']*'|"([^\\"]|\\.)*"|([^ \t\n\\'"]|\\.))+
  81  *
  82  */
  83
  84 /*
  85  * vshCmdOptType - command option type
  86  */
  87 typedef enum {
  88     VSH_OT_NONE = 0, /* cannary to catch programming errors */
  89     VSH_OT_BOOL,     /* optional boolean option */
  90     VSH_OT_STRING,   /* optional string option */
  91     VSH_OT_INT,      /* optional or mandatory int option */
  92     VSH_OT_ARGV,     /* remaining arguments */
  93     VSH_OT_ALIAS,    /* alternate spelling for a later argument */
  94 } vshCmdOptType;
  95
  96 /* forward declarations */
  97 typedef struct _vshClientHooks vshClientHooks;
  98 typedef struct _vshCmd vshCmd;
  99 typedef struct _vshCmdDef vshCmdDef;
 100 typedef struct _vshCmdGrp vshCmdGrp;
 101 typedef struct _vshCmdInfo vshCmdInfo;
 102 typedef struct _vshCmdOpt vshCmdOpt;
 103 typedef struct _vshCmdOptDef vshCmdOptDef;
 104 typedef struct _vshControl vshControl;
 105
 106 typedef char **(*vshCompleter)(vshControl *ctl,
 107                                const vshCmd *cmd,
 108                                unsigned int flags);
 109
 110 /*
 111  * "help" - short description of command
 112  * "desc" - description of command, or empty string
 113  */
 114 struct _vshCmdInfo {
 115     const char *help;           /* short description of command */
 116     const char *desc;           /* description of command */
 117 };
 118
 119 /*
 120  * vshCmdOptDef - command option definition
 121  */
 122 struct _vshCmdOptDef {
 123     const char *name;           /* the name of option, or NULL for list end */
 124     vshCmdOptType type;         /* option type */
 125     bool required;              /* option is required */
 126     bool positional;            /* option is a positional option (not requiring '--optionname') */
 127
 128     /* Historically the command parser in virsh allowed many optional arguments
 129      * which were documented as non-positional to be filled positionally. To
 130      * preserve this functionality those need to be annotated with the
 131      * 'unwanted_positional' flag. New options must not use this flag */
 132     bool unwanted_positional;
 133
 134     bool allowEmpty;            /* allow empty string */
 135     const char *help;           /* non-NULL help string; or for VSH_OT_ALIAS
 136                                  * the name of a later public option */
 137     vshCompleter completer;         /* option completer */
 138     unsigned int completer_flags;   /* option completer flags */
 139 };
 140
 141 /*
 142  * vshCmdOpt - command options
 143  *
 144  * After parsing a command, all arguments to the command have been
 145  * collected into a list of these objects.
 146  */
 147 struct _vshCmdOpt {
 148     const vshCmdOptDef *def;    /* non-NULL pointer to option definition */
 149     char *data;                 /* allocated data, or NULL for bool option */
 150     const char **argv;          /* for VSH_OT_ARGV, the list of options */
 151     char *argvstr;              /* space-joined @argv */
 152     vshCmdOpt *next;
 153 };
 154
 155 /*
 156  * Command Usage Flags
 157  */
 158 enum {
 159     VSH_CMD_FLAG_NOCONNECT = (1 << 0),  /* no prior connection needed */
 160     VSH_CMD_FLAG_HIDDEN    = (1 << 1),  /* command is hidden/internal */
 161 };
 162
 163 /*
 164  * vshCmdDef - command definition
 165  */
 166 struct _vshCmdDef {
 167     const char *name;           /* name of command, or NULL for list end */
 168     bool (*handler) (vshControl *, const vshCmd *);    /* command handler */
 169     const vshCmdOptDef *opts;   /* definition of command options */
 170     const vshCmdInfo *info;     /* details about command */
 171     unsigned int flags;         /* bitwise OR of VSH_CMD_FLAG */
 172     const char *alias;          /* name of the aliased command */
 173 };
 174
 175 /*
 176  * vshCmd - parsed command
 177  */
 178 struct _vshCmd {
 179     const vshCmdDef *def;       /* command definition */
 180     vshCmdOpt *opts;            /* list of command arguments */
 181     vshCmdOpt *lastopt;         /* last option of the commandline */
 182     vshCmd *next;               /* next command */
 183     bool skipChecks;            /* skip validity checks when retrieving opts */
 184 };
 185
 186 /*
 187  * vshControl
 188  */
 189 struct _vshControl {
 190     const char *name;           /* hardcoded name of the binary that cannot
 191                                  * be changed without recompilation compared
 192                                  * to program name */
 193     const char *env_prefix;     /* hardcoded environment variable prefix */
 194     char *connname;             /* connection name */
 195     char *progname;             /* program name */
 196     vshCmd *cmd;                /* the current command */
 197     char *cmdstr;               /* string with command */
 198     bool imode;                 /* interactive mode? */
 199     bool quiet;                 /* quiet mode */
 200     bool timing;                /* print timing info? */
 201     int debug;                  /* print debug messages? */
 202     char *logfile;              /* log file name */
 203     int log_fd;                 /* log file descriptor */
 204     char *historydir;           /* readline history directory name */
 205     char *historyfile;          /* readline history file name */
 206     virThread eventLoop;
 207     virMutex lock;
 208     bool eventLoopStarted;
 209     bool quit;
 210     int eventPipe[2];           /* Write-to-self pipe to end waiting for an
 211                                  * event to occur */
 212     int eventTimerId;           /* id of event loop timeout registration */
 213
 214     int keepalive_interval;     /* Client keepalive interval */
 215     int keepalive_count;        /* Client keepalive count */
 216
 217 #ifndef WIN32
 218     struct termios termattr;    /* settings of the tty terminal */
 219 #endif
 220     bool istty;                 /* is the terminal a tty */
 221
 222     const vshClientHooks *hooks;/* mandatory client specific hooks */
 223     void *privData;             /* client specific data */
 224 };
 225
 226 typedef void *
 227 (*vshConnectionHook)(vshControl *ctl);
 228
 229 struct _vshClientHooks {
 230     vshConnectionHook connHandler;
 231 };
 232
 233 struct _vshCmdGrp {
 234     const char *name;    /* name of group, or NULL for list end */
 235     const char *keyword; /* help keyword */
 236     const vshCmdDef *commands;
 237 };
 238
 239 void vshError(vshControl *ctl, const char *format, ...)
 240     G_GNUC_PRINTF(2, 3);
 241 void vshOpenLogFile(vshControl *ctl);
 242 void vshOutputLogFile(vshControl *ctl, int log_level, const char *format,
 243                       va_list ap)
 244     G_GNUC_PRINTF(3, 0);
 245 void vshCloseLogFile(vshControl *ctl);
 246
 247 const vshCmdDef *vshCmddefSearch(const char *cmdname);
 248 const vshCmdGrp *vshCmdGrpSearch(const char *grpname);
 249 bool vshCmdGrpHelp(vshControl *ctl, const vshCmdGrp *grp);
 250
 251 int vshCommandOptInt(vshControl *ctl, const vshCmd *cmd,
 252                      const char *name, int *value)
 253     ATTRIBUTE_NONNULL(4) G_GNUC_WARN_UNUSED_RESULT;
 254 int vshCommandOptUInt(vshControl *ctl, const vshCmd *cmd,
 255                       const char *name, unsigned int *value)
 256     ATTRIBUTE_NONNULL(4) G_GNUC_WARN_UNUSED_RESULT;
 257 int vshCommandOptUIntWrap(vshControl *ctl, const vshCmd *cmd,
 258                           const char *name, unsigned int *value)
 259     ATTRIBUTE_NONNULL(4) G_GNUC_WARN_UNUSED_RESULT;
 260 int vshCommandOptUL(vshControl *ctl, const vshCmd *cmd,
 261                     const char *name, unsigned long *value)
 262     ATTRIBUTE_NONNULL(4) G_GNUC_WARN_UNUSED_RESULT;
 263 int vshCommandOptULWrap(vshControl *ctl, const vshCmd *cmd,
 264                         const char *name, unsigned long *value)
 265     ATTRIBUTE_NONNULL(4) G_GNUC_WARN_UNUSED_RESULT;
 266 int vshCommandOptStringQuiet(vshControl *ctl, const vshCmd *cmd,
 267                              const char *name, const char **value)
 268     ATTRIBUTE_NONNULL(4) G_GNUC_WARN_UNUSED_RESULT;
 269 int vshCommandOptString(vshControl *ctl, const vshCmd *cmd,
 270                         const char *name, const char **value)
 271     ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(2) ATTRIBUTE_NONNULL(3)
 272     ATTRIBUTE_NONNULL(4) G_GNUC_WARN_UNUSED_RESULT;
 273 int vshCommandOptLongLong(vshControl *ctl, const vshCmd *cmd,
 274                           const char *name, long long *value)
 275     ATTRIBUTE_NONNULL(4) G_GNUC_WARN_UNUSED_RESULT;
 276 int vshCommandOptULongLong(vshControl *ctl, const vshCmd *cmd,
 277                            const char *name, unsigned long long *value)
 278     ATTRIBUTE_NONNULL(4) G_GNUC_WARN_UNUSED_RESULT;
 279 int vshCommandOptULongLongWrap(vshControl *ctl, const vshCmd *cmd,
 280                                const char *name, unsigned long long *value)
 281     ATTRIBUTE_NONNULL(4) G_GNUC_WARN_UNUSED_RESULT;
 282 int vshCommandOptScaledInt(vshControl *ctl, const vshCmd *cmd,
 283                            const char *name, unsigned long long *value,
 284                            int scale, unsigned long long max)
 285     ATTRIBUTE_NONNULL(4) G_GNUC_WARN_UNUSED_RESULT;
 286 int vshBlockJobOptionBandwidth(vshControl *ctl,
 287                                const vshCmd *cmd,
 288                                bool bytes,
 289                                unsigned long *bandwidth);
 290 bool vshCommandOptBool(const vshCmd *cmd, const char *name);
 291 bool vshCommandRun(vshControl *ctl, const vshCmd *cmd);
 292 bool vshCommandStringParse(vshControl *ctl, char *cmdstr,
 293                            vshCmd **partial);
 294
 295 const char **
 296 vshCommandOptArgv(const vshCmd *cmd,
 297                   const char *name);
 298 const char *
 299 vshCommandOptArgvString(const vshCmd *cmd,
 300                         const char *name);
 301 bool vshCommandArgvParse(vshControl *ctl, int nargs, char **argv);
 302 int vshCommandOptTimeoutToMs(vshControl *ctl, const vshCmd *cmd, int *timeout);
 303
 304 void vshPrintVa(vshControl *ctl,
 305                 const char *format,
 306                 va_list ap)
 307     G_GNUC_PRINTF(2, 0);
 308 void vshPrint(vshControl *ctl, const char *format, ...)
 309     G_GNUC_PRINTF(2, 3);
 310 void vshPrintExtra(vshControl *ctl, const char *format, ...)
 311     G_GNUC_PRINTF(2, 3);
 312 bool vshInit(vshControl *ctl, const vshCmdGrp *groups);
 313 bool vshInitReload(vshControl *ctl);
 314 void vshDeinit(vshControl *ctl);
 315 void vshDebug(vshControl *ctl, int level, const char *format, ...)
 316     G_GNUC_PRINTF(3, 4);
 317
 318 /* User visible sort, so we want locale-specific case comparison.  */
 319 #define vshStrcasecmp(S1, S2) strcasecmp(S1, S2)
 320 int vshNameSorter(const void *a, const void *b);
 321
 322 char *vshGetTypedParamValue(vshControl *ctl, virTypedParameterPtr item)
 323     ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(2);
 324
 325 double vshPrettyCapacity(unsigned long long val, const char **unit);
 326 int vshStringToArray(const char *str, char ***array);
 327
 328 /* Given an index, return either the name of that device (non-NULL) or
 329  * of its parent (NULL if a root).  */
 330 typedef const char * (*vshTreeLookup)(int devid, bool parent, void *opaque);
 331 int vshTreePrint(vshControl *ctl, vshTreeLookup lookup, void *opaque,
 332                  int num_devices, int devid);
 333
 334 /* error handling */
 335 extern virErrorPtr last_error;
 336 void vshErrorHandler(void *opaque, virErrorPtr error);
 337 void vshReportError(vshControl *ctl);
 338 void vshResetLibvirtError(void);
 339 void vshSaveLibvirtError(void);
 340 void vshSaveLibvirtHelperError(void);
 341
 342 /* file handling */
 343 void vshEditUnlinkTempfile(char *file);
 344 typedef char vshTempFile;
 345 G_DEFINE_AUTOPTR_CLEANUP_FUNC(vshTempFile, vshEditUnlinkTempfile);
 346 char *vshEditWriteToTempFile(vshControl *ctl, const char *doc);
 347 int vshEditFile(vshControl *ctl, const char *filename);
 348 char *vshEditReadBackFile(vshControl *ctl, const char *filename);
 349 int vshEditString(vshControl *ctl, char **output, const char *string);
 350 int vshAskReedit(vshControl *ctl, const char *msg, bool relax_avail);
 351
 352 /* terminal modifications */
 353 bool vshTTYIsInterruptCharacter(vshControl *ctl, const char chr);
 354 int vshTTYDisableInterrupt(vshControl *ctl);
 355 int vshTTYRestore(vshControl *ctl);
 356 int vshTTYMakeRaw(vshControl *ctl, bool report_errors);
 357 bool vshTTYAvailable(vshControl *ctl);
 358
 359 /* waiting for events */
 360 enum {
 361     VSH_EVENT_INTERRUPT,
 362     VSH_EVENT_TIMEOUT,
 363     VSH_EVENT_DONE,
 364 };
 365 void vshEventCleanup(vshControl *ctl);
 366 void vshEventDone(vshControl *ctl);
 367 void vshEventLoop(void *opaque);
 368 int vshEventStart(vshControl *ctl, int timeout_ms);
 369 void vshEventTimeout(int timer, void *opaque);
 370 int vshEventWait(vshControl *ctl);
 371
 372 /* generic commands */
 373 extern const vshCmdOptDef opts_help[];
 374 extern const vshCmdInfo info_help;
 375 extern const vshCmdOptDef opts_cd[];
 376 extern const vshCmdInfo info_cd;
 377 extern const vshCmdOptDef opts_echo[];
 378 extern const vshCmdInfo info_echo;
 379 extern const vshCmdInfo info_pwd;
 380 extern const vshCmdInfo info_quit;
 381 extern const vshCmdOptDef opts_selftest[];
 382 extern const vshCmdInfo info_selftest;
 383 extern const vshCmdOptDef opts_complete[];
 384 extern const vshCmdInfo info_complete;
 385
 386 bool cmdHelp(vshControl *ctl, const vshCmd *cmd);
 387 bool cmdCd(vshControl *ctl, const vshCmd *cmd);
 388 bool cmdEcho(vshControl *ctl, const vshCmd *cmd);
 389 bool cmdPwd(vshControl *ctl, const vshCmd *cmd);
 390 bool cmdQuit(vshControl *ctl, const vshCmd *cmd);
 391 bool cmdSelfTest(vshControl *ctl, const vshCmd *cmd);
 392 bool cmdComplete(vshControl *ctl, const vshCmd *cmd);
 393
 394 #define VSH_CMD_CD \
 395     { \
 396         .name = "cd", \
 397         .handler = cmdCd, \
 398         .opts = opts_cd, \
 399         .info = &info_cd, \
 400         .flags = VSH_CMD_FLAG_NOCONNECT \
 401     }
 402
 403 #define VSH_CMD_ECHO \
 404     { \
 405         .name = "echo", \
 406         .handler = cmdEcho, \
 407         .opts = opts_echo, \
 408         .info = &info_echo, \
 409         .flags = VSH_CMD_FLAG_NOCONNECT \
 410     }
 411
 412 #define VSH_CMD_EXIT \
 413     { \
 414         .name = "exit", \
 415         .handler = cmdQuit, \
 416         .opts = NULL, \
 417         .info = &info_quit, \
 418         .flags = VSH_CMD_FLAG_NOCONNECT \
 419     }
 420
 421 #define VSH_CMD_HELP \
 422     { \
 423         .name = "help", \
 424         .handler = cmdHelp, \
 425         .opts = opts_help, \
 426         .info = &info_help, \
 427         .flags = VSH_CMD_FLAG_NOCONNECT \
 428     }
 429
 430 #define VSH_CMD_PWD \
 431     { \
 432         .name = "pwd", \
 433         .handler = cmdPwd, \
 434         .opts = NULL, \
 435         .info = &info_pwd, \
 436         .flags = VSH_CMD_FLAG_NOCONNECT \
 437     }
 438
 439 #define VSH_CMD_QUIT \
 440     { \
 441         .name = "quit", \
 442         .handler = cmdQuit, \
 443         .opts = NULL, \
 444         .info = &info_quit, \
 445         .flags = VSH_CMD_FLAG_NOCONNECT \
 446     }
 447
 448 #define VSH_CMD_SELF_TEST \
 449     { \
 450         .name = "self-test", \
 451         .handler = cmdSelfTest, \
 452         .opts = opts_selftest, \
 453         .info = &info_selftest, \
 454         .flags = VSH_CMD_FLAG_NOCONNECT | VSH_CMD_FLAG_HIDDEN, \
 455     }
 456
 457 #define VSH_CMD_COMPLETE \
 458     { \
 459         .name = "complete", \
 460         .handler = cmdComplete, \
 461         .opts = opts_complete, \
 462         .info = &info_complete, \
 463         .flags = VSH_CMD_FLAG_NOCONNECT | VSH_CMD_FLAG_HIDDEN, \
 464     }
 465
 466
 467
 468 /* readline */
 469 char * vshReadline(vshControl *ctl, const char *prompt);
 470
 471 void vshReadlineHistoryAdd(const char *cmd);
 472
 473 /* Macros to help dealing with mutually exclusive options. */
 474
 475 /* VSH_EXCLUSIVE_OPTIONS_EXPR:
 476  *
 477  * @NAME1: String containing the name of the option.
 478  * @EXPR1: Expression to validate the variable (boolean variable)
 479  * @NAME2: String containing the name of the option.
 480  * @EXPR2: Expression to validate the variable (boolean variable)
 481  *
 482  * Reject mutually exclusive command options in virsh. Use the
 483  * provided expression to check the variables.
 484  *
 485  * This helper does an early return and therefore it has to be called
 486  * before anything that would require cleanup.
 487  */
 488 #define VSH_EXCLUSIVE_OPTIONS_EXPR(NAME1, EXPR1, NAME2, EXPR2) \
 489     if ((EXPR1) && (EXPR2)) { \
 490         vshError(ctl, _("Options --%1$s and --%2$s are mutually exclusive"), \
 491                  NAME1, NAME2); \
 492         return false; \
 493     }
 494
 495 /* VSH_EXCLUSIVE_OPTIONS:
 496  *
 497  * @NAME1: String containing the name of the option.
 498  * @NAME2: String containing the name of the option.
 499  *
 500  * Reject mutually exclusive command options in virsh. Use the
 501  * vshCommandOptBool call to request them.
 502  *
 503  * This helper does an early return and therefore it has to be called
 504  * before anything that would require cleanup.
 505  */
 506 #define VSH_EXCLUSIVE_OPTIONS(NAME1, NAME2) \
 507     VSH_EXCLUSIVE_OPTIONS_EXPR(NAME1, vshCommandOptBool(cmd, NAME1), \
 508                                NAME2, vshCommandOptBool(cmd, NAME2))
 509
 510 /* VSH_EXCLUSIVE_OPTIONS_VAR:
 511  *
 512  * @VARNAME1: Boolean variable containing the value of the option of same name
 513  * @VARNAME2: Boolean variable containing the value of the option of same name
 514  *
 515  * Reject mutually exclusive command options in virsh. Check in variables that
 516  * contain the value and have same name as the option.
 517  *
 518  * This helper does an early return and therefore it has to be called
 519  * before anything that would require cleanup.
 520  */
 521 #define VSH_EXCLUSIVE_OPTIONS_VAR(VARNAME1, VARNAME2) \
 522     VSH_EXCLUSIVE_OPTIONS_EXPR(#VARNAME1, VARNAME1, #VARNAME2, VARNAME2)
 523
 524 /* Macros to help dealing with alternative mutually exclusive options. */
 525
 526 /* VSH_ALTERNATIVE_OPTIONS_EXPR:
 527  *
 528  * @NAME1: String containing the name of the option.
 529  * @EXPR1: Expression to validate the variable (must evaluate to bool).
 530  * @NAME2: String containing the name of the option.
 531  * @EXPR2: Expression to validate the variable (must evaluate to bool).
 532  *
 533  * Require exactly one of the command options in virsh. Use the provided
 534  * expression to check the variables.
 535  *
 536  * This helper does an early return and therefore it has to be called
 537  * before anything that would require cleanup.
 538  */
 539 #define VSH_ALTERNATIVE_OPTIONS_EXPR(NAME1, EXPR1, NAME2, EXPR2) \
 540     do { \
 541         bool _expr1 = EXPR1; \
 542         bool _expr2 = EXPR2; \
 543         VSH_EXCLUSIVE_OPTIONS_EXPR(NAME1, _expr1, NAME2, _expr2); \
 544         if (!_expr1 && !_expr2) { \
 545            vshError(ctl, _("Either --%1$s or --%2$s must be provided"), \
 546                     NAME1, NAME2); \
 547            return false; \
 548         } \
 549     } while (0)
 550
 551 #define VSH_ALTERNATIVE_OPTIONS(NAME1, NAME2) \
 552     VSH_ALTERNATIVE_OPTIONS_EXPR(NAME1, vshCommandOptBool(cmd, NAME1), \
 553                                  NAME2, vshCommandOptBool(cmd, NAME2))
 554
 555 /* Macros to help dealing with required options. */
 556
 557 /* VSH_REQUIRE_OPTION_EXPR:
 558  *
 559  * @NAME1: String containing the name of the option.
 560  * @EXPR1: Expression to validate the variable (boolean variable).
 561  * @NAME2: String containing the name of required option.
 562  * @EXPR2: Expression to validate the variable (boolean variable).
 563  *
 564  * Check if required command options in virsh was set.  Use the
 565  * provided expression to check the variables.
 566  *
 567  * This helper does an early return and therefore it has to be called
 568  * before anything that would require cleanup.
 569  */
 570 #define VSH_REQUIRE_OPTION_EXPR(NAME1, EXPR1, NAME2, EXPR2) \
 571     do { \
 572         if ((EXPR1) && !(EXPR2)) { \
 573             vshError(ctl, _("Option --%1$s is required by option --%2$s"), \
 574                      NAME2, NAME1); \
 575             return false; \
 576         } \
 577     } while (0)
 578
 579 /* VSH_REQUIRE_OPTION:
 580  *
 581  * @NAME1: String containing the name of the option.
 582  * @NAME2: String containing the name of required option.
 583  *
 584  * Check if required command options in virsh was set.  Use the
 585  * vshCommandOptBool call to request them.
 586  *
 587  * This helper does an early return and therefore it has to be called
 588  * before anything that would require cleanup.
 589  */
 590 #define VSH_REQUIRE_OPTION(NAME1, NAME2) \
 591     VSH_REQUIRE_OPTION_EXPR(NAME1, vshCommandOptBool(cmd, NAME1), \
 592                             NAME2, vshCommandOptBool(cmd, NAME2))
 593
 594 /* VSH_REQUIRE_OPTION_VAR:
 595  *
 596  * @VARNAME1: Boolean variable containing the value of the option of same name.
 597  * @VARNAME2: Boolean variable containing the value of required option of
 598  *            same name.
 599  *
 600  * Check if required command options in virsh was set.  Check in variables
 601  * that contain the value and have same name as the option.
 602  *
 603  * This helper does an early return and therefore it has to be called
 604  * before anything that would require cleanup.
 605  */
 606 #define VSH_REQUIRE_OPTION_VAR(VARNAME1, VARNAME2) \
 607     VSH_REQUIRE_OPTION_EXPR(#VARNAME1, VARNAME1, #VARNAME2, VARNAME2)