virsh.h 15.3 KB
Newer Older
E
Eric Blake 已提交
1 2 3
/*
 * virsh.h: a shell to exercise the libvirt API
 *
4
 * Copyright (C) 2005, 2007-2013 Red Hat, Inc.
E
Eric Blake 已提交
5 6 7 8 9 10 11 12 13 14 15 16
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
17
 * License along with this library.  If not, see
E
Eric Blake 已提交
18 19 20 21 22 23 24 25
 * <http://www.gnu.org/licenses/>.
 *
 * Daniel Veillard <veillard@redhat.com>
 * Karel Zak <kzak@redhat.com>
 * Daniel P. Berrange <berrange@redhat.com>
 */

#ifndef VIRSH_H
26
# define VIRSH_H
E
Eric Blake 已提交
27 28 29 30 31 32 33 34 35 36

# include <stdio.h>
# include <stdlib.h>
# include <string.h>
# include <stdarg.h>
# include <unistd.h>
# include <sys/stat.h>
# include <inttypes.h>

# include "internal.h"
37
# include "virerror.h"
38
# include "virthread.h"
E
Eric Blake 已提交
39
# include "virnetdevbandwidth.h"
40
# include "virstring.h"
E
Eric Blake 已提交
41

E
Eric Blake 已提交
42
# define VSH_MAX_XML_FILE (10*1024*1024)
E
Eric Blake 已提交
43 44 45 46 47 48 49 50

# define VSH_PROMPT_RW    "virsh # "
# define VSH_PROMPT_RO    "virsh > "

# define VIR_FROM_THIS VIR_FROM_NONE

# define GETTIMEOFDAY(T) gettimeofday(T, NULL)

51 52
# define VSH_MATCH(FLAG) (flags & (FLAG))

E
Eric Blake 已提交
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
/**
 * The log configuration
 */
# define MSG_BUFFER    4096
# define SIGN_NAME     "virsh"
# define DIR_MODE      (S_IWUSR | S_IRUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH)  /* 0755 */
# define FILE_MODE     (S_IWUSR | S_IRUSR | S_IRGRP | S_IROTH)                                /* 0644 */
# define LOCK_MODE     (S_IWUSR | S_IRUSR)                                                    /* 0600 */
# define LVL_DEBUG     "DEBUG"
# define LVL_INFO      "INFO"
# define LVL_NOTICE    "NOTICE"
# define LVL_WARNING   "WARNING"
# define LVL_ERROR     "ERROR"

/**
 * vshErrorLevel:
 *
 * Indicates the level of a log message
 */
typedef enum {
    VSH_ERR_DEBUG = 0,
    VSH_ERR_INFO,
    VSH_ERR_NOTICE,
    VSH_ERR_WARNING,
    VSH_ERR_ERROR
} vshErrorLevel;

# define VSH_DEBUG_DEFAULT VSH_ERR_ERROR

/*
 * virsh command line grammar:
 *
 *    command_line    =     <command>\n | <command>; <command>; ...
 *
 *    command         =    <keyword> <option> [--] <data>
 *
 *    option          =     <bool_option> | <int_option> | <string_option>
 *    data            =     <string>
 *
 *    bool_option     =     --optionname
 *    int_option      =     --optionname <number> | --optionname=<number>
 *    string_option   =     --optionname <string> | --optionname=<string>
 *
 *    keyword         =     [a-zA-Z][a-zA-Z-]*
 *    number          =     [0-9]+
 *    string          =     ('[^']*'|"([^\\"]|\\.)*"|([^ \t\n\\'"]|\\.))+
 *
 */

/*
 * vshCmdOptType - command option type
 */
typedef enum {
    VSH_OT_BOOL,     /* optional boolean option */
    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_ALIAS,    /* alternate spelling for a later argument */
} vshCmdOptType;

/*
 * Command group types
 */
# define VSH_CMD_GRP_DOM_MANAGEMENT   "Domain Management"
# define VSH_CMD_GRP_DOM_MONITORING   "Domain Monitoring"
# define VSH_CMD_GRP_STORAGE_POOL     "Storage Pool"
# define VSH_CMD_GRP_STORAGE_VOL      "Storage Volume"
# define VSH_CMD_GRP_NETWORK          "Networking"
# define VSH_CMD_GRP_NODEDEV          "Node Device"
# define VSH_CMD_GRP_IFACE            "Interface"
# define VSH_CMD_GRP_NWFILTER         "Network Filter"
# define VSH_CMD_GRP_SECRET           "Secret"
# define VSH_CMD_GRP_SNAPSHOT         "Snapshot"
# define VSH_CMD_GRP_HOST_AND_HV      "Host and Hypervisor"
# define VSH_CMD_GRP_VIRSH            "Virsh itself"

/*
 * Command Option Flags
 */
enum {
    VSH_OFLAG_NONE     = 0,        /* without flags */
    VSH_OFLAG_REQ      = (1 << 0), /* option required */
    VSH_OFLAG_EMPTY_OK = (1 << 1), /* empty string option allowed */
    VSH_OFLAG_REQ_OPT  = (1 << 2), /* --optionname required */
};

E
Eric Blake 已提交
140 141 142 143 144 145 146 147 148
/* forward declarations */
typedef struct _vshCmd vshCmd;
typedef struct _vshCmdDef vshCmdDef;
typedef struct _vshCmdGrp vshCmdGrp;
typedef struct _vshCmdInfo vshCmdInfo;
typedef struct _vshCmdOpt vshCmdOpt;
typedef struct _vshCmdOptDef vshCmdOptDef;
typedef struct _vshControl vshControl;
typedef struct _vshCtrlData vshCtrlData;
E
Eric Blake 已提交
149 150 151 152 153 154 155 156

/*
 * vshCmdInfo -- name/value pair for information about command
 *
 * Commands should have at least the following names:
 * "name" - command name
 * "desc" - description of command, or empty string
 */
E
Eric Blake 已提交
157
struct _vshCmdInfo {
E
Eric Blake 已提交
158 159
    const char *name;           /* name of information, or NULL for list end */
    const char *data;           /* non-NULL information */
E
Eric Blake 已提交
160
};
E
Eric Blake 已提交
161 162 163 164

/*
 * vshCmdOptDef - command option definition
 */
E
Eric Blake 已提交
165
struct _vshCmdOptDef {
E
Eric Blake 已提交
166 167 168 169 170
    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; or for VSH_OT_ALIAS
                                 * the name of a later public option */
E
Eric Blake 已提交
171
};
E
Eric Blake 已提交
172 173 174 175 176 177 178

/*
 * vshCmdOpt - command options
 *
 * After parsing a command, all arguments to the command have been
 * collected into a list of these objects.
 */
E
Eric Blake 已提交
179
struct _vshCmdOpt {
E
Eric Blake 已提交
180 181
    const vshCmdOptDef *def;    /* non-NULL pointer to option definition */
    char *data;                 /* allocated data, or NULL for bool option */
E
Eric Blake 已提交
182 183
    vshCmdOpt *next;
};
E
Eric Blake 已提交
184 185 186 187 188 189 190 191 192 193 194 195

/*
 * Command Usage Flags
 */
enum {
    VSH_CMD_FLAG_NOCONNECT = (1 << 0),  /* no prior connection needed */
    VSH_CMD_FLAG_ALIAS     = (1 << 1),  /* command is an alias */
};

/*
 * vshCmdDef - command definition
 */
E
Eric Blake 已提交
196
struct _vshCmdDef {
E
Eric Blake 已提交
197 198 199 200 201
    const char *name;           /* name of command, or NULL for list end */
    bool (*handler) (vshControl *, const vshCmd *);    /* command handler */
    const vshCmdOptDef *opts;   /* definition of command options */
    const vshCmdInfo *info;     /* details about command */
    unsigned int flags;         /* bitwise OR of VSH_CMD_FLAG */
E
Eric Blake 已提交
202
};
E
Eric Blake 已提交
203 204 205 206

/*
 * vshCmd - parsed command
 */
E
Eric Blake 已提交
207
struct _vshCmd {
E
Eric Blake 已提交
208 209
    const vshCmdDef *def;       /* command definition */
    vshCmdOpt *opts;            /* list of command arguments */
E
Eric Blake 已提交
210 211
    vshCmd *next;      /* next command */
};
E
Eric Blake 已提交
212 213 214 215

/*
 * vshControl
 */
E
Eric Blake 已提交
216
struct _vshControl {
E
Eric Blake 已提交
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242
    char *name;                 /* connection name */
    virConnectPtr conn;         /* connection to hypervisor (MAY BE NULL) */
    vshCmd *cmd;                /* the current command */
    char *cmdstr;               /* string with command */
    bool imode;                 /* interactive mode? */
    bool quiet;                 /* quiet mode */
    int debug;                  /* print debug messages? */
    bool timing;                /* print timing info? */
    bool readonly;              /* connect readonly (first time only, not
                                 * during explicit connect command)
                                 */
    char *logfile;              /* log file name */
    int log_fd;                 /* log file descriptor */
    char *historydir;           /* readline history directory name */
    char *historyfile;          /* readline history file name */
    bool useGetInfo;            /* must use virDomainGetInfo, since
                                   virDomainGetState is not supported */
    bool useSnapshotOld;        /* cannot use virDomainSnapshotGetParent or
                                   virDomainSnapshotNumChildren */
    virThread eventLoop;
    virMutex lock;
    bool eventLoopStarted;
    bool quit;

    const char *escapeChar;     /* String representation of
                                   console escape character */
E
Eric Blake 已提交
243
};
E
Eric Blake 已提交
244

E
Eric Blake 已提交
245
struct _vshCmdGrp {
E
Eric Blake 已提交
246 247 248
    const char *name;    /* name of group, or NULL for list end */
    const char *keyword; /* help keyword */
    const vshCmdDef *commands;
E
Eric Blake 已提交
249
};
E
Eric Blake 已提交
250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275

void vshError(vshControl *ctl, const char *format, ...)
    ATTRIBUTE_FMT_PRINTF(2, 3);
void vshOpenLogFile(vshControl *ctl);
void vshOutputLogFile(vshControl *ctl, int log_level, const char *format,
                      va_list ap)
    ATTRIBUTE_FMT_PRINTF(3, 0);
void vshCloseLogFile(vshControl *ctl);

const char *vshCmddefGetInfo(const vshCmdDef *cmd, const char *info);
const vshCmdDef *vshCmddefSearch(const char *cmdname);
bool vshCmddefHelp(vshControl *ctl, const char *name);
const vshCmdGrp *vshCmdGrpSearch(const char *grpname);
bool vshCmdGrpHelp(vshControl *ctl, const char *name);

int vshCommandOptInt(const vshCmd *cmd, const char *name, int *value)
    ATTRIBUTE_NONNULL(3) ATTRIBUTE_RETURN_CHECK;
int vshCommandOptUInt(const vshCmd *cmd, const char *name,
                      unsigned int *value)
    ATTRIBUTE_NONNULL(3) ATTRIBUTE_RETURN_CHECK;
int vshCommandOptUL(const vshCmd *cmd, const char *name,
                    unsigned long *value)
    ATTRIBUTE_NONNULL(3) ATTRIBUTE_RETURN_CHECK;
int vshCommandOptString(const vshCmd *cmd, const char *name,
                        const char **value)
    ATTRIBUTE_NONNULL(3) ATTRIBUTE_RETURN_CHECK;
276 277 278 279
int vshCommandOptStringReq(vshControl *ctl, const vshCmd *cmd,
                           const char *name, const char **value)
    ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(2) ATTRIBUTE_NONNULL(3)
    ATTRIBUTE_NONNULL(4) ATTRIBUTE_RETURN_CHECK;
E
Eric Blake 已提交
280 281 282 283 284 285 286 287 288 289 290 291 292
int vshCommandOptLongLong(const vshCmd *cmd, const char *name,
                          long long *value)
    ATTRIBUTE_NONNULL(3) ATTRIBUTE_RETURN_CHECK;
int vshCommandOptULongLong(const vshCmd *cmd, const char *name,
                           unsigned long long *value)
    ATTRIBUTE_NONNULL(3) ATTRIBUTE_RETURN_CHECK;
int vshCommandOptScaledInt(const vshCmd *cmd, const char *name,
                           unsigned long long *value, int scale,
                           unsigned long long max)
    ATTRIBUTE_NONNULL(3) ATTRIBUTE_RETURN_CHECK;
bool vshCommandOptBool(const vshCmd *cmd, const char *name);
const vshCmdOpt *vshCommandOptArgv(const vshCmd *cmd,
                                   const vshCmdOpt *opt);
293
bool vshCmdHasOption(vshControl *ctl, const vshCmd *cmd, const char *optname);
E
Eric Blake 已提交
294

295 296 297 298 299 300 301
/* Filter flags for various vshCommandOpt*By() functions */
typedef enum {
    VSH_BYID   = (1 << 1),
    VSH_BYUUID = (1 << 2),
    VSH_BYNAME = (1 << 3),
    VSH_BYMAC  = (1 << 4),
} vshLookupByFlags;
E
Eric Blake 已提交
302

E
Eric Blake 已提交
303 304 305 306 307 308
/* Given an index, return either the name of that device (non-NULL) or
 * of its parent (NULL if a root).  */
typedef const char * (*vshTreeLookup)(int devid, bool parent, void *opaque);
int vshTreePrint(vshControl *ctl, vshTreeLookup lookup, void *opaque,
                 int num_devices, int devid);

E
Eric Blake 已提交
309 310 311 312 313 314 315 316 317 318
void vshPrintExtra(vshControl *ctl, const char *format, ...)
    ATTRIBUTE_FMT_PRINTF(2, 3);
void vshDebug(vshControl *ctl, int level, const char *format, ...)
    ATTRIBUTE_FMT_PRINTF(3, 4);

/* XXX: add batch support */
# define vshPrint(_ctl, ...)   vshPrintExtra(NULL, __VA_ARGS__)

/* User visible sort, so we want locale-specific case comparison.  */
# define vshStrcasecmp(S1, S2) strcasecmp(S1, S2)
319
int vshNameSorter(const void *a, const void *b);
E
Eric Blake 已提交
320 321 322 323 324 325 326 327

int vshDomainState(vshControl *ctl, virDomainPtr dom, int *reason);
virTypedParameterPtr vshFindTypedParamByName(const char *name,
                                             virTypedParameterPtr list,
                                             int count);
char *vshGetTypedParamValue(vshControl *ctl, virTypedParameterPtr item)
    ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(2);

E
Eric Blake 已提交
328 329 330
char *vshEditWriteToTempFile(vshControl *ctl, const char *doc);
int vshEditFile(vshControl *ctl, const char *filename);
char *vshEditReadBackFile(vshControl *ctl, const char *filename);
E
Eric Blake 已提交
331 332 333
int vshAskReedit(vshControl *ctl, const char *msg);
int vshStreamSink(virStreamPtr st, const char *bytes, size_t nbytes,
                  void *opaque);
E
Eric Blake 已提交
334
double vshPrettyCapacity(unsigned long long val, const char **unit);
335
int vshStringToArray(const char *str, char ***array);
E
Eric Blake 已提交
336 337 338 339 340

/* Typedefs, function prototypes for job progress reporting.
 * There are used by some long lingering commands like
 * migrate, dump, save, managedsave.
 */
E
Eric Blake 已提交
341
struct _vshCtrlData {
E
Eric Blake 已提交
342 343 344
    vshControl *ctl;
    const vshCmd *cmd;
    int writefd;
E
Eric Blake 已提交
345
};
E
Eric Blake 已提交
346

E
Eric Blake 已提交
347 348
/* error handling */
extern virErrorPtr last_error;
E
Eric Blake 已提交
349
void vshReportError(vshControl *ctl);
E
Eric Blake 已提交
350
void vshResetLibvirtError(void);
351
void vshSaveLibvirtError(void);
E
Eric Blake 已提交
352 353

/* allocation wrappers */
E
Eric Blake 已提交
354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375
void *_vshMalloc(vshControl *ctl, size_t sz, const char *filename, int line);
# define vshMalloc(_ctl, _sz)    _vshMalloc(_ctl, _sz, __FILE__, __LINE__)

void *_vshCalloc(vshControl *ctl, size_t nmemb, size_t sz,
                 const char *filename, int line);
# define vshCalloc(_ctl, _nmemb, _sz) \
    _vshCalloc(_ctl, _nmemb, _sz, __FILE__, __LINE__)

char *_vshStrdup(vshControl *ctl, const char *s, const char *filename,
                 int line);
# define vshStrdup(_ctl, _s)    _vshStrdup(_ctl, _s, __FILE__, __LINE__)

/* Poison the raw allocating identifiers in favor of our vsh variants.  */
# undef malloc
# undef calloc
# undef realloc
# undef strdup
# define malloc use_vshMalloc_instead_of_malloc
# define calloc use_vshCalloc_instead_of_calloc
# define realloc use_vshRealloc_instead_of_realloc
# define strdup use_vshStrdup_instead_of_strdup

376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426
/* Macros to help dealing with mutually exclusive options. */

/* VSH_EXCLUSIVE_OPTIONS_EXPR:
 *
 * @NAME1: String containing the name of the option.
 * @EXPR1: Expression to validate the variable (boolean variable)
 * @NAME2: String containing the name of the option.
 * @EXPR2: Expression to validate the variable (boolean variable)
 *
 * Reject mutually exclusive command options in virsh. Use the
 * provided expression to check the variables.
 *
 * This helper does an early return and therefore it has to be called
 * before anything that would require cleanup.
 */
# define VSH_EXCLUSIVE_OPTIONS_EXPR(NAME1, EXPR1, NAME2, EXPR2)             \
    if ((EXPR1) && (EXPR2)) {                                               \
        vshError(ctl, _("Options --%s and --%s are mutually exclusive"),    \
                 NAME1, NAME2);                                             \
        return false;                                                       \
    }

/* VSH_EXCLUSIVE_OPTIONS:
 *
 * @NAME1: String containing the name of the option.
 * @NAME2: String containing the name of the option.
 *
 * Reject mutually exclusive command options in virsh. Use the
 * vshCommandOptBool call to request them.
 *
 * This helper does an early return and therefore it has to be called
 * before anything that would require cleanup.
 */
# define VSH_EXCLUSIVE_OPTIONS(NAME1, NAME2)                                \
    VSH_EXCLUSIVE_OPTIONS_EXPR(NAME1, vshCommandOptBool(cmd, NAME1),        \
                               NAME2, vshCommandOptBool(cmd, NAME2))

/* VSH_EXCLUSIVE_OPTIONS_VAR:
 *
 * @VARNAME1: Boolean variable containing the value of the option of same name
 * @VARNAME2: Boolean variable containing the value of the option of same name
 *
 * Reject mutually exclusive command options in virsh. Check in variables that
 * contain the value and have same name as the option.
 *
 * This helper does an early return and therefore it has to be called
 * before anything that would require cleanup.
 */
# define VSH_EXCLUSIVE_OPTIONS_VAR(VARNAME1, VARNAME2)                      \
    VSH_EXCLUSIVE_OPTIONS_EXPR(#VARNAME1, VARNAME1, #VARNAME2, VARNAME2)

E
Eric Blake 已提交
427
#endif /* VIRSH_H */