VirtualBox

source: vbox/trunk/src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp@ 67954

Last change on this file since 67954 was 67949, checked in by vboxsync, 7 years ago

VBoxManageHelp: unattended update.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 69.2 KB
Line 
1/* $Id: VBoxManageHelp.cpp 67949 2017-07-13 10:01:43Z vboxsync $ */
2/** @file
3 * VBoxManage - help and other message output.
4 */
5
6/*
7 * Copyright (C) 2006-2017 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 */
17
18
19/*********************************************************************************************************************************
20* Header Files *
21*********************************************************************************************************************************/
22#include <VBox/version.h>
23
24#include <iprt/buildconfig.h>
25#include <iprt/ctype.h>
26#include <iprt/err.h>
27#include <iprt/getopt.h>
28#include <iprt/stream.h>
29
30#include "VBoxManage.h"
31
32
33/*********************************************************************************************************************************
34* Defined Constants And Macros *
35*********************************************************************************************************************************/
36/** If the usage is the given number of length long or longer, the error is
37 * repeated so the user can actually see it. */
38#define ERROR_REPEAT_AFTER_USAGE_LENGTH 16
39
40
41/*********************************************************************************************************************************
42* Global Variables *
43*********************************************************************************************************************************/
44#ifndef VBOX_ONLY_DOCS
45enum HELP_CMD_VBOXMANAGE g_enmCurCommand = HELP_CMD_VBOXMANAGE_INVALID;
46/** The scope maskt for the current subcommand. */
47uint64_t g_fCurSubcommandScope = REFENTRYSTR_SCOPE_GLOBAL;
48/** String of spaces that can be used for indentation. */
49static const char g_szSpaces[] = " ";
50
51/**
52 * Sets the current command.
53 *
54 * This affects future calls to error and help functions.
55 *
56 * @param enmCommand The command.
57 */
58void setCurrentCommand(enum HELP_CMD_VBOXMANAGE enmCommand)
59{
60 Assert(g_enmCurCommand == HELP_CMD_VBOXMANAGE_INVALID);
61 g_enmCurCommand = enmCommand;
62 g_fCurSubcommandScope = REFENTRYSTR_SCOPE_GLOBAL;
63}
64
65
66/**
67 * Sets the current subcommand.
68 *
69 * This affects future calls to error and help functions.
70 *
71 * @param fSubcommandScope The subcommand scope.
72 */
73void setCurrentSubcommand(uint64_t fSubcommandScope)
74{
75 g_fCurSubcommandScope = fSubcommandScope;
76}
77
78
79
80/**
81 * Retruns the width for the given handle.
82 *
83 * @returns Screen width.
84 * @param pStrm The stream, g_pStdErr or g_pStdOut.
85 */
86static uint32_t getScreenWidth(PRTSTREAM pStrm)
87{
88 static uint32_t s_acch[2] = { 0, 0};
89 uint32_t iWhich = pStrm == g_pStdErr ? 1 : 0;
90 uint32_t cch = s_acch[iWhich];
91 if (cch)
92 return cch;
93
94 cch = 80; /** @todo screen width IPRT API. */
95 s_acch[iWhich] = cch;
96 return cch;
97}
98
99
100/**
101 * Prints a string table string (paragraph), performing non-breaking-space
102 * replacement and wrapping.
103 *
104 * @returns Number of lines written.
105 * @param pStrm The output stream.
106 * @param psz The string table string to print.
107 * @param cchMaxWidth The maximum output width.
108 * @param fFlags String flags that may affect formatting.
109 */
110static uint32_t printString(PRTSTREAM pStrm, const char *psz, uint32_t cchMaxWidth, uint64_t fFlags)
111{
112 uint32_t cLinesWritten;
113 size_t cch = strlen(psz);
114 const char *pszNbsp = strchr(psz, REFENTRY_NBSP);
115
116 /*
117 * No-wrap case is simpler, so handle that separately.
118 */
119 if (cch <= cchMaxWidth)
120 {
121 if (!pszNbsp)
122 RTStrmWrite(pStrm, psz, cch);
123 else
124 {
125 do
126 {
127 RTStrmWrite(pStrm, psz, pszNbsp - psz);
128 RTStrmPutCh(pStrm, ' ');
129 psz = pszNbsp + 1;
130 pszNbsp = strchr(psz, REFENTRY_NBSP);
131 } while (pszNbsp);
132 RTStrmWrite(pStrm, psz, strlen(psz));
133 }
134 RTStrmPutCh(pStrm, '\n');
135 cLinesWritten = 1;
136 }
137 /*
138 * We need to wrap stuff, too bad.
139 */
140 else
141 {
142 /* Figure the paragraph indent level first. */
143 uint32_t cchIndent = 0;
144 while (*psz == ' ')
145 cchIndent++, psz++;
146 Assert(cchIndent + 4 + 1 <= RT_ELEMENTS(g_szSpaces));
147
148 if (cchIndent + 8 >= cchMaxWidth)
149 cchMaxWidth += cchIndent + 8;
150
151 /* Work our way thru the string, line by line. */
152 uint32_t cchHangingIndent = 0;
153 cLinesWritten = 0;
154 do
155 {
156 RTStrmWrite(pStrm, g_szSpaces, cchIndent + cchHangingIndent);
157 size_t offLine = cchIndent + cchHangingIndent;
158 bool fPendingSpace = false;
159 do
160 {
161 const char *pszSpace = strchr(psz, ' ');
162 size_t cchWord = pszSpace ? pszSpace - psz : strlen(psz);
163 if ( offLine + cchWord + fPendingSpace > cchMaxWidth
164 && offLine != cchIndent)
165 break;
166
167 pszNbsp = (const char *)memchr(psz, REFENTRY_NBSP, cchWord);
168 while (pszNbsp)
169 {
170 size_t cchSubWord = pszNbsp - psz;
171 if (fPendingSpace)
172 RTStrmPutCh(pStrm, ' ');
173 RTStrmWrite(pStrm, psz, cchSubWord);
174 offLine += cchSubWord + fPendingSpace;
175 psz += cchSubWord + 1;
176 cchWord -= cchSubWord + 1;
177 pszNbsp = (const char *)memchr(psz, REFENTRY_NBSP, cchWord);
178 fPendingSpace = true;
179 }
180
181 if (fPendingSpace)
182 RTStrmPutCh(pStrm, ' ');
183 RTStrmWrite(pStrm, psz, cchWord);
184 offLine += cchWord + fPendingSpace;
185 psz = pszSpace ? pszSpace + 1 : strchr(psz, '\0');
186 fPendingSpace = true;
187 } while (offLine < cchMaxWidth && *psz != '\0');
188 RTStrmPutCh(pStrm, '\n');
189 cLinesWritten++;
190
191 /* Set up hanging indent if relevant. */
192 if (fFlags & REFENTRYSTR_FLAGS_SYNOPSIS)
193 cchHangingIndent = 4;
194 } while (*psz != '\0');
195 }
196 return cLinesWritten;
197}
198
199
200/**
201 * Checks if the given string is empty (only spaces).
202 * @returns true if empty, false if not.
203 * @param psz The string to examine.
204 */
205DECLINLINE(bool) isEmptyString(const char *psz)
206{
207 char ch;
208 while ((ch = *psz) == ' ')
209 psz++;
210 return ch == '\0';
211}
212
213
214/**
215 * Prints a string table.
216 *
217 * @returns Current number of pending blank lines.
218 * @param pStrm The output stream.
219 * @param pStrTab The string table.
220 * @param fScope The selection scope.
221 * @param cPendingBlankLines Pending blank lines from previous string table.
222 * @param pcLinesWritten Pointer to variable that should be incremented
223 * by the number of lines written. Optional.
224 */
225static uint32_t printStringTable(PRTSTREAM pStrm, PCREFENTRYSTRTAB pStrTab, uint64_t fScope, uint32_t cPendingBlankLines,
226 uint32_t *pcLinesWritten = NULL)
227{
228 uint32_t cLinesWritten = 0;
229 uint32_t cchWidth = getScreenWidth(pStrm);
230 uint64_t fPrevScope = fScope;
231 for (uint32_t i = 0; i < pStrTab->cStrings; i++)
232 {
233 uint64_t fCurScope = pStrTab->paStrings[i].fScope;
234 if ((fCurScope & REFENTRYSTR_SCOPE_MASK) == REFENTRYSTR_SCOPE_SAME)
235 {
236 fCurScope &= ~REFENTRYSTR_SCOPE_MASK;
237 fCurScope |= (fPrevScope & REFENTRYSTR_SCOPE_MASK);
238 }
239 if (fCurScope & REFENTRYSTR_SCOPE_MASK & fScope)
240 {
241 const char *psz = pStrTab->paStrings[i].psz;
242 if (psz && !isEmptyString(psz))
243 {
244 while (cPendingBlankLines > 0)
245 {
246 cPendingBlankLines--;
247 RTStrmPutCh(pStrm, '\n');
248 cLinesWritten++;
249 }
250 cLinesWritten += printString(pStrm, psz, cchWidth, fCurScope & REFENTRYSTR_FLAGS_MASK);
251 }
252 else
253 cPendingBlankLines++;
254 }
255 fPrevScope = fCurScope;
256 }
257
258 if (pcLinesWritten)
259 *pcLinesWritten += cLinesWritten;
260 return cPendingBlankLines;
261}
262
263
264/**
265 * Prints brief help for a command or subcommand.
266 *
267 * @returns Number of lines written.
268 * @param enmCommand The command.
269 * @param fSubcommandScope The subcommand scope, REFENTRYSTR_SCOPE_GLOBAL
270 * for all.
271 * @param pStrm The output stream.
272 */
273static uint32_t printBriefCommandOrSubcommandHelp(enum HELP_CMD_VBOXMANAGE enmCommand, uint64_t fSubcommandScope, PRTSTREAM pStrm)
274{
275 uint32_t cLinesWritten = 0;
276 uint32_t cPendingBlankLines = 0;
277 uint32_t cFound = 0;
278 for (uint32_t i = 0; i < g_cHelpEntries; i++)
279 {
280 PCREFENTRY pHelp = g_apHelpEntries[i];
281 if (pHelp->idInternal == (int64_t)enmCommand)
282 {
283 cFound++;
284 if (cFound == 1)
285 {
286 if (fSubcommandScope == REFENTRYSTR_SCOPE_GLOBAL)
287 RTStrmPrintf(pStrm, "Usage - %c%s:\n", RT_C_TO_UPPER(pHelp->pszBrief[0]), pHelp->pszBrief + 1);
288 else
289 RTStrmPrintf(pStrm, "Usage:\n");
290 }
291 cPendingBlankLines = printStringTable(pStrm, &pHelp->Synopsis, fSubcommandScope, cPendingBlankLines, &cLinesWritten);
292 if (!cPendingBlankLines)
293 cPendingBlankLines = 1;
294 }
295 }
296 Assert(cFound > 0);
297 return cLinesWritten;
298}
299
300
301/**
302 * Prints the brief usage information for the current (sub)command.
303 *
304 * @param pStrm The output stream.
305 */
306void printUsage(PRTSTREAM pStrm)
307{
308 printBriefCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, pStrm);
309}
310
311
312/**
313 * Prints full help for a command or subcommand.
314 *
315 * @param enmCommand The command.
316 * @param fSubcommandScope The subcommand scope, REFENTRYSTR_SCOPE_GLOBAL
317 * for all.
318 * @param pStrm The output stream.
319 */
320static void printFullCommandOrSubcommandHelp(enum HELP_CMD_VBOXMANAGE enmCommand, uint64_t fSubcommandScope, PRTSTREAM pStrm)
321{
322 uint32_t cPendingBlankLines = 0;
323 uint32_t cFound = 0;
324 for (uint32_t i = 0; i < g_cHelpEntries; i++)
325 {
326 PCREFENTRY pHelp = g_apHelpEntries[i];
327 if ( pHelp->idInternal == (int64_t)enmCommand
328 || enmCommand == HELP_CMD_VBOXMANAGE_INVALID)
329 {
330 cFound++;
331 cPendingBlankLines = printStringTable(pStrm, &pHelp->Help, fSubcommandScope, cPendingBlankLines);
332 if (cPendingBlankLines < 2)
333 cPendingBlankLines = 2;
334 }
335 }
336 Assert(cFound > 0);
337}
338
339
340/**
341 * Prints the full help for the current (sub)command.
342 *
343 * @param pStrm The output stream.
344 */
345void printHelp(PRTSTREAM pStrm)
346{
347 printFullCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, pStrm);
348}
349
350
351/**
352 * Display no subcommand error message and current command usage.
353 *
354 * @returns RTEXITCODE_SYNTAX.
355 */
356RTEXITCODE errorNoSubcommand(void)
357{
358 Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID);
359 Assert(g_fCurSubcommandScope == REFENTRYSTR_SCOPE_GLOBAL);
360
361 return errorSyntax("No subcommand specified");
362}
363
364
365/**
366 * Display unknown subcommand error message and current command usage.
367 *
368 * May show full command help instead if the subcommand is a common help option.
369 *
370 * @returns RTEXITCODE_SYNTAX, or RTEXITCODE_SUCCESS if common help option.
371 * @param pszSubcommand The name of the alleged subcommand.
372 */
373RTEXITCODE errorUnknownSubcommand(const char *pszSubcommand)
374{
375 Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID);
376 Assert(g_fCurSubcommandScope == REFENTRYSTR_SCOPE_GLOBAL);
377
378 /* check if help was requested. */
379 if ( strcmp(pszSubcommand, "--help") == 0
380 || strcmp(pszSubcommand, "-h") == 0
381 || strcmp(pszSubcommand, "-?") == 0)
382 {
383 printFullCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, g_pStdOut);
384 return RTEXITCODE_SUCCESS;
385 }
386
387 return errorSyntax("Unknown subcommand: %s", pszSubcommand);
388}
389
390
391/**
392 * Display too many parameters error message and current command usage.
393 *
394 * May show full command help instead if the subcommand is a common help option.
395 *
396 * @returns RTEXITCODE_SYNTAX, or RTEXITCODE_SUCCESS if common help option.
397 * @param papszArgs The first unwanted parameter. Terminated by
398 * NULL entry.
399 */
400RTEXITCODE errorTooManyParameters(char **papszArgs)
401{
402 Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID);
403 Assert(g_fCurSubcommandScope != REFENTRYSTR_SCOPE_GLOBAL);
404
405 /* check if help was requested. */
406 if (papszArgs)
407 {
408 for (uint32_t i = 0; papszArgs[i]; i++)
409 if ( strcmp(papszArgs[i], "--help") == 0
410 || strcmp(papszArgs[i], "-h") == 0
411 || strcmp(papszArgs[i], "-?") == 0)
412 {
413 printFullCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, g_pStdOut);
414 return RTEXITCODE_SUCCESS;
415 }
416 else if (!strcmp(papszArgs[i], "--"))
417 break;
418 }
419
420 return errorSyntax("Too many parameters");
421}
422
423
424/**
425 * Display current (sub)command usage and the custom error message.
426 *
427 * @returns RTEXITCODE_SYNTAX.
428 * @param pszFormat Custom error message format string.
429 * @param ... Format arguments.
430 */
431RTEXITCODE errorSyntax(const char *pszFormat, ...)
432{
433 Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID);
434
435 showLogo(g_pStdErr);
436
437 va_list va;
438 va_start(va, pszFormat);
439 RTMsgErrorV(pszFormat, va);
440 va_end(va);
441
442 RTStrmPutCh(g_pStdErr, '\n');
443 if ( printBriefCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, g_pStdErr)
444 >= ERROR_REPEAT_AFTER_USAGE_LENGTH)
445 {
446 /* Usage was very long, repeat the error message. */
447 RTStrmPutCh(g_pStdErr, '\n');
448 va_start(va, pszFormat);
449 RTMsgErrorV(pszFormat, va);
450 va_end(va);
451 }
452 return RTEXITCODE_SYNTAX;
453}
454
455
456/**
457 * Worker for errorGetOpt.
458 *
459 * @param rcGetOpt The RTGetOpt return value.
460 * @param pValueUnion The value union returned by RTGetOpt.
461 */
462static void errorGetOptWorker(int rcGetOpt, union RTGETOPTUNION const *pValueUnion)
463{
464 if (rcGetOpt == VINF_GETOPT_NOT_OPTION)
465 RTMsgError("Invalid parameter '%s'", pValueUnion->psz);
466 else if (rcGetOpt > 0)
467 {
468 if (RT_C_IS_PRINT(rcGetOpt))
469 RTMsgError("Invalid option -%c", rcGetOpt);
470 else
471 RTMsgError("Invalid option case %i", rcGetOpt);
472 }
473 else if (rcGetOpt == VERR_GETOPT_UNKNOWN_OPTION)
474 RTMsgError("Unknown option: %s", pValueUnion->psz);
475 else if (rcGetOpt == VERR_GETOPT_INVALID_ARGUMENT_FORMAT)
476 RTMsgError("Invalid argument format: %s", pValueUnion->psz);
477 else if (pValueUnion->pDef)
478 RTMsgError("%s: %Rrs", pValueUnion->pDef->pszLong, rcGetOpt);
479 else
480 RTMsgError("%Rrs", rcGetOpt);
481}
482
483
484/**
485 * Handled an RTGetOpt error or common option.
486 *
487 * This implements the 'V' and 'h' cases. It reports appropriate syntax errors
488 * for other @a rcGetOpt values.
489 *
490 * @retval RTEXITCODE_SUCCESS if help or version request.
491 * @retval RTEXITCODE_SYNTAX if not help or version request.
492 * @param rcGetOpt The RTGetOpt return value.
493 * @param pValueUnion The value union returned by RTGetOpt.
494 */
495RTEXITCODE errorGetOpt(int rcGetOpt, union RTGETOPTUNION const *pValueUnion)
496{
497 Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID);
498
499 /*
500 * Check if it is an unhandled standard option.
501 */
502 if (rcGetOpt == 'V')
503 {
504 RTPrintf("%sr%d\n", VBOX_VERSION_STRING, RTBldCfgRevision());
505 return RTEXITCODE_SUCCESS;
506 }
507
508 if (rcGetOpt == 'h')
509 {
510 printFullCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, g_pStdOut);
511 return RTEXITCODE_SUCCESS;
512 }
513
514 /*
515 * We failed.
516 */
517 showLogo(g_pStdErr);
518 errorGetOptWorker(rcGetOpt, pValueUnion);
519 if ( printBriefCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, g_pStdErr)
520 >= ERROR_REPEAT_AFTER_USAGE_LENGTH)
521 {
522 /* Usage was very long, repeat the error message. */
523 RTStrmPutCh(g_pStdErr, '\n');
524 errorGetOptWorker(rcGetOpt, pValueUnion);
525 }
526 return RTEXITCODE_SYNTAX;
527}
528
529#endif /* !VBOX_ONLY_DOCS */
530
531
532
533void showLogo(PRTSTREAM pStrm)
534{
535 static bool s_fShown; /* show only once */
536
537 if (!s_fShown)
538 {
539 RTStrmPrintf(pStrm, VBOX_PRODUCT " Command Line Management Interface Version "
540 VBOX_VERSION_STRING "\n"
541 "(C) 2005-" VBOX_C_YEAR " " VBOX_VENDOR "\n"
542 "All rights reserved.\n"
543 "\n");
544 s_fShown = true;
545 }
546}
547
548
549
550
551void printUsage(USAGECATEGORY fCategory, uint32_t fSubCategory, PRTSTREAM pStrm)
552{
553 bool fDumpOpts = false;
554#ifdef RT_OS_LINUX
555 bool fLinux = true;
556#else
557 bool fLinux = false;
558#endif
559#ifdef RT_OS_WINDOWS
560 bool fWin = true;
561#else
562 bool fWin = false;
563#endif
564#ifdef RT_OS_SOLARIS
565 bool fSolaris = true;
566#else
567 bool fSolaris = false;
568#endif
569#ifdef RT_OS_FREEBSD
570 bool fFreeBSD = true;
571#else
572 bool fFreeBSD = false;
573#endif
574#ifdef RT_OS_DARWIN
575 bool fDarwin = true;
576#else
577 bool fDarwin = false;
578#endif
579#ifdef VBOX_WITH_VBOXSDL
580 bool fVBoxSDL = true;
581#else
582 bool fVBoxSDL = false;
583#endif
584
585 if (fCategory == USAGE_DUMPOPTS)
586 {
587 fDumpOpts = true;
588 fLinux = true;
589 fWin = true;
590 fSolaris = true;
591 fFreeBSD = true;
592 fDarwin = true;
593 fVBoxSDL = true;
594 fCategory = USAGE_ALL;
595 }
596
597 RTStrmPrintf(pStrm,
598 "Usage:\n"
599 "\n");
600
601 if (fCategory == USAGE_ALL)
602 RTStrmPrintf(pStrm,
603 " VBoxManage [<general option>] <command>\n"
604 " \n \n"
605 "General Options:\n \n"
606 " [-v|--version] print version number and exit\n"
607 " [-q|--nologo] suppress the logo\n"
608 " [--settingspw <pw>] provide the settings password\n"
609 " [--settingspwfile <file>] provide a file containing the settings password\n"
610 " \n \n"
611 "Commands:\n \n");
612
613 const char *pcszSep1 = " ";
614 const char *pcszSep2 = " ";
615 if (fCategory != USAGE_ALL)
616 {
617 pcszSep1 = "VBoxManage";
618 pcszSep2 = "";
619 }
620
621#define SEP pcszSep1, pcszSep2
622
623 if (fCategory & USAGE_LIST)
624 RTStrmPrintf(pStrm,
625 "%s list [--long|-l] [--sorted|-s]%s vms|runningvms|ostypes|hostdvds|hostfloppies|\n"
626#if defined(VBOX_WITH_NETFLT)
627 " intnets|bridgedifs|hostonlyifs|natnets|dhcpservers|\n"
628#else
629 " intnets|bridgedifs|natnets|dhcpservers|hostinfo|\n"
630#endif
631 " hostinfo|hostcpuids|hddbackends|hdds|dvds|floppies|\n"
632 " usbhost|usbfilters|systemproperties|extpacks|\n"
633 " groups|webcams|screenshotformats\n"
634 "\n", SEP);
635
636 if (fCategory & USAGE_SHOWVMINFO)
637 RTStrmPrintf(pStrm,
638 "%s showvminfo %s <uuid|vmname> [--details]\n"
639 " [--machinereadable]\n"
640 "%s showvminfo %s <uuid|vmname> --log <idx>\n"
641 "\n", SEP, SEP);
642
643 if (fCategory & USAGE_REGISTERVM)
644 RTStrmPrintf(pStrm,
645 "%s registervm %s <filename>\n"
646 "\n", SEP);
647
648 if (fCategory & USAGE_UNREGISTERVM)
649 RTStrmPrintf(pStrm,
650 "%s unregistervm %s <uuid|vmname> [--delete]\n"
651 "\n", SEP);
652
653 if (fCategory & USAGE_CREATEVM)
654 RTStrmPrintf(pStrm,
655 "%s createvm %s --name <name>\n"
656 " [--groups <group>, ...]\n"
657 " [--ostype <ostype>]\n"
658 " [--register]\n"
659 " [--basefolder <path>]\n"
660 " [--uuid <uuid>]\n"
661 "\n", SEP);
662
663 if (fCategory & USAGE_MODIFYVM)
664 {
665 RTStrmPrintf(pStrm,
666 "%s modifyvm %s <uuid|vmname>\n"
667 " [--name <name>]\n"
668 " [--groups <group>, ...]\n"
669 " [--description <desc>]\n"
670 " [--ostype <ostype>]\n"
671 " [--iconfile <filename>]\n"
672 " [--memory <memorysize in MB>]\n"
673 " [--pagefusion on|off]\n"
674 " [--vram <vramsize in MB>]\n"
675 " [--acpi on|off]\n"
676#ifdef VBOX_WITH_PCI_PASSTHROUGH
677 " [--pciattach 03:04.0]\n"
678 " [--pciattach 03:04.0@02:01.0]\n"
679 " [--pcidetach 03:04.0]\n"
680#endif
681 " [--ioapic on|off]\n"
682 " [--hpet on|off]\n"
683 " [--triplefaultreset on|off]\n"
684 " [--apic on|off]\n"
685 " [--x2apic on|off]\n"
686 " [--paravirtprovider none|default|legacy|minimal|\n"
687 " hyperv|kvm]\n"
688 " [--paravirtdebug <key=value> [,<key=value> ...]]\n"
689 " [--hwvirtex on|off]\n"
690 " [--nestedpaging on|off]\n"
691 " [--largepages on|off]\n"
692 " [--vtxvpid on|off]\n"
693 " [--vtxux on|off]\n"
694 " [--pae on|off]\n"
695 " [--longmode on|off]\n"
696 " [--cpu-profile \"host|Intel 80[86|286|386]\"]\n"
697 " [--cpuid-portability-level <0..3>\n"
698 " [--cpuidset <leaf> <eax> <ebx> <ecx> <edx>]\n"
699 " [--cpuidremove <leaf>]\n"
700 " [--cpuidremoveall]\n"
701 " [--hardwareuuid <uuid>]\n"
702 " [--cpus <number>]\n"
703 " [--cpuhotplug on|off]\n"
704 " [--plugcpu <id>]\n"
705 " [--unplugcpu <id>]\n"
706 " [--cpuexecutioncap <1-100>]\n"
707 " [--rtcuseutc on|off]\n"
708#ifdef VBOX_WITH_VMSVGA
709 " [--graphicscontroller none|vboxvga|vmsvga]\n"
710#else
711 " [--graphicscontroller none|vboxvga]\n"
712#endif
713 " [--monitorcount <number>]\n"
714 " [--accelerate3d on|off]\n"
715#ifdef VBOX_WITH_VIDEOHWACCEL
716 " [--accelerate2dvideo on|off]\n"
717#endif
718 " [--firmware bios|efi|efi32|efi64]\n"
719 " [--chipset ich9|piix3]\n"
720 " [--bioslogofadein on|off]\n"
721 " [--bioslogofadeout on|off]\n"
722 " [--bioslogodisplaytime <msec>]\n"
723 " [--bioslogoimagepath <imagepath>]\n"
724 " [--biosbootmenu disabled|menuonly|messageandmenu]\n"
725 " [--biosapic disabled|apic|x2apic]\n"
726 " [--biossystemtimeoffset <msec>]\n"
727 " [--biospxedebug on|off]\n"
728 " [--boot<1-4> none|floppy|dvd|disk|net>]\n"
729 " [--nic<1-N> none|null|nat|bridged|intnet"
730#if defined(VBOX_WITH_NETFLT)
731 "|hostonly"
732#endif
733 "|\n"
734 " generic|natnetwork"
735 "]\n"
736 " [--nictype<1-N> Am79C970A|Am79C973"
737#ifdef VBOX_WITH_E1000
738 "|\n 82540EM|82543GC|82545EM"
739#endif
740#ifdef VBOX_WITH_VIRTIO
741 "|\n virtio"
742#endif /* VBOX_WITH_VIRTIO */
743 "]\n"
744 " [--cableconnected<1-N> on|off]\n"
745 " [--nictrace<1-N> on|off]\n"
746 " [--nictracefile<1-N> <filename>]\n"
747 " [--nicproperty<1-N> name=[value]]\n"
748 " [--nicspeed<1-N> <kbps>]\n"
749 " [--nicbootprio<1-N> <priority>]\n"
750 " [--nicpromisc<1-N> deny|allow-vms|allow-all]\n"
751 " [--nicbandwidthgroup<1-N> none|<name>]\n"
752 " [--bridgeadapter<1-N> none|<devicename>]\n"
753#if defined(VBOX_WITH_NETFLT)
754 " [--hostonlyadapter<1-N> none|<devicename>]\n"
755#endif
756 " [--intnet<1-N> <network name>]\n"
757 " [--nat-network<1-N> <network name>]\n"
758 " [--nicgenericdrv<1-N> <driver>\n"
759 " [--natnet<1-N> <network>|default]\n"
760 " [--natsettings<1-N> [<mtu>],[<socksnd>],\n"
761 " [<sockrcv>],[<tcpsnd>],\n"
762 " [<tcprcv>]]\n"
763 " [--natpf<1-N> [<rulename>],tcp|udp,[<hostip>],\n"
764 " <hostport>,[<guestip>],<guestport>]\n"
765 " [--natpf<1-N> delete <rulename>]\n"
766 " [--nattftpprefix<1-N> <prefix>]\n"
767 " [--nattftpfile<1-N> <file>]\n"
768 " [--nattftpserver<1-N> <ip>]\n"
769 " [--natbindip<1-N> <ip>\n"
770 " [--natdnspassdomain<1-N> on|off]\n"
771 " [--natdnsproxy<1-N> on|off]\n"
772 " [--natdnshostresolver<1-N> on|off]\n"
773 " [--nataliasmode<1-N> default|[log],[proxyonly],\n"
774 " [sameports]]\n"
775 " [--macaddress<1-N> auto|<mac>]\n"
776 " [--mouse ps2|usb|usbtablet|usbmultitouch]\n"
777 " [--keyboard ps2|usb\n"
778 " [--uart<1-N> off|<I/O base> <IRQ>]\n"
779 " [--uartmode<1-N> disconnected|\n"
780 " server <pipe>|\n"
781 " client <pipe>|\n"
782 " tcpserver <port>|\n"
783 " tcpclient <hostname:port>|\n"
784 " file <file>|\n"
785 " <devicename>]\n"
786#if defined(RT_OS_LINUX) || defined(RT_OS_WINDOWS)
787 " [--lpt<1-N> off|<I/O base> <IRQ>]\n"
788 " [--lptmode<1-N> <devicename>]\n"
789#endif
790 " [--guestmemoryballoon <balloonsize in MB>]\n"
791 " [--audio none|null", SEP);
792 if (fWin)
793 {
794#ifdef VBOX_WITH_WINMM
795 RTStrmPrintf(pStrm, "|winmm|dsound");
796#else
797 RTStrmPrintf(pStrm, "|dsound");
798#endif
799 }
800 if (fLinux || fSolaris)
801 {
802 RTStrmPrintf(pStrm, ""
803#ifdef VBOX_WITH_AUDIO_OSS
804 "|oss"
805#endif
806#ifdef VBOX_WITH_AUDIO_ALSA
807 "|alsa"
808#endif
809#ifdef VBOX_WITH_AUDIO_PULSE
810 "|pulse"
811#endif
812 );
813 }
814 if (fFreeBSD)
815 {
816#ifdef VBOX_WITH_AUDIO_OSS
817 /* Get the line break sorted when dumping all option variants. */
818 if (fDumpOpts)
819 {
820 RTStrmPrintf(pStrm, "|\n"
821 " oss");
822 }
823 else
824 RTStrmPrintf(pStrm, "|oss");
825#endif
826#ifdef VBOX_WITH_AUDIO_PULSE
827 RTStrmPrintf(pStrm, "|pulse");
828#endif
829 }
830 if (fDarwin)
831 {
832 RTStrmPrintf(pStrm, "|coreaudio");
833 }
834 RTStrmPrintf(pStrm, "]\n");
835 RTStrmPrintf(pStrm,
836 " [--audiocontroller ac97|hda|sb16]\n"
837 " [--audiocodec stac9700|ad1980|stac9221|sb16]\n"
838 " [--clipboard disabled|hosttoguest|guesttohost|\n"
839 " bidirectional]\n"
840 " [--draganddrop disabled|hosttoguest]\n");
841 RTStrmPrintf(pStrm,
842 " [--vrde on|off]\n"
843 " [--vrdeextpack default|<name>\n"
844 " [--vrdeproperty <name=[value]>]\n"
845 " [--vrdeport <hostport>]\n"
846 " [--vrdeaddress <hostip>]\n"
847 " [--vrdeauthtype null|external|guest]\n"
848 " [--vrdeauthlibrary default|<name>\n"
849 " [--vrdemulticon on|off]\n"
850 " [--vrdereusecon on|off]\n"
851 " [--vrdevideochannel on|off]\n"
852 " [--vrdevideochannelquality <percent>]\n");
853 RTStrmPrintf(pStrm,
854 " [--usb on|off]\n"
855 " [--usbehci on|off]\n"
856 " [--usbxhci on|off]\n"
857 " [--usbrename <oldname> <newname>]\n"
858 " [--snapshotfolder default|<path>]\n"
859 " [--teleporter on|off]\n"
860 " [--teleporterport <port>]\n"
861 " [--teleporteraddress <address|empty>\n"
862 " [--teleporterpassword <password>]\n"
863 " [--teleporterpasswordfile <file>|stdin]\n"
864 " [--tracing-enabled on|off]\n"
865 " [--tracing-config <config-string>]\n"
866 " [--tracing-allow-vm-access on|off]\n"
867#if 0
868 " [--iocache on|off]\n"
869 " [--iocachesize <I/O cache size in MB>]\n"
870#endif
871#if 0
872 " [--faulttolerance master|standby]\n"
873 " [--faulttoleranceaddress <name>]\n"
874 " [--faulttoleranceport <port>]\n"
875 " [--faulttolerancesyncinterval <msec>]\n"
876 " [--faulttolerancepassword <password>]\n"
877#endif
878#ifdef VBOX_WITH_USB_CARDREADER
879 " [--usbcardreader on|off]\n"
880#endif
881 " [--autostart-enabled on|off]\n"
882 " [--autostart-delay <seconds>]\n"
883#if 0
884 " [--autostop-type disabled|savestate|poweroff|\n"
885 " acpishutdown]\n"
886#endif
887#ifdef VBOX_WITH_VIDEOREC
888 " [--videocap on|off]\n"
889 " [--videocapscreens all|<screen ID> [<screen ID> ...]]\n"
890 " [--videocapfile <filename>]\n"
891 " [--videocapres <width> <height>]\n"
892 " [--videocaprate <rate>]\n"
893 " [--videocapfps <fps>]\n"
894 " [--videocapmaxtime <ms>]\n"
895 " [--videocapmaxsize <MB>]\n"
896 " [--videocapopts <key=value> [,<key=value> ...]]\n"
897#endif
898 " [--defaultfrontend default|<name>]\n"
899 "\n");
900 }
901
902 if (fCategory & USAGE_CLONEVM)
903 RTStrmPrintf(pStrm,
904 "%s clonevm %s <uuid|vmname>\n"
905 " [--snapshot <uuid>|<name>]\n"
906 " [--mode machine|machineandchildren|all]\n"
907 " [--options link|keepallmacs|keepnatmacs|\n"
908 " keepdisknames]\n"
909 " [--name <name>]\n"
910 " [--groups <group>, ...]\n"
911 " [--basefolder <basefolder>]\n"
912 " [--uuid <uuid>]\n"
913 " [--register]\n"
914 "\n", SEP);
915
916 if (fCategory & USAGE_IMPORTAPPLIANCE)
917 RTStrmPrintf(pStrm,
918 "%s import %s <ovfname/ovaname>\n"
919 " [--dry-run|-n]\n"
920 " [--options keepallmacs|keepnatmacs|importtovdi]\n"
921 " [more options]\n"
922 " (run with -n to have options displayed\n"
923 " for a particular OVF)\n\n", SEP);
924
925 if (fCategory & USAGE_EXPORTAPPLIANCE)
926 RTStrmPrintf(pStrm,
927 "%s export %s <machines> --output|-o <name>.<ovf/ova/tar.gz>\n"
928 " [--legacy09|--ovf09|--ovf10|--ovf20|--opc10]\n"
929 " [--manifest]\n"
930 " [--iso]\n"
931 " [--options manifest|iso|nomacs|nomacsbutnat]\n"
932 " [--vsys <number of virtual system>]\n"
933 " [--product <product name>]\n"
934 " [--producturl <product url>]\n"
935 " [--vendor <vendor name>]\n"
936 " [--vendorurl <vendor url>]\n"
937 " [--version <version info>]\n"
938 " [--description <description info>]\n"
939 " [--eula <license text>]\n"
940 " [--eulafile <filename>]\n"
941 "\n", SEP);
942
943 if (fCategory & USAGE_STARTVM)
944 {
945 RTStrmPrintf(pStrm,
946 "%s startvm %s <uuid|vmname>...\n"
947 " [--type gui", SEP);
948 if (fVBoxSDL)
949 RTStrmPrintf(pStrm, "|sdl");
950 RTStrmPrintf(pStrm, "|headless|separate]\n");
951 RTStrmPrintf(pStrm,
952 " [-E|--putenv <NAME>[=<VALUE>]]\n"
953 "\n");
954 }
955
956 if (fCategory & USAGE_CONTROLVM)
957 {
958 RTStrmPrintf(pStrm,
959 "%s controlvm %s <uuid|vmname>\n"
960 " pause|resume|reset|poweroff|savestate|\n"
961 " acpipowerbutton|acpisleepbutton|\n"
962 " keyboardputscancode <hex> [<hex> ...]|\n"
963 " keyboardputstring <string1> [<string2> ...]|\n"
964 " keyboardputfile <filename>|\n"
965 " setlinkstate<1-N> on|off |\n"
966#if defined(VBOX_WITH_NETFLT)
967 " nic<1-N> null|nat|bridged|intnet|hostonly|generic|\n"
968 " natnetwork [<devicename>] |\n"
969#else /* !VBOX_WITH_NETFLT */
970 " nic<1-N> null|nat|bridged|intnet|generic|natnetwork\n"
971 " [<devicename>] |\n"
972#endif /* !VBOX_WITH_NETFLT */
973 " nictrace<1-N> on|off |\n"
974 " nictracefile<1-N> <filename> |\n"
975 " nicproperty<1-N> name=[value] |\n"
976 " nicpromisc<1-N> deny|allow-vms|allow-all |\n"
977 " natpf<1-N> [<rulename>],tcp|udp,[<hostip>],\n"
978 " <hostport>,[<guestip>],<guestport> |\n"
979 " natpf<1-N> delete <rulename> |\n"
980 " guestmemoryballoon <balloonsize in MB> |\n"
981 " usbattach <uuid>|<address>\n"
982 " [--capturefile <filename>] |\n"
983 " usbdetach <uuid>|<address> |\n"
984 " clipboard disabled|hosttoguest|guesttohost|\n"
985 " bidirectional |\n"
986 " draganddrop disabled|hosttoguest |\n"
987 " vrde on|off |\n"
988 " vrdeport <port> |\n"
989 " vrdeproperty <name=[value]> |\n"
990 " vrdevideochannelquality <percent> |\n"
991 " setvideomodehint <xres> <yres> <bpp>\n"
992 " [[<display>] [<enabled:yes|no> |\n"
993 " [<xorigin> <yorigin>]]] |\n"
994 " screenshotpng <file> [display] |\n"
995 " videocap on|off |\n"
996 " videocapscreens all|none|<screen>,[<screen>...] |\n"
997 " videocapfile <file>\n"
998 " videocapres <width>x<height>\n"
999 " videocaprate <rate>\n"
1000 " videocapfps <fps>\n"
1001 " videocapmaxtime <ms>\n"
1002 " videocapmaxsize <MB>\n"
1003 " setcredentials <username>\n"
1004 " --passwordfile <file> | <password>\n"
1005 " <domain>\n"
1006 " [--allowlocallogon <yes|no>] |\n"
1007 " teleport --host <name> --port <port>\n"
1008 " [--maxdowntime <msec>]\n"
1009 " [--passwordfile <file> |\n"
1010 " --password <password>] |\n"
1011 " plugcpu <id> |\n"
1012 " unplugcpu <id> |\n"
1013 " cpuexecutioncap <1-100>\n"
1014 " webcam <attach [path [settings]]> | <detach [path]> | <list>\n"
1015 " addencpassword <id>\n"
1016 " <password file>|-\n"
1017 " [--removeonsuspend <yes|no>]\n"
1018 " removeencpassword <id>\n"
1019 " removeallencpasswords\n"
1020 "\n", SEP);
1021 }
1022
1023 if (fCategory & USAGE_UNATTENDEDINSTALL)
1024 RTStrmPrintf(pStrm,
1025 "%s unattended %s <uuid|vmname>\n"
1026 " --settings-file <file>\n"
1027 " [--session-type <type>]\n"
1028 "%s unattended %s <uuid|vmname>\n"
1029 " --user <user>\n"
1030 " --password <password>\n"
1031 " --iso-path <path>\n"
1032 " [--key <CD-key>]\n"
1033 " [--additions-iso-path <path>]\n"
1034 " [--install-additions]\n"
1035 " [--image-index <index>]\n"
1036 " [--session-type <type>]\n"
1037 "\n", SEP, SEP);
1038
1039 if (fCategory & USAGE_DISCARDSTATE)
1040 RTStrmPrintf(pStrm,
1041 "%s discardstate %s <uuid|vmname>\n"
1042 "\n", SEP);
1043
1044 if (fCategory & USAGE_ADOPTSTATE)
1045 RTStrmPrintf(pStrm,
1046 "%s adoptstate %s <uuid|vmname> <state_file>\n"
1047 "\n", SEP);
1048
1049 if (fCategory & USAGE_SNAPSHOT)
1050 RTStrmPrintf(pStrm,
1051 "%s snapshot %s <uuid|vmname>\n"
1052 " take <name> [--description <desc>] [--live]\n"
1053 " [--uniquename Number,Timestamp,Space,Force] |\n"
1054 " delete <uuid|snapname> |\n"
1055 " restore <uuid|snapname> |\n"
1056 " restorecurrent |\n"
1057 " edit <uuid|snapname>|--current\n"
1058 " [--name <name>]\n"
1059 " [--description <desc>] |\n"
1060 " list [--details|--machinereadable]\n"
1061 " showvminfo <uuid|snapname>\n"
1062 "\n", SEP);
1063
1064 if (fCategory & USAGE_CLOSEMEDIUM)
1065 RTStrmPrintf(pStrm,
1066 "%s closemedium %s [disk|dvd|floppy] <uuid|filename>\n"
1067 " [--delete]\n"
1068 "\n", SEP);
1069
1070 if (fCategory & USAGE_STORAGEATTACH)
1071 RTStrmPrintf(pStrm,
1072 "%s storageattach %s <uuid|vmname>\n"
1073 " --storagectl <name>\n"
1074 " [--port <number>]\n"
1075 " [--device <number>]\n"
1076 " [--type dvddrive|hdd|fdd]\n"
1077 " [--medium none|emptydrive|additions|\n"
1078 " <uuid|filename>|host:<drive>|iscsi]\n"
1079 " [--mtype normal|writethrough|immutable|shareable|\n"
1080 " readonly|multiattach]\n"
1081 " [--comment <text>]\n"
1082 " [--setuuid <uuid>]\n"
1083 " [--setparentuuid <uuid>]\n"
1084 " [--passthrough on|off]\n"
1085 " [--tempeject on|off]\n"
1086 " [--nonrotational on|off]\n"
1087 " [--discard on|off]\n"
1088 " [--hotpluggable on|off]\n"
1089 " [--bandwidthgroup <name>]\n"
1090 " [--forceunmount]\n"
1091 " [--server <name>|<ip>]\n"
1092 " [--target <target>]\n"
1093 " [--tport <port>]\n"
1094 " [--lun <lun>]\n"
1095 " [--encodedlun <lun>]\n"
1096 " [--username <username>]\n"
1097 " [--password <password>]\n"
1098 " [--initiator <initiator>]\n"
1099 " [--intnet]\n"
1100 "\n", SEP);
1101
1102 if (fCategory & USAGE_STORAGECONTROLLER)
1103 RTStrmPrintf(pStrm,
1104 "%s storagectl %s <uuid|vmname>\n"
1105 " --name <name>\n"
1106 " [--add ide|sata|scsi|floppy|sas|usb|pcie]\n"
1107 " [--controller LSILogic|LSILogicSAS|BusLogic|\n"
1108 " IntelAHCI|PIIX3|PIIX4|ICH6|I82078|\n"
1109 " [ USB|NVMe]\n"
1110 " [--portcount <1-n>]\n"
1111 " [--hostiocache on|off]\n"
1112 " [--bootable on|off]\n"
1113 " [--rename <name>]\n"
1114 " [--remove]\n"
1115 "\n", SEP);
1116
1117 if (fCategory & USAGE_BANDWIDTHCONTROL)
1118 RTStrmPrintf(pStrm,
1119 "%s bandwidthctl %s <uuid|vmname>\n"
1120 " add <name> --type disk|network\n"
1121 " --limit <megabytes per second>[k|m|g|K|M|G] |\n"
1122 " set <name>\n"
1123 " --limit <megabytes per second>[k|m|g|K|M|G] |\n"
1124 " remove <name> |\n"
1125 " list [--machinereadable]\n"
1126 " (limit units: k=kilobit, m=megabit, g=gigabit,\n"
1127 " K=kilobyte, M=megabyte, G=gigabyte)\n"
1128 "\n", SEP);
1129
1130 if (fCategory & USAGE_SHOWMEDIUMINFO)
1131 RTStrmPrintf(pStrm,
1132 "%s showmediuminfo %s [disk|dvd|floppy] <uuid|filename>\n"
1133 "\n", SEP);
1134
1135 if (fCategory & USAGE_CREATEMEDIUM)
1136 RTStrmPrintf(pStrm,
1137 "%s createmedium %s [disk|dvd|floppy] --filename <filename>\n"
1138 " [--size <megabytes>|--sizebyte <bytes>]\n"
1139 " [--diffparent <uuid>|<filename>\n"
1140 " [--format VDI|VMDK|VHD] (default: VDI)\n"
1141 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
1142 "\n", SEP);
1143
1144 if (fCategory & USAGE_MODIFYMEDIUM)
1145 RTStrmPrintf(pStrm,
1146 "%s modifymedium %s [disk|dvd|floppy] <uuid|filename>\n"
1147 " [--type normal|writethrough|immutable|shareable|\n"
1148 " readonly|multiattach]\n"
1149 " [--autoreset on|off]\n"
1150 " [--property <name=[value]>]\n"
1151 " [--compact]\n"
1152 " [--resize <megabytes>|--resizebyte <bytes>]\n"
1153 " [--move <path]\n"
1154 " [--description <description string>]"
1155 "\n", SEP);
1156
1157 if (fCategory & USAGE_CLONEMEDIUM)
1158 RTStrmPrintf(pStrm,
1159 "%s clonemedium %s [disk|dvd|floppy] <uuid|inputfile> <uuid|outputfile>\n"
1160 " [--format VDI|VMDK|VHD|RAW|<other>]\n"
1161 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
1162 " [--existing]\n"
1163 "\n", SEP);
1164
1165 if (fCategory & USAGE_MEDIUMPROPERTY)
1166 RTStrmPrintf(pStrm,
1167 "%s mediumproperty %s [disk|dvd|floppy] set <uuid|filename>\n"
1168 " <property> <value>\n"
1169 "\n"
1170 " [disk|dvd|floppy] get <uuid|filename>\n"
1171 " <property>\n"
1172 "\n"
1173 " [disk|dvd|floppy] delete <uuid|filename>\n"
1174 " <property>\n"
1175 "\n", SEP);
1176
1177 if (fCategory & USAGE_ENCRYPTMEDIUM)
1178 RTStrmPrintf(pStrm,
1179 "%s encryptmedium %s <uuid|filename>\n"
1180 " [--newpassword <file>|-]\n"
1181 " [--oldpassword <file>|-]\n"
1182 " [--cipher <cipher identifier>]\n"
1183 " [--newpasswordid <password identifier>]\n"
1184 "\n", SEP);
1185
1186 if (fCategory & USAGE_MEDIUMENCCHKPWD)
1187 RTStrmPrintf(pStrm,
1188 "%s checkmediumpwd %s <uuid|filename>\n"
1189 " <pwd file>|-\n"
1190 "\n", SEP);
1191
1192 if (fCategory & USAGE_CONVERTFROMRAW)
1193 RTStrmPrintf(pStrm,
1194 "%s convertfromraw %s <filename> <outputfile>\n"
1195 " [--format VDI|VMDK|VHD]\n"
1196 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
1197 " [--uuid <uuid>]\n"
1198 "%s convertfromraw %s stdin <outputfile> <bytes>\n"
1199 " [--format VDI|VMDK|VHD]\n"
1200 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
1201 " [--uuid <uuid>]\n"
1202 "\n", SEP, SEP);
1203
1204 if (fCategory & USAGE_GETEXTRADATA)
1205 RTStrmPrintf(pStrm,
1206 "%s getextradata %s global|<uuid|vmname>\n"
1207 " <key>|enumerate\n"
1208 "\n", SEP);
1209
1210 if (fCategory & USAGE_SETEXTRADATA)
1211 RTStrmPrintf(pStrm,
1212 "%s setextradata %s global|<uuid|vmname>\n"
1213 " <key>\n"
1214 " [<value>] (no value deletes key)\n"
1215 "\n", SEP);
1216
1217 if (fCategory & USAGE_SETPROPERTY)
1218 RTStrmPrintf(pStrm,
1219 "%s setproperty %s machinefolder default|<folder> |\n"
1220 " hwvirtexclusive on|off |\n"
1221 " vrdeauthlibrary default|<library> |\n"
1222 " websrvauthlibrary default|null|<library> |\n"
1223 " vrdeextpack null|<library> |\n"
1224 " autostartdbpath null|<folder> |\n"
1225 " loghistorycount <value>\n"
1226 " defaultfrontend default|<name>\n"
1227 " logginglevel <log setting>\n"
1228 "\n", SEP);
1229
1230 if (fCategory & USAGE_USBFILTER_ADD)
1231 RTStrmPrintf(pStrm,
1232 "%s usbfilter %s add <index,0-N>\n"
1233 " --target <uuid|vmname>|global\n"
1234 " --name <string>\n"
1235 " --action ignore|hold (global filters only)\n"
1236 " [--active yes|no] (yes)\n"
1237 " [--vendorid <XXXX>] (null)\n"
1238 " [--productid <XXXX>] (null)\n"
1239 " [--revision <IIFF>] (null)\n"
1240 " [--manufacturer <string>] (null)\n"
1241 " [--product <string>] (null)\n"
1242 " [--remote yes|no] (null, VM filters only)\n"
1243 " [--serialnumber <string>] (null)\n"
1244 " [--maskedinterfaces <XXXXXXXX>]\n"
1245 "\n", SEP);
1246
1247 if (fCategory & USAGE_USBFILTER_MODIFY)
1248 RTStrmPrintf(pStrm,
1249 "%s usbfilter %s modify <index,0-N>\n"
1250 " --target <uuid|vmname>|global\n"
1251 " [--name <string>]\n"
1252 " [--action ignore|hold] (global filters only)\n"
1253 " [--active yes|no]\n"
1254 " [--vendorid <XXXX>|\"\"]\n"
1255 " [--productid <XXXX>|\"\"]\n"
1256 " [--revision <IIFF>|\"\"]\n"
1257 " [--manufacturer <string>|\"\"]\n"
1258 " [--product <string>|\"\"]\n"
1259 " [--remote yes|no] (null, VM filters only)\n"
1260 " [--serialnumber <string>|\"\"]\n"
1261 " [--maskedinterfaces <XXXXXXXX>]\n"
1262 "\n", SEP);
1263
1264 if (fCategory & USAGE_USBFILTER_REMOVE)
1265 RTStrmPrintf(pStrm,
1266 "%s usbfilter %s remove <index,0-N>\n"
1267 " --target <uuid|vmname>|global\n"
1268 "\n", SEP);
1269
1270 if (fCategory & USAGE_SHAREDFOLDER_ADD)
1271 RTStrmPrintf(pStrm,
1272 "%s sharedfolder %s add <uuid|vmname>\n"
1273 " --name <name> --hostpath <hostpath>\n"
1274 " [--transient] [--readonly] [--automount]\n"
1275 "\n", SEP);
1276
1277 if (fCategory & USAGE_SHAREDFOLDER_REMOVE)
1278 RTStrmPrintf(pStrm,
1279 "%s sharedfolder %s remove <uuid|vmname>\n"
1280 " --name <name> [--transient]\n"
1281 "\n", SEP);
1282
1283#ifdef VBOX_WITH_GUEST_PROPS
1284 if (fCategory & USAGE_GUESTPROPERTY)
1285 usageGuestProperty(pStrm, SEP);
1286#endif /* VBOX_WITH_GUEST_PROPS defined */
1287
1288#ifdef VBOX_WITH_GUEST_CONTROL
1289 if (fCategory & USAGE_GUESTCONTROL)
1290 usageGuestControl(pStrm, SEP, fSubCategory);
1291#endif /* VBOX_WITH_GUEST_CONTROL defined */
1292
1293 if (fCategory & USAGE_METRICS)
1294 RTStrmPrintf(pStrm,
1295 "%s metrics %s list [*|host|<vmname> [<metric_list>]]\n"
1296 " (comma-separated)\n\n"
1297 "%s metrics %s setup\n"
1298 " [--period <seconds>] (default: 1)\n"
1299 " [--samples <count>] (default: 1)\n"
1300 " [--list]\n"
1301 " [*|host|<vmname> [<metric_list>]]\n\n"
1302 "%s metrics %s query [*|host|<vmname> [<metric_list>]]\n\n"
1303 "%s metrics %s enable\n"
1304 " [--list]\n"
1305 " [*|host|<vmname> [<metric_list>]]\n\n"
1306 "%s metrics %s disable\n"
1307 " [--list]\n"
1308 " [*|host|<vmname> [<metric_list>]]\n\n"
1309 "%s metrics %s collect\n"
1310 " [--period <seconds>] (default: 1)\n"
1311 " [--samples <count>] (default: 1)\n"
1312 " [--list]\n"
1313 " [--detach]\n"
1314 " [*|host|<vmname> [<metric_list>]]\n"
1315 "\n", SEP, SEP, SEP, SEP, SEP, SEP);
1316
1317#if defined(VBOX_WITH_NAT_SERVICE)
1318 if (fCategory & USAGE_NATNETWORK)
1319 {
1320 RTStrmPrintf(pStrm,
1321 "%s natnetwork %s add --netname <name>\n"
1322 " --network <network>\n"
1323 " [--enable|--disable]\n"
1324 " [--dhcp on|off]\n"
1325 " [--port-forward-4 <rule>]\n"
1326 " [--loopback-4 <rule>]\n"
1327 " [--ipv6 on|off]\n"
1328 " [--port-forward-6 <rule>]\n"
1329 " [--loopback-6 <rule>]\n\n"
1330 "%s natnetwork %s remove --netname <name>\n\n"
1331 "%s natnetwork %s modify --netname <name>\n"
1332 " [--network <network>]\n"
1333 " [--enable|--disable]\n"
1334 " [--dhcp on|off]\n"
1335 " [--port-forward-4 <rule>]\n"
1336 " [--loopback-4 <rule>]\n"
1337 " [--ipv6 on|off]\n"
1338 " [--port-forward-6 <rule>]\n"
1339 " [--loopback-6 <rule>]\n\n"
1340 "%s natnetwork %s start --netname <name>\n\n"
1341 "%s natnetwork %s stop --netname <name>\n\n"
1342 "%s natnetwork %s list [<pattern>]\n"
1343 "\n", SEP, SEP, SEP, SEP, SEP, SEP);
1344
1345
1346 }
1347#endif
1348
1349#if defined(VBOX_WITH_NETFLT)
1350 if (fCategory & USAGE_HOSTONLYIFS)
1351 {
1352 RTStrmPrintf(pStrm,
1353 "%s hostonlyif %s ipconfig <name>\n"
1354 " [--dhcp |\n"
1355 " --ip<ipv4> [--netmask<ipv4> (def: 255.255.255.0)] |\n"
1356 " --ipv6<ipv6> [--netmasklengthv6<length> (def: 64)]]\n"
1357# if !defined(RT_OS_SOLARIS) || defined(VBOX_ONLY_DOCS)
1358 " create |\n"
1359 " remove <name>\n"
1360# endif
1361 "\n", SEP);
1362 }
1363#endif
1364
1365 if (fCategory & USAGE_DHCPSERVER)
1366 {
1367 RTStrmPrintf(pStrm,
1368 "%s dhcpserver %s add|modify --netname <network_name> |\n"
1369#if defined(VBOX_WITH_NETFLT)
1370 " --ifname <hostonly_if_name>\n"
1371#endif
1372 " [--ip <ip_address>\n"
1373 " --netmask <network_mask>\n"
1374 " --lowerip <lower_ip>\n"
1375 " --upperip <upper_ip>]\n"
1376 " [--enable | --disable]\n\n"
1377 "%s dhcpserver %s remove --netname <network_name> |\n"
1378#if defined(VBOX_WITH_NETFLT)
1379 " --ifname <hostonly_if_name>\n"
1380#endif
1381 "\n", SEP, SEP);
1382 }
1383
1384 if (fCategory & USAGE_USBDEVSOURCE)
1385 {
1386 RTStrmPrintf(pStrm,
1387 "%s usbdevsource %s add <source name>\n"
1388 " --backend <backend>\n"
1389 " --address <address>\n"
1390 "%s usbdevsource %s remove <source name>\n"
1391 "\n", SEP, SEP);
1392 }
1393
1394#ifndef VBOX_ONLY_DOCS /* Converted to man page, not needed. */
1395 if (fCategory == USAGE_ALL)
1396 {
1397 uint32_t cPendingBlankLines = 0;
1398 for (uint32_t i = 0; i < g_cHelpEntries; i++)
1399 {
1400 PCREFENTRY pHelp = g_apHelpEntries[i];
1401 while (cPendingBlankLines-- > 0)
1402 RTStrmPutCh(pStrm, '\n');
1403 RTStrmPrintf(pStrm, " %c%s:\n", RT_C_TO_UPPER(pHelp->pszBrief[0]), pHelp->pszBrief + 1);
1404 cPendingBlankLines = printStringTable(pStrm, &pHelp->Synopsis, REFENTRYSTR_SCOPE_GLOBAL, 0);
1405 cPendingBlankLines = RT_MAX(cPendingBlankLines, 1);
1406 }
1407 }
1408#endif
1409}
1410
1411/**
1412 * Print a usage synopsis and the syntax error message.
1413 * @returns RTEXITCODE_SYNTAX.
1414 */
1415RTEXITCODE errorSyntax(USAGECATEGORY fCategory, const char *pszFormat, ...)
1416{
1417 va_list args;
1418 showLogo(g_pStdErr); // show logo even if suppressed
1419#ifndef VBOX_ONLY_DOCS
1420 if (g_fInternalMode)
1421 printUsageInternal(fCategory, g_pStdErr);
1422 else
1423 printUsage(fCategory, ~0U, g_pStdErr);
1424#else
1425 RT_NOREF_PV(fCategory);
1426#endif
1427 va_start(args, pszFormat);
1428 RTStrmPrintf(g_pStdErr, "\nSyntax error: %N\n", pszFormat, &args);
1429 va_end(args);
1430 return RTEXITCODE_SYNTAX;
1431}
1432
1433/**
1434 * Print a usage synopsis and the syntax error message.
1435 * @returns RTEXITCODE_SYNTAX.
1436 */
1437RTEXITCODE errorSyntaxEx(USAGECATEGORY fCategory, uint32_t fSubCategory, const char *pszFormat, ...)
1438{
1439 va_list args;
1440 showLogo(g_pStdErr); // show logo even if suppressed
1441#ifndef VBOX_ONLY_DOCS
1442 if (g_fInternalMode)
1443 printUsageInternal(fCategory, g_pStdErr);
1444 else
1445 printUsage(fCategory, fSubCategory, g_pStdErr);
1446#else
1447 RT_NOREF2(fCategory, fSubCategory);
1448#endif
1449 va_start(args, pszFormat);
1450 RTStrmPrintf(g_pStdErr, "\nSyntax error: %N\n", pszFormat, &args);
1451 va_end(args);
1452 return RTEXITCODE_SYNTAX;
1453}
1454
1455/**
1456 * errorSyntax for RTGetOpt users.
1457 *
1458 * @returns RTEXITCODE_SYNTAX.
1459 *
1460 * @param fCategory The usage category of the command.
1461 * @param fSubCategory The usage sub-category of the command.
1462 * @param rc The RTGetOpt return code.
1463 * @param pValueUnion The value union.
1464 */
1465RTEXITCODE errorGetOptEx(USAGECATEGORY fCategory, uint32_t fSubCategory, int rc, union RTGETOPTUNION const *pValueUnion)
1466{
1467 /*
1468 * Check if it is an unhandled standard option.
1469 */
1470#ifndef VBOX_ONLY_DOCS
1471 if (rc == 'V')
1472 {
1473 RTPrintf("%sr%d\n", VBOX_VERSION_STRING, RTBldCfgRevision());
1474 return RTEXITCODE_SUCCESS;
1475 }
1476#endif
1477
1478 if (rc == 'h')
1479 {
1480 showLogo(g_pStdErr);
1481#ifndef VBOX_ONLY_DOCS
1482 if (g_fInternalMode)
1483 printUsageInternal(fCategory, g_pStdOut);
1484 else
1485 printUsage(fCategory, fSubCategory, g_pStdOut);
1486#endif
1487 return RTEXITCODE_SUCCESS;
1488 }
1489
1490 /*
1491 * General failure.
1492 */
1493 showLogo(g_pStdErr); // show logo even if suppressed
1494#ifndef VBOX_ONLY_DOCS
1495 if (g_fInternalMode)
1496 printUsageInternal(fCategory, g_pStdErr);
1497 else
1498 printUsage(fCategory, fSubCategory, g_pStdErr);
1499#else
1500 RT_NOREF2(fCategory, fSubCategory);
1501#endif
1502
1503 if (rc == VINF_GETOPT_NOT_OPTION)
1504 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Invalid parameter '%s'", pValueUnion->psz);
1505 if (rc > 0)
1506 {
1507 if (RT_C_IS_PRINT(rc))
1508 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Invalid option -%c", rc);
1509 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Invalid option case %i", rc);
1510 }
1511 if (rc == VERR_GETOPT_UNKNOWN_OPTION)
1512 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Unknown option: %s", pValueUnion->psz);
1513 if (rc == VERR_GETOPT_INVALID_ARGUMENT_FORMAT)
1514 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Invalid argument format: %s", pValueUnion->psz);
1515 if (pValueUnion->pDef)
1516 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "%s: %Rrs", pValueUnion->pDef->pszLong, rc);
1517 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "%Rrs", rc);
1518}
1519
1520/**
1521 * errorSyntax for RTGetOpt users.
1522 *
1523 * @returns RTEXITCODE_SYNTAX.
1524 *
1525 * @param fUsageCategory The usage category of the command.
1526 * @param rc The RTGetOpt return code.
1527 * @param pValueUnion The value union.
1528 */
1529RTEXITCODE errorGetOpt(USAGECATEGORY fCategory, int rc, union RTGETOPTUNION const *pValueUnion)
1530{
1531 return errorGetOptEx(fCategory, ~0U, rc, pValueUnion);
1532}
1533
1534/**
1535 * Print an error message without the syntax stuff.
1536 *
1537 * @returns RTEXITCODE_SYNTAX.
1538 */
1539RTEXITCODE errorArgument(const char *pszFormat, ...)
1540{
1541 va_list args;
1542 va_start(args, pszFormat);
1543 RTMsgErrorV(pszFormat, args);
1544 va_end(args);
1545 return RTEXITCODE_SYNTAX;
1546}
1547
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette