VirtualBox

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

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

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