VirtualBox

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

Last change on this file since 92710 was 92538, checked in by vboxsync, 3 years ago

VBoxManage/modifyvm,showvminfo: Added --testing-enabled=bool, --testing-mmio=bool and --testing-cfg-dwordN=val switches to modifyvm for easy VMMDev/Testing config. Display these settings in showvminfo.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 48.0 KB
Line 
1/* $Id: VBoxManageHelp.cpp 92538 2021-11-22 01:53:20Z vboxsync $ */
2/** @file
3 * VBoxManage - help and other message output.
4 */
5
6/*
7 * Copyright (C) 2006-2020 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/assert.h>
27#include <iprt/env.h>
28#include <iprt/err.h>
29#include <iprt/getopt.h>
30#include <iprt/stream.h>
31#include <iprt/message.h>
32
33#include "VBoxManage.h"
34
35
36/*********************************************************************************************************************************
37* Defined Constants And Macros *
38*********************************************************************************************************************************/
39/** If the usage is the given number of length long or longer, the error is
40 * repeated so the user can actually see it. */
41#define ERROR_REPEAT_AFTER_USAGE_LENGTH 16
42
43
44/*********************************************************************************************************************************
45* Global Variables *
46*********************************************************************************************************************************/
47DECLARE_TRANSLATION_CONTEXT(Help);
48
49#ifndef VBOX_ONLY_DOCS
50static enum HELP_CMD_VBOXMANAGE g_enmCurCommand = HELP_CMD_VBOXMANAGE_INVALID;
51/** The scope mask for the current subcommand. */
52static uint64_t g_fCurSubcommandScope = RTMSGREFENTRYSTR_SCOPE_GLOBAL;
53
54/**
55 * Sets the current command.
56 *
57 * This affects future calls to error and help functions.
58 *
59 * @param enmCommand The command.
60 */
61void setCurrentCommand(enum HELP_CMD_VBOXMANAGE enmCommand)
62{
63 Assert(g_enmCurCommand == HELP_CMD_VBOXMANAGE_INVALID);
64 g_enmCurCommand = enmCommand;
65 g_fCurSubcommandScope = RTMSGREFENTRYSTR_SCOPE_GLOBAL;
66}
67
68
69/**
70 * Sets the current subcommand.
71 *
72 * This affects future calls to error and help functions.
73 *
74 * @param fSubcommandScope The subcommand scope.
75 */
76void setCurrentSubcommand(uint64_t fSubcommandScope)
77{
78 g_fCurSubcommandScope = fSubcommandScope;
79}
80
81
82
83
84/**
85 * Prints brief help for a command or subcommand.
86 *
87 * @returns Number of lines written.
88 * @param enmCommand The command.
89 * @param fSubcommandScope The subcommand scope, REFENTRYSTR_SCOPE_GLOBAL
90 * for all.
91 * @param pStrm The output stream.
92 */
93static uint32_t printBriefCommandOrSubcommandHelp(enum HELP_CMD_VBOXMANAGE enmCommand, uint64_t fSubcommandScope, PRTSTREAM pStrm)
94{
95 uint32_t cLinesWritten = 0;
96 uint32_t cPendingBlankLines = 0;
97 uint32_t cFound = 0;
98 for (uint32_t i = 0; i < g_cHelpEntries; i++)
99 {
100 PCRTMSGREFENTRY pHelp = g_apHelpEntries[i];
101 if (pHelp->idInternal == (int64_t)enmCommand)
102 {
103 cFound++;
104 if (cFound == 1)
105 {
106 if (fSubcommandScope == RTMSGREFENTRYSTR_SCOPE_GLOBAL)
107 RTStrmPrintf(pStrm, Help::tr("Usage - %c%s:\n"), RT_C_TO_UPPER(pHelp->pszBrief[0]), pHelp->pszBrief + 1);
108 else
109 RTStrmPrintf(pStrm, Help::tr("Usage:\n"));
110 }
111 RTMsgRefEntryPrintStringTable(pStrm, &pHelp->Synopsis, fSubcommandScope, &cPendingBlankLines, &cLinesWritten);
112 if (!cPendingBlankLines)
113 cPendingBlankLines = 1;
114 }
115 }
116 Assert(cFound > 0);
117 return cLinesWritten;
118}
119
120
121/**
122 * Prints the brief usage information for the current (sub)command.
123 *
124 * @param pStrm The output stream.
125 */
126void printUsage(PRTSTREAM pStrm)
127{
128 printBriefCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, pStrm);
129}
130
131
132/**
133 * Prints full help for a command or subcommand.
134 *
135 * @param enmCommand The command.
136 * @param fSubcommandScope The subcommand scope, REFENTRYSTR_SCOPE_GLOBAL
137 * for all.
138 * @param pStrm The output stream.
139 */
140static void printFullCommandOrSubcommandHelp(enum HELP_CMD_VBOXMANAGE enmCommand, uint64_t fSubcommandScope, PRTSTREAM pStrm)
141{
142 uint32_t cPendingBlankLines = 0;
143 uint32_t cFound = 0;
144 for (uint32_t i = 0; i < g_cHelpEntries; i++)
145 {
146 PCRTMSGREFENTRY pHelp = g_apHelpEntries[i];
147 if ( pHelp->idInternal == (int64_t)enmCommand
148 || enmCommand == HELP_CMD_VBOXMANAGE_INVALID)
149 {
150 cFound++;
151 RTMsgRefEntryPrintStringTable(pStrm, &pHelp->Help, fSubcommandScope, &cPendingBlankLines, NULL /*pcLinesWritten*/);
152 if (cPendingBlankLines < 2)
153 cPendingBlankLines = 2;
154 }
155 }
156 Assert(cFound > 0);
157}
158
159
160/**
161 * Prints the full help for the current (sub)command.
162 *
163 * @param pStrm The output stream.
164 */
165void printHelp(PRTSTREAM pStrm)
166{
167 printFullCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, pStrm);
168}
169
170
171/**
172 * Display no subcommand error message and current command usage.
173 *
174 * @returns RTEXITCODE_SYNTAX.
175 */
176RTEXITCODE errorNoSubcommand(void)
177{
178 Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID);
179 Assert(g_fCurSubcommandScope == RTMSGREFENTRYSTR_SCOPE_GLOBAL);
180
181 return errorSyntax(Help::tr("No subcommand specified"));
182}
183
184
185/**
186 * Display unknown subcommand error message and current command usage.
187 *
188 * May show full command help instead if the subcommand is a common help option.
189 *
190 * @returns RTEXITCODE_SYNTAX, or RTEXITCODE_SUCCESS if common help option.
191 * @param pszSubcommand The name of the alleged subcommand.
192 */
193RTEXITCODE errorUnknownSubcommand(const char *pszSubcommand)
194{
195 Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID);
196 Assert(g_fCurSubcommandScope == RTMSGREFENTRYSTR_SCOPE_GLOBAL);
197
198 /* check if help was requested. */
199 if ( strcmp(pszSubcommand, "--help") == 0
200 || strcmp(pszSubcommand, "-h") == 0
201 || strcmp(pszSubcommand, "-?") == 0)
202 {
203 printFullCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, g_pStdOut);
204 return RTEXITCODE_SUCCESS;
205 }
206
207 return errorSyntax(Help::tr("Unknown subcommand: %s"), pszSubcommand);
208}
209
210
211/**
212 * Display too many parameters error message and current command usage.
213 *
214 * May show full command help instead if the subcommand is a common help option.
215 *
216 * @returns RTEXITCODE_SYNTAX, or RTEXITCODE_SUCCESS if common help option.
217 * @param papszArgs The first unwanted parameter. Terminated by
218 * NULL entry.
219 */
220RTEXITCODE errorTooManyParameters(char **papszArgs)
221{
222 Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID);
223 Assert(g_fCurSubcommandScope != RTMSGREFENTRYSTR_SCOPE_GLOBAL);
224
225 /* check if help was requested. */
226 if (papszArgs)
227 {
228 for (uint32_t i = 0; papszArgs[i]; i++)
229 if ( strcmp(papszArgs[i], "--help") == 0
230 || strcmp(papszArgs[i], "-h") == 0
231 || strcmp(papszArgs[i], "-?") == 0)
232 {
233 printFullCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, g_pStdOut);
234 return RTEXITCODE_SUCCESS;
235 }
236 else if (!strcmp(papszArgs[i], "--"))
237 break;
238 }
239
240 return errorSyntax(Help::tr("Too many parameters"));
241}
242
243
244/**
245 * Display current (sub)command usage and the custom error message.
246 *
247 * @returns RTEXITCODE_SYNTAX.
248 * @param pszFormat Custom error message format string.
249 * @param va Format arguments.
250 */
251RTEXITCODE errorSyntaxV(const char *pszFormat, va_list va)
252{
253 Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID);
254
255 showLogo(g_pStdErr);
256
257 va_list vaCopy;
258 va_copy(vaCopy, va);
259 RTMsgErrorV(pszFormat, vaCopy);
260 va_end(vaCopy);
261
262 RTStrmPutCh(g_pStdErr, '\n');
263 if ( printBriefCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, g_pStdErr)
264 >= ERROR_REPEAT_AFTER_USAGE_LENGTH)
265 {
266 /* Usage was very long, repeat the error message. */
267 RTStrmPutCh(g_pStdErr, '\n');
268 RTMsgErrorV(pszFormat, va);
269 }
270 return RTEXITCODE_SYNTAX;
271}
272
273
274/**
275 * Display current (sub)command usage and the custom error message.
276 *
277 * @returns RTEXITCODE_SYNTAX.
278 * @param pszFormat Custom error message format string.
279 * @param ... Format arguments.
280 */
281RTEXITCODE errorSyntax(const char *pszFormat, ...)
282{
283 va_list va;
284 va_start(va, pszFormat);
285 RTEXITCODE rcExit = errorSyntaxV(pszFormat, va);
286 va_end(va);
287 return rcExit;
288}
289
290
291/**
292 * Display current (sub)command usage and the custom error message.
293 *
294 * @returns E_INVALIDARG
295 * @param pszFormat Custom error message format string.
296 * @param ... Format arguments.
297 */
298HRESULT errorSyntaxHr(const char *pszFormat, ...)
299{
300 va_list va;
301 va_start(va, pszFormat);
302 errorSyntaxV(pszFormat, va);
303 va_end(va);
304 return E_INVALIDARG;
305}
306
307
308/**
309 * Print an error message without the syntax stuff.
310 *
311 * @returns RTEXITCODE_SYNTAX.
312 */
313RTEXITCODE errorArgument(const char *pszFormat, ...)
314{
315 va_list args;
316 va_start(args, pszFormat);
317 RTMsgErrorV(pszFormat, args);
318 va_end(args);
319 return RTEXITCODE_SYNTAX;
320}
321
322
323/**
324 * Print an error message without the syntax stuff.
325 *
326 * @returns E_INVALIDARG.
327 */
328HRESULT errorArgumentHr(const char *pszFormat, ...)
329{
330 va_list args;
331 va_start(args, pszFormat);
332 RTMsgErrorV(pszFormat, args);
333 va_end(args);
334 return E_INVALIDARG;
335}
336
337
338/**
339 * Worker for errorGetOpt.
340 *
341 * @param rcGetOpt The RTGetOpt return value.
342 * @param pValueUnion The value union returned by RTGetOpt.
343 */
344static void errorGetOptWorker(int rcGetOpt, union RTGETOPTUNION const *pValueUnion)
345{
346 if (rcGetOpt == VINF_GETOPT_NOT_OPTION)
347 RTMsgError(Help::tr("Invalid parameter '%s'"), pValueUnion->psz);
348 else if (rcGetOpt > 0)
349 {
350 if (RT_C_IS_PRINT(rcGetOpt))
351 RTMsgError(Help::tr("Invalid option -%c"), rcGetOpt);
352 else
353 RTMsgError(Help::tr("Invalid option case %i"), rcGetOpt);
354 }
355 else if (rcGetOpt == VERR_GETOPT_UNKNOWN_OPTION)
356 RTMsgError(Help::tr("Unknown option: %s"), pValueUnion->psz);
357 else if (rcGetOpt == VERR_GETOPT_INVALID_ARGUMENT_FORMAT)
358 RTMsgError(Help::tr("Invalid argument format: %s"), pValueUnion->psz);
359 else if (pValueUnion->pDef)
360 RTMsgError("%s: %Rrs", pValueUnion->pDef->pszLong, rcGetOpt);
361 else
362 RTMsgError("%Rrs", rcGetOpt);
363}
364
365
366/**
367 * For use to deal with RTGetOptFetchValue failures.
368 *
369 * @retval RTEXITCODE_SYNTAX
370 * @param iValueNo The value number being fetched, counting the
371 * RTGetOpt value as zero and the first
372 * RTGetOptFetchValue call as one.
373 * @param pszOption The option being parsed.
374 * @param rcGetOptFetchValue The status returned by RTGetOptFetchValue.
375 * @param pValueUnion The value union returned by the fetch.
376 */
377RTEXITCODE errorFetchValue(int iValueNo, const char *pszOption, int rcGetOptFetchValue, union RTGETOPTUNION const *pValueUnion)
378{
379 Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID);
380 showLogo(g_pStdErr);
381 if (rcGetOptFetchValue == VERR_GETOPT_REQUIRED_ARGUMENT_MISSING)
382 RTMsgError(Help::tr("Missing the %u%s value for option %s"),
383 iValueNo,
384 iValueNo == 1 ? Help::tr("st")
385 : iValueNo == 2 ? Help::tr("nd")
386 : iValueNo == 3 ? Help::tr("rd")
387 : Help::tr("th"),
388 pszOption);
389 else
390 errorGetOptWorker(rcGetOptFetchValue, pValueUnion);
391 return RTEXITCODE_SYNTAX;
392
393}
394
395
396/**
397 * Handled an RTGetOpt error or common option.
398 *
399 * This implements the 'V' and 'h' cases. It reports appropriate syntax errors
400 * for other @a rcGetOpt values.
401 *
402 * @retval RTEXITCODE_SUCCESS if help or version request.
403 * @retval RTEXITCODE_SYNTAX if not help or version request.
404 * @param rcGetOpt The RTGetOpt return value.
405 * @param pValueUnion The value union returned by RTGetOpt.
406 */
407RTEXITCODE errorGetOpt(int rcGetOpt, union RTGETOPTUNION const *pValueUnion)
408{
409 Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID);
410
411 /*
412 * Check if it is an unhandled standard option.
413 */
414 if (rcGetOpt == 'V')
415 {
416 RTPrintf("%sr%d\n", VBOX_VERSION_STRING, RTBldCfgRevision());
417 return RTEXITCODE_SUCCESS;
418 }
419
420 if (rcGetOpt == 'h')
421 {
422 printFullCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, g_pStdOut);
423 return RTEXITCODE_SUCCESS;
424 }
425
426 /*
427 * We failed.
428 */
429 showLogo(g_pStdErr);
430 errorGetOptWorker(rcGetOpt, pValueUnion);
431 if ( printBriefCommandOrSubcommandHelp(g_enmCurCommand, g_fCurSubcommandScope, g_pStdErr)
432 >= ERROR_REPEAT_AFTER_USAGE_LENGTH)
433 {
434 /* Usage was very long, repeat the error message. */
435 RTStrmPutCh(g_pStdErr, '\n');
436 errorGetOptWorker(rcGetOpt, pValueUnion);
437 }
438 return RTEXITCODE_SYNTAX;
439}
440
441#endif /* !VBOX_ONLY_DOCS */
442
443
444
445void showLogo(PRTSTREAM pStrm)
446{
447 static bool s_fShown; /* show only once */
448
449 if (!s_fShown)
450 {
451 RTStrmPrintf(pStrm, VBOX_PRODUCT " Command Line Management Interface Version "
452 VBOX_VERSION_STRING "\n"
453 "(C) 2005-" VBOX_C_YEAR " " VBOX_VENDOR "\n"
454 "All rights reserved.\n"
455 "\n");
456 s_fShown = true;
457 }
458}
459
460
461
462
463void printUsage(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, PRTSTREAM pStrm)
464{
465 bool fDumpOpts = false;
466#ifdef RT_OS_LINUX
467 bool fLinux = true;
468#else
469 bool fLinux = false;
470#endif
471#ifdef RT_OS_WINDOWS
472 bool fWin = true;
473#else
474 bool fWin = false;
475#endif
476#ifdef RT_OS_SOLARIS
477 bool fSolaris = true;
478#else
479 bool fSolaris = false;
480#endif
481#ifdef RT_OS_FREEBSD
482 bool fFreeBSD = true;
483#else
484 bool fFreeBSD = false;
485#endif
486#ifdef RT_OS_DARWIN
487 bool fDarwin = true;
488#else
489 bool fDarwin = false;
490#endif
491#ifdef VBOX_WITH_VBOXSDL
492 bool fVBoxSDL = true;
493#else
494 bool fVBoxSDL = false;
495#endif
496
497 Assert(enmCommand != USAGE_INVALID);
498 Assert(enmCommand != USAGE_S_NEWCMD);
499
500 if (enmCommand == USAGE_S_DUMPOPTS)
501 {
502 fDumpOpts = true;
503 fLinux = true;
504 fWin = true;
505 fSolaris = true;
506 fFreeBSD = true;
507 fDarwin = true;
508 fVBoxSDL = true;
509 enmCommand = USAGE_S_ALL;
510 }
511
512 RTStrmPrintf(pStrm,
513 Help::tr("Usage:\n"
514 "\n"));
515
516 if (enmCommand == USAGE_S_ALL)
517 RTStrmPrintf(pStrm,
518 " VBoxManage [<general option>] <command>\n"
519 "\n"
520 "\n"
521 "General Options:\n"
522 "\n"
523 " [-V|--version] print version number and exit\n"
524 " [--dump-build-type] print build type and exit\n"
525 " [-q|--nologo] suppress the logo\n"
526 " [--settingspw <pw>] provide the settings password\n"
527 " [--settingspwfile <file>] provide a file containing the settings password\n"
528 " [@<response-file>] load arguments from the given response file (bourne style)\n"
529 "\n"
530 "\n"
531 "Commands:\n"
532 "\n");
533
534 const char *pcszSep1 = " ";
535 const char *pcszSep2 = " ";
536 if (enmCommand != USAGE_S_ALL)
537 {
538 pcszSep1 = "VBoxManage";
539 pcszSep2 = "";
540 }
541
542#define SEP pcszSep1, pcszSep2
543
544 if (enmCommand == USAGE_STARTVM || enmCommand == USAGE_S_ALL)
545 {
546 RTStrmPrintf(pStrm,
547 "%s startvm %s <uuid|vmname>...\n"
548 " [--type gui", SEP);
549 if (fVBoxSDL)
550 RTStrmPrintf(pStrm, "|sdl");
551 RTStrmPrintf(pStrm, "|headless|separate]\n");
552 RTStrmPrintf(pStrm,
553 " [-E|--putenv <NAME>[=<VALUE>]]\n"
554 "\n");
555 }
556
557 if (enmCommand == USAGE_CONTROLVM || enmCommand == USAGE_S_ALL)
558 {
559 RTStrmPrintf(pStrm,
560 "%s controlvm %s <uuid|vmname>\n"
561 " pause|resume|reset|poweroff|savestate|\n", SEP);
562#ifdef VBOX_WITH_GUEST_CONTROL
563 RTStrmPrintf(pStrm,
564 " reboot|shutdown [--force]|\n");
565#endif
566 RTStrmPrintf(pStrm,
567 " acpipowerbutton|acpisleepbutton|\n"
568 " keyboardputscancode <hex> [<hex> ...]|\n"
569 " keyboardputstring <string1> [<string2> ...]|\n"
570 " keyboardputfile <filename>|\n"
571 " setlinkstate<1-N> on|off |\n");
572#if defined(VBOX_WITH_NETFLT)
573 RTStrmPrintf(pStrm,
574 " nic<1-N> null|nat|bridged|intnet|hostonly|generic|\n"
575 " natnetwork [<devicename>] |\n");
576#else /* !VBOX_WITH_NETFLT */
577 RTStrmPrintf(pStrm,
578 " nic<1-N> null|nat|bridged|intnet|generic|natnetwork\n"
579 " [<devicename>] |\n");
580#endif /* !VBOX_WITH_NETFLT */
581 RTStrmPrintf(pStrm,
582 " nictrace<1-N> on|off |\n"
583 " nictracefile<1-N> <filename> |\n"
584 " nicproperty<1-N> name=[value] |\n"
585 " nicpromisc<1-N> deny|allow-vms|allow-all |\n"
586 " natpf<1-N> [<rulename>],tcp|udp,[<hostip>],\n"
587 " <hostport>,[<guestip>],<guestport> |\n"
588 " natpf<1-N> delete <rulename> |\n"
589 " guestmemoryballoon <balloonsize in MB> |\n"
590 " usbattach <uuid>|<address>\n"
591 " [--capturefile <filename>] |\n"
592 " usbdetach <uuid>|<address> |\n"
593 " audioin on|off |\n"
594 " audioout on|off |\n");
595#ifdef VBOX_WITH_SHARED_CLIPBOARD
596 RTStrmPrintf(pStrm,
597 " clipboard mode disabled|hosttoguest|guesttohost|\n"
598 " bidirectional |\n");
599# ifdef VBOX_WITH_SHARED_CLIPBOARD_TRANSFERS
600 RTStrmPrintf(pStrm,
601 " clipboard filetransfers enabled|disabled |\n");
602# endif
603#endif
604 RTStrmPrintf(pStrm,
605 " draganddrop disabled|hosttoguest|guesttohost|\n"
606 " bidirectional |\n"
607 " vrde on|off |\n"
608 " vrdeport <port> |\n"
609 " vrdeproperty <name=[value]> |\n"
610 " vrdevideochannelquality <percent> |\n"
611 " setvideomodehint <xres> <yres> <bpp>\n"
612 " [[<display>] [<enabled:yes|no> |\n"
613 " [<xorigin> <yorigin>]]] |\n"
614 " setscreenlayout <display> on|primary <xorigin> <yorigin> <xres> <yres> <bpp> | off\n"
615 " screenshotpng <file> [display] |\n");
616#ifdef VBOX_WITH_RECORDING
617 RTStrmPrintf(pStrm,
618 " recording on|off |\n"
619 " recording screens all|none|<screen>,[<screen>...] |\n"
620 " recording filename <file> |\n"
621 " recording videores <width>x<height> |\n"
622 " recording videorate <rate> |\n"
623 " recording videofps <fps> |\n"
624 " recording maxtime <s> |\n"
625 " recording maxfilesize <MB> |\n");
626#endif /* VBOX_WITH_RECORDING */
627 RTStrmPrintf(pStrm,
628 " setcredentials <username>\n"
629 " --passwordfile <file> | <password>\n"
630 " <domain>\n"
631 " [--allowlocallogon <yes|no>] |\n"
632 " teleport --host <name> --port <port>\n"
633 " [--maxdowntime <msec>]\n"
634 " [--passwordfile <file> |\n"
635 " --password <password>] |\n"
636 " plugcpu <id> |\n"
637 " unplugcpu <id> |\n"
638 " cpuexecutioncap <1-100>\n"
639 " webcam <attach [path [settings]]> | <detach [path]> | <list>\n"
640 " addencpassword <id>\n"
641 " <password file>|-\n"
642 " [--removeonsuspend <yes|no>]\n"
643 " removeencpassword <id>\n"
644 " removeallencpasswords\n"
645 " changeuartmode<1-N> disconnected|\n"
646 " server <pipe>|\n"
647 " client <pipe>|\n"
648 " tcpserver <port>|\n"
649 " tcpclient <hostname:port>|\n"
650 " file <file>|\n"
651 " <devicename>\n"
652 " vm-process-priority default|flat|low|normal|high\n"
653 " autostart-enabled on|off\n"
654 " autostart-delay <seconds>\n"
655 "\n");
656 }
657
658 if (enmCommand == USAGE_DISCARDSTATE || enmCommand == USAGE_S_ALL)
659 RTStrmPrintf(pStrm,
660 "%s discardstate %s <uuid|vmname>\n"
661 "\n", SEP);
662
663 if (enmCommand == USAGE_ADOPTSTATE || enmCommand == USAGE_S_ALL)
664 RTStrmPrintf(pStrm,
665 "%s adoptstate %s <uuid|vmname> <state_file>\n"
666 "\n", SEP);
667
668 if (enmCommand == USAGE_CLOSEMEDIUM || enmCommand == USAGE_S_ALL)
669 RTStrmPrintf(pStrm,
670 "%s closemedium %s [disk|dvd|floppy] <uuid|filename>\n"
671 " [--delete]\n"
672 "\n", SEP);
673
674 if (enmCommand == USAGE_STORAGEATTACH || enmCommand == USAGE_S_ALL)
675 RTStrmPrintf(pStrm,
676 "%s storageattach %s <uuid|vmname>\n"
677 " --storagectl <name>\n"
678 " [--port <number>]\n"
679 " [--device <number>]\n"
680 " [--type dvddrive|hdd|fdd]\n"
681 " [--medium none|emptydrive|additions|\n"
682 " <uuid|filename>|host:<drive>|iscsi]\n"
683 " [--mtype normal|writethrough|immutable|shareable|\n"
684 " readonly|multiattach]\n"
685 " [--comment <text>]\n"
686 " [--setuuid <uuid>]\n"
687 " [--setparentuuid <uuid>]\n"
688 " [--passthrough on|off]\n"
689 " [--tempeject on|off]\n"
690 " [--nonrotational on|off]\n"
691 " [--discard on|off]\n"
692 " [--hotpluggable on|off]\n"
693 " [--bandwidthgroup <name>]\n"
694 " [--forceunmount]\n"
695 " [--server <name>|<ip>]\n"
696 " [--target <target>]\n"
697 " [--tport <port>]\n"
698 " [--lun <lun>]\n"
699 " [--encodedlun <lun>]\n"
700 " [--username <username>]\n"
701 " [--password <password>]\n"
702 " [--passwordfile <file>]\n"
703 " [--initiator <initiator>]\n"
704 " [--intnet]\n"
705 "\n", SEP);
706
707 if (enmCommand == USAGE_STORAGECONTROLLER || enmCommand == USAGE_S_ALL)
708 RTStrmPrintf(pStrm,
709 "%s storagectl %s <uuid|vmname>\n"
710 " --name <name>\n"
711 " [--add ide|sata|scsi|floppy|sas|usb|pcie|virtio]\n"
712 " [--controller LSILogic|LSILogicSAS|BusLogic|\n"
713 " IntelAHCI|PIIX3|PIIX4|ICH6|I82078|\n"
714 " [ USB|NVMe|VirtIO]\n"
715 " [--portcount <1-n>]\n"
716 " [--hostiocache on|off]\n"
717 " [--bootable on|off]\n"
718 " [--rename <name>]\n"
719 " [--remove]\n"
720 "\n", SEP);
721
722 if (enmCommand == USAGE_BANDWIDTHCONTROL || enmCommand == USAGE_S_ALL)
723 RTStrmPrintf(pStrm,
724 "%s bandwidthctl %s <uuid|vmname>\n"
725 " add <name> --type disk|network\n"
726 " --limit <megabytes per second>[k|m|g|K|M|G] |\n"
727 " set <name>\n"
728 " --limit <megabytes per second>[k|m|g|K|M|G] |\n"
729 " remove <name> |\n"
730 " list [--machinereadable]\n"
731 " (limit units: k=kilobit, m=megabit, g=gigabit,\n"
732 " K=kilobyte, M=megabyte, G=gigabyte)\n"
733 "\n", SEP);
734
735 if (enmCommand == USAGE_SHOWMEDIUMINFO || enmCommand == USAGE_S_ALL)
736 RTStrmPrintf(pStrm,
737 "%s showmediuminfo %s [disk|dvd|floppy] <uuid|filename>\n"
738 "\n", SEP);
739
740 if (enmCommand == USAGE_CREATEMEDIUM || enmCommand == USAGE_S_ALL)
741 RTStrmPrintf(pStrm,
742 "%s createmedium %s [disk|dvd|floppy] --filename <filename>\n"
743 " [--size <megabytes>|--sizebyte <bytes>]\n"
744 " [--diffparent <uuid>|<filename>]\n"
745 " [--format VDI|VMDK|VHD] (default: VDI)]\n"
746 " [--variant Standard,Fixed,Split2G,Stream,ESX,\n"
747 " Formatted,RawDisk]\n"
748 " [[--property <name>=<value>] --property <name>=<value>\n"
749 " --property-file <name>=</path/to/file/with/value>]...\n"
750 "\n", SEP);
751
752 if (enmCommand == USAGE_MODIFYMEDIUM || enmCommand == USAGE_S_ALL)
753 RTStrmPrintf(pStrm,
754 "%s modifymedium %s [disk|dvd|floppy] <uuid|filename>\n"
755 " [--type normal|writethrough|immutable|shareable|\n"
756 " readonly|multiattach]\n"
757 " [--autoreset on|off]\n"
758 " [--property <name=[value]>]\n"
759 " [--compact]\n"
760 " [--resize <megabytes>|--resizebyte <bytes>]\n"
761 " [--move <path>]\n"
762 " [--setlocation <path>]\n"
763 " [--description <description string>]"
764 "\n", SEP);
765
766 if (enmCommand == USAGE_CLONEMEDIUM || enmCommand == USAGE_S_ALL)
767 RTStrmPrintf(pStrm,
768 "%s clonemedium %s [disk|dvd|floppy] <uuid|inputfile> <uuid|outputfile>\n"
769 " [--format VDI|VMDK|VHD|RAW|<other>]\n"
770 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
771 " [--existing]\n"
772 "\n", SEP);
773
774 if (enmCommand == USAGE_MEDIUMPROPERTY || enmCommand == USAGE_S_ALL)
775 RTStrmPrintf(pStrm,
776 "%s mediumproperty %s [disk|dvd|floppy] set <uuid|filename>\n"
777 " <property> <value>\n"
778 "\n"
779 " [disk|dvd|floppy] get <uuid|filename>\n"
780 " <property>\n"
781 "\n"
782 " [disk|dvd|floppy] delete <uuid|filename>\n"
783 " <property>\n"
784 "\n", SEP);
785
786 if (enmCommand == USAGE_ENCRYPTMEDIUM || enmCommand == USAGE_S_ALL)
787 RTStrmPrintf(pStrm,
788 "%s encryptmedium %s <uuid|filename>\n"
789 " [--newpassword <file>|-]\n"
790 " [--oldpassword <file>|-]\n"
791 " [--cipher <cipher identifier>]\n"
792 " [--newpasswordid <password identifier>]\n"
793 "\n", SEP);
794
795 if (enmCommand == USAGE_MEDIUMENCCHKPWD || enmCommand == USAGE_S_ALL)
796 RTStrmPrintf(pStrm,
797 "%s checkmediumpwd %s <uuid|filename>\n"
798 " <pwd file>|-\n"
799 "\n", SEP);
800
801 if (enmCommand == USAGE_CONVERTFROMRAW || enmCommand == USAGE_S_ALL)
802 RTStrmPrintf(pStrm,
803 "%s convertfromraw %s <filename> <outputfile>\n"
804 " [--format VDI|VMDK|VHD]\n"
805 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
806 " [--uuid <uuid>]\n"
807 "%s convertfromraw %s stdin <outputfile> <bytes>\n"
808 " [--format VDI|VMDK|VHD]\n"
809 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
810 " [--uuid <uuid>]\n"
811 "\n", SEP, SEP);
812
813 if (enmCommand == USAGE_GETEXTRADATA || enmCommand == USAGE_S_ALL)
814 RTStrmPrintf(pStrm,
815 "%s getextradata %s global|<uuid|vmname>\n"
816 " <key>|[enumerate]\n"
817 "\n", SEP);
818
819 if (enmCommand == USAGE_SETEXTRADATA || enmCommand == USAGE_S_ALL)
820 RTStrmPrintf(pStrm,
821 "%s setextradata %s global|<uuid|vmname>\n"
822 " <key>\n"
823 " [<value>] (no value deletes key)\n"
824 "\n", SEP);
825
826 if (enmCommand == USAGE_SETPROPERTY || enmCommand == USAGE_S_ALL)
827 RTStrmPrintf(pStrm,
828 "%s setproperty %s machinefolder default|<folder> |\n"
829 " hwvirtexclusive on|off |\n"
830 " vrdeauthlibrary default|<library> |\n"
831 " websrvauthlibrary default|null|<library> |\n"
832 " vrdeextpack null|<library> |\n"
833 " autostartdbpath null|<folder> |\n"
834 " loghistorycount <value>\n"
835 " defaultfrontend default|<name>\n"
836 " logginglevel <log setting>\n"
837 " proxymode system|noproxy|manual\n"
838 " proxyurl <url>\n", SEP);
839#ifdef VBOX_WITH_MAIN_NLS
840 RTStrmPrintf(pStrm,
841 " language <language id>\n");
842#endif
843 RTStrmPrintf(pStrm,
844 "\n");
845
846 if (enmCommand == USAGE_USBFILTER || enmCommand == USAGE_S_ALL)
847 {
848 if (fSubcommandScope & HELP_SCOPE_USBFILTER_ADD)
849 RTStrmPrintf(pStrm,
850 "%s usbfilter %s add <index,0-N>\n"
851 " --target <uuid|vmname>|global\n"
852 " --name <string>\n"
853 " --action ignore|hold (global filters only)\n"
854 " [--active yes|no] (yes)\n"
855 " [--vendorid <XXXX>] (null)\n"
856 " [--productid <XXXX>] (null)\n"
857 " [--revision <IIFF>] (null)\n"
858 " [--manufacturer <string>] (null)\n"
859 " [--product <string>] (null)\n"
860 " [--remote yes|no] (null, VM filters only)\n"
861 " [--serialnumber <string>] (null)\n"
862 " [--maskedinterfaces <XXXXXXXX>]\n"
863 "\n", SEP);
864
865 if (fSubcommandScope & HELP_SCOPE_USBFILTER_MODIFY)
866 RTStrmPrintf(pStrm,
867 "%s usbfilter %s modify <index,0-N>\n"
868 " --target <uuid|vmname>|global\n"
869 " [--name <string>]\n"
870 " [--action ignore|hold] (global filters only)\n"
871 " [--active yes|no]\n"
872 " [--vendorid <XXXX>|\"\"]\n"
873 " [--productid <XXXX>|\"\"]\n"
874 " [--revision <IIFF>|\"\"]\n"
875 " [--manufacturer <string>|\"\"]\n"
876 " [--product <string>|\"\"]\n"
877 " [--remote yes|no] (null, VM filters only)\n"
878 " [--serialnumber <string>|\"\"]\n"
879 " [--maskedinterfaces <XXXXXXXX>]\n"
880 "\n", SEP);
881
882 if (fSubcommandScope & HELP_SCOPE_USBFILTER_REMOVE)
883 RTStrmPrintf(pStrm,
884 "%s usbfilter %s remove <index,0-N>\n"
885 " --target <uuid|vmname>|global\n"
886 "\n", SEP);
887 }
888
889#ifdef VBOX_WITH_GUEST_PROPS
890 if (enmCommand == USAGE_GUESTPROPERTY || enmCommand == USAGE_S_ALL)
891 usageGuestProperty(pStrm, SEP);
892#endif /* VBOX_WITH_GUEST_PROPS defined */
893
894#ifdef VBOX_WITH_GUEST_CONTROL
895 if (enmCommand == USAGE_GUESTCONTROL || enmCommand == USAGE_S_ALL)
896 usageGuestControl(pStrm, SEP, fSubcommandScope);
897#endif /* VBOX_WITH_GUEST_CONTROL defined */
898
899 if (enmCommand == USAGE_METRICS || enmCommand == USAGE_S_ALL)
900 RTStrmPrintf(pStrm,
901 "%s metrics %s list [*|host|<vmname> [<metric_list>]]\n"
902 " (comma-separated)\n\n"
903 "%s metrics %s setup\n"
904 " [--period <seconds>] (default: 1)\n"
905 " [--samples <count>] (default: 1)\n"
906 " [--list]\n"
907 " [*|host|<vmname> [<metric_list>]]\n\n"
908 "%s metrics %s query [*|host|<vmname> [<metric_list>]]\n\n"
909 "%s metrics %s enable\n"
910 " [--list]\n"
911 " [*|host|<vmname> [<metric_list>]]\n\n"
912 "%s metrics %s disable\n"
913 " [--list]\n"
914 " [*|host|<vmname> [<metric_list>]]\n\n"
915 "%s metrics %s collect\n"
916 " [--period <seconds>] (default: 1)\n"
917 " [--samples <count>] (default: 1)\n"
918 " [--list]\n"
919 " [--detach]\n"
920 " [*|host|<vmname> [<metric_list>]]\n"
921 "\n", SEP, SEP, SEP, SEP, SEP, SEP);
922
923#if defined(VBOX_WITH_NAT_SERVICE)
924 if (enmCommand == USAGE_NATNETWORK || enmCommand == USAGE_S_ALL)
925 {
926 RTStrmPrintf(pStrm,
927 "%s natnetwork %s add --netname <name>\n"
928 " --network <network>\n"
929 " [--enable|--disable]\n"
930 " [--dhcp on|off]\n"
931 " [--port-forward-4 <rule>]\n"
932 " [--loopback-4 <rule>]\n"
933 " [--ipv6 on|off]\n"
934 " [--port-forward-6 <rule>]\n"
935 " [--loopback-6 <rule>]\n\n"
936 "%s natnetwork %s remove --netname <name>\n\n"
937 "%s natnetwork %s modify --netname <name>\n"
938 " [--network <network>]\n"
939 " [--enable|--disable]\n"
940 " [--dhcp on|off]\n"
941 " [--port-forward-4 <rule>]\n"
942 " [--loopback-4 <rule>]\n"
943 " [--ipv6 on|off]\n"
944 " [--port-forward-6 <rule>]\n"
945 " [--loopback-6 <rule>]\n\n"
946 "%s natnetwork %s start --netname <name>\n\n"
947 "%s natnetwork %s stop --netname <name>\n\n"
948 "%s natnetwork %s list [<pattern>]\n"
949 "\n", SEP, SEP, SEP, SEP, SEP, SEP);
950
951
952 }
953#endif
954
955#if defined(VBOX_WITH_NETFLT)
956 if (enmCommand == USAGE_HOSTONLYIFS || enmCommand == USAGE_S_ALL)
957 {
958 RTStrmPrintf(pStrm,
959 "%s hostonlyif %s ipconfig <name>\n"
960 " [--dhcp |\n"
961 " --ip <ipv4> [--netmask <ipv4> (def:255.255.255.0)]|\n"
962 " --ipv6 <ipv6> [--netmasklengthv6 <N> (def:64)]]", SEP);
963# if !defined(RT_OS_SOLARIS) || defined(VBOX_ONLY_DOCS)
964 RTStrmPrintf(pStrm,
965 " |\n"
966 " create |\n"
967 " remove <name>\n");
968# else
969 RTStrmPrintf(pStrm,
970 "\n");
971# endif
972 RTStrmPrintf(pStrm,
973 "\n");
974 }
975#endif
976
977 if (enmCommand == USAGE_USBDEVSOURCE || enmCommand == USAGE_S_ALL)
978 {
979 RTStrmPrintf(pStrm,
980 "%s usbdevsource %s add <source name>\n"
981 " --backend <backend>\n"
982 " --address <address>\n"
983 "%s usbdevsource %s remove <source name>\n"
984 "\n", SEP, SEP);
985 }
986
987#ifndef VBOX_ONLY_DOCS /* Converted to man page, not needed. */
988 if (enmCommand == USAGE_S_ALL)
989 {
990 uint32_t cPendingBlankLines = 0;
991 for (uint32_t i = 0; i < g_cHelpEntries; i++)
992 {
993 PCRTMSGREFENTRY pHelp = g_apHelpEntries[i];
994 while (cPendingBlankLines-- > 0)
995 RTStrmPutCh(pStrm, '\n');
996 RTStrmPrintf(pStrm, " %c%s:\n", RT_C_TO_UPPER(pHelp->pszBrief[0]), pHelp->pszBrief + 1);
997 cPendingBlankLines = 0;
998 RTMsgRefEntryPrintStringTable(pStrm, &pHelp->Synopsis, RTMSGREFENTRYSTR_SCOPE_GLOBAL,
999 &cPendingBlankLines, NULL /*pcLinesWritten*/);
1000 cPendingBlankLines = RT_MAX(cPendingBlankLines, 1);
1001 }
1002 }
1003#endif
1004}
1005
1006/**
1007 * Print a usage synopsis and the syntax error message.
1008 * @returns RTEXITCODE_SYNTAX.
1009 */
1010RTEXITCODE errorSyntax(USAGECATEGORY enmCommand, const char *pszFormat, ...)
1011{
1012 va_list args;
1013 showLogo(g_pStdErr); // show logo even if suppressed
1014#ifndef VBOX_ONLY_DOCS
1015 if (g_fInternalMode)
1016 printUsageInternal(enmCommand, g_pStdErr);
1017 else if (g_enmCurCommand == HELP_CMD_VBOXMANAGE_INVALID)
1018 printUsage(enmCommand, RTMSGREFENTRYSTR_SCOPE_GLOBAL, g_pStdErr);
1019 else
1020 printUsage(g_pStdErr);
1021#else
1022 RT_NOREF_PV(enmCommand);
1023#endif
1024 va_start(args, pszFormat);
1025 RTStrmPrintf(g_pStdErr, Help::tr("\nSyntax error: %N\n"), pszFormat, &args);
1026 va_end(args);
1027 return RTEXITCODE_SYNTAX;
1028}
1029
1030/**
1031 * Print a usage synopsis and the syntax error message.
1032 * @returns RTEXITCODE_SYNTAX.
1033 */
1034RTEXITCODE errorSyntaxEx(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, const char *pszFormat, ...)
1035{
1036 va_list args;
1037 showLogo(g_pStdErr); // show logo even if suppressed
1038#ifndef VBOX_ONLY_DOCS
1039 if (g_fInternalMode)
1040 printUsageInternal(enmCommand, g_pStdErr);
1041 else if (g_enmCurCommand == HELP_CMD_VBOXMANAGE_INVALID)
1042 printUsage(enmCommand, fSubcommandScope, g_pStdErr);
1043 else
1044 printUsage(g_pStdErr);
1045#else
1046 RT_NOREF2(enmCommand, fSubcommandScope);
1047#endif
1048 va_start(args, pszFormat);
1049 RTStrmPrintf(g_pStdErr, Help::tr("\nSyntax error: %N\n"), pszFormat, &args);
1050 va_end(args);
1051 return RTEXITCODE_SYNTAX;
1052}
1053
1054/**
1055 * errorSyntax for RTGetOpt users.
1056 *
1057 * @returns RTEXITCODE_SYNTAX.
1058 *
1059 * @param enmCommand The command.
1060 * @param fSubcommandScope The subcommand scope, REFENTRYSTR_SCOPE_GLOBAL
1061 * for all.
1062 * @param rc The RTGetOpt return code.
1063 * @param pValueUnion The value union.
1064 */
1065RTEXITCODE errorGetOptEx(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, int rc, union RTGETOPTUNION const *pValueUnion)
1066{
1067 /*
1068 * Check if it is an unhandled standard option.
1069 */
1070#ifndef VBOX_ONLY_DOCS
1071 if (rc == 'V')
1072 {
1073 RTPrintf("%sr%d\n", VBOX_VERSION_STRING, RTBldCfgRevision());
1074 return RTEXITCODE_SUCCESS;
1075 }
1076#endif
1077
1078 if (rc == 'h')
1079 {
1080 showLogo(g_pStdErr);
1081#ifndef VBOX_ONLY_DOCS
1082 if (g_fInternalMode)
1083 printUsageInternal(enmCommand, g_pStdOut);
1084 else if (g_enmCurCommand == HELP_CMD_VBOXMANAGE_INVALID)
1085 printUsage(enmCommand, fSubcommandScope, g_pStdOut);
1086 else
1087 printUsage(g_pStdErr);
1088#endif
1089 return RTEXITCODE_SUCCESS;
1090 }
1091
1092 /*
1093 * General failure.
1094 */
1095 showLogo(g_pStdErr); // show logo even if suppressed
1096#ifndef VBOX_ONLY_DOCS
1097 if (g_fInternalMode)
1098 printUsageInternal(enmCommand, g_pStdErr);
1099 else if (g_enmCurCommand == HELP_CMD_VBOXMANAGE_INVALID)
1100 printUsage(enmCommand, fSubcommandScope, g_pStdErr);
1101 else
1102 printUsage(g_pStdErr);
1103#else
1104 RT_NOREF2(enmCommand, fSubcommandScope);
1105#endif
1106
1107 if (rc == VINF_GETOPT_NOT_OPTION)
1108 return RTMsgErrorExit(RTEXITCODE_SYNTAX, Help::tr("Invalid parameter '%s'"), pValueUnion->psz);
1109 if (rc > 0)
1110 {
1111 if (RT_C_IS_PRINT(rc))
1112 return RTMsgErrorExit(RTEXITCODE_SYNTAX, Help::tr("Invalid option -%c"), rc);
1113 return RTMsgErrorExit(RTEXITCODE_SYNTAX, Help::tr("Invalid option case %i"), rc);
1114 }
1115 if (rc == VERR_GETOPT_UNKNOWN_OPTION)
1116 return RTMsgErrorExit(RTEXITCODE_SYNTAX, Help::tr("Unknown option: %s"), pValueUnion->psz);
1117 if (rc == VERR_GETOPT_INVALID_ARGUMENT_FORMAT)
1118 return RTMsgErrorExit(RTEXITCODE_SYNTAX, Help::tr("Invalid argument format: %s"), pValueUnion->psz);
1119 if (pValueUnion->pDef)
1120 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "%s: %Rrs", pValueUnion->pDef->pszLong, rc);
1121 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "%Rrs", rc);
1122}
1123
1124
1125/**
1126 * errorSyntax for RTGetOpt users.
1127 *
1128 * @returns RTEXITCODE_SYNTAX.
1129 *
1130 * @param enmCommand The command.
1131 * @param rc The RTGetOpt return code.
1132 * @param pValueUnion The value union.
1133 */
1134RTEXITCODE errorGetOpt(USAGECATEGORY enmCommand, int rc, union RTGETOPTUNION const *pValueUnion)
1135{
1136 return errorGetOptEx(enmCommand, RTMSGREFENTRYSTR_SCOPE_GLOBAL, rc, pValueUnion);
1137}
1138
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