VirtualBox

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

Last change on this file since 57671 was 57525, checked in by vboxsync, 9 years ago

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