VirtualBox

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

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

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

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