VirtualBox

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

Last change on this file since 77606 was 77606, checked in by vboxsync, 5 years ago

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use