VirtualBox

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

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

Main/Appliance: Teach importing new tricks: importing to specific location (by settings file name or base folder) and also importing straight into a group. Lots of cleanup and minor fixing (bad code quality due to lots of copy/paste, and what's worse is that the original code was broken already, using the variables inconsistently), plus some smallish coding style cleaup. Much more needed. Also fixed the incomplete use of the VM name on expert (the one in the VBox XML was not changed, and it's the preferred name on import).
VBoxManage: small updates to reflect the new features (and actually offer setting the VM name on export, which is something the GUI could do for a long time).
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 64.3 KB
Line 
1/* $Id: VBoxManageHelp.cpp 72476 2018-06-07 13:49:48Z 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.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/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\n"
452 "\n", SEP);
453
454 if (fCategory & USAGE_SHOWVMINFO)
455 RTStrmPrintf(pStrm,
456 "%s showvminfo %s <uuid|vmname> [--details]\n"
457 " [--machinereadable]\n"
458 "%s showvminfo %s <uuid|vmname> --log <idx>\n"
459 "\n", SEP, SEP);
460
461 if (fCategory & USAGE_REGISTERVM)
462 RTStrmPrintf(pStrm,
463 "%s registervm %s <filename>\n"
464 "\n", SEP);
465
466 if (fCategory & USAGE_UNREGISTERVM)
467 RTStrmPrintf(pStrm,
468 "%s unregistervm %s <uuid|vmname> [--delete]\n"
469 "\n", SEP);
470
471 if (fCategory & USAGE_CREATEVM)
472 RTStrmPrintf(pStrm,
473 "%s createvm %s --name <name>\n"
474 " [--groups <group>, ...]\n"
475 " [--ostype <ostype>]\n"
476 " [--register]\n"
477 " [--basefolder <path>]\n"
478 " [--uuid <uuid>]\n"
479 "\n", SEP);
480
481 if (fCategory & USAGE_MODIFYVM)
482 {
483 RTStrmPrintf(pStrm,
484 "%s modifyvm %s <uuid|vmname>\n"
485 " [--name <name>]\n"
486 " [--groups <group>, ...]\n"
487 " [--description <desc>]\n"
488 " [--ostype <ostype>]\n"
489 " [--iconfile <filename>]\n"
490 " [--memory <memorysize in MB>]\n"
491 " [--pagefusion on|off]\n"
492 " [--vram <vramsize in MB>]\n"
493 " [--acpi on|off]\n"
494#ifdef VBOX_WITH_PCI_PASSTHROUGH
495 " [--pciattach 03:04.0]\n"
496 " [--pciattach 03:04.0@02:01.0]\n"
497 " [--pcidetach 03:04.0]\n"
498#endif
499 " [--ioapic on|off]\n"
500 " [--hpet on|off]\n"
501 " [--triplefaultreset on|off]\n"
502 " [--apic on|off]\n"
503 " [--x2apic on|off]\n"
504 " [--paravirtprovider none|default|legacy|minimal|\n"
505 " hyperv|kvm]\n"
506 " [--paravirtdebug <key=value> [,<key=value> ...]]\n"
507 " [--hwvirtex on|off]\n"
508 " [--nestedpaging on|off]\n"
509 " [--largepages on|off]\n"
510 " [--vtxvpid on|off]\n"
511 " [--vtxux on|off]\n"
512 " [--pae on|off]\n"
513 " [--longmode on|off]\n"
514 " [--ibpb-on-vm-exit on|off]\n"
515 " [--ibpb-on-vm-entry on|off]\n"
516 " [--spec-ctrl on|off]\n"
517 " [--nested-hw-virt on|off]\n"
518 " [--cpu-profile \"host|Intel 80[86|286|386]\"]\n"
519 " [--cpuid-portability-level <0..3>\n"
520 " [--cpuid-set <leaf[:subleaf]> <eax> <ebx> <ecx> <edx>]\n"
521 " [--cpuid-remove <leaf[:subleaf]>]\n"
522 " [--cpuidremoveall]\n"
523 " [--hardwareuuid <uuid>]\n"
524 " [--cpus <number>]\n"
525 " [--cpuhotplug on|off]\n"
526 " [--plugcpu <id>]\n"
527 " [--unplugcpu <id>]\n"
528 " [--cpuexecutioncap <1-100>]\n"
529 " [--rtcuseutc on|off]\n"
530#ifdef VBOX_WITH_VMSVGA
531 " [--graphicscontroller none|vboxvga|vmsvga]\n"
532#else
533 " [--graphicscontroller none|vboxvga]\n"
534#endif
535 " [--monitorcount <number>]\n"
536 " [--accelerate3d on|off]\n"
537#ifdef VBOX_WITH_VIDEOHWACCEL
538 " [--accelerate2dvideo on|off]\n"
539#endif
540 " [--firmware bios|efi|efi32|efi64]\n"
541 " [--chipset ich9|piix3]\n"
542 " [--bioslogofadein on|off]\n"
543 " [--bioslogofadeout on|off]\n"
544 " [--bioslogodisplaytime <msec>]\n"
545 " [--bioslogoimagepath <imagepath>]\n"
546 " [--biosbootmenu disabled|menuonly|messageandmenu]\n"
547 " [--biosapic disabled|apic|x2apic]\n"
548 " [--biossystemtimeoffset <msec>]\n"
549 " [--biospxedebug on|off]\n"
550 " [--boot<1-4> none|floppy|dvd|disk|net>]\n"
551 " [--nic<1-N> none|null|nat|bridged|intnet"
552#if defined(VBOX_WITH_NETFLT)
553 "|hostonly"
554#endif
555 "|\n"
556 " generic|natnetwork"
557 "]\n"
558 " [--nictype<1-N> Am79C970A|Am79C973"
559#ifdef VBOX_WITH_E1000
560 "|\n 82540EM|82543GC|82545EM"
561#endif
562#ifdef VBOX_WITH_VIRTIO
563 "|\n virtio"
564#endif /* VBOX_WITH_VIRTIO */
565 "]\n"
566 " [--cableconnected<1-N> on|off]\n"
567 " [--nictrace<1-N> on|off]\n"
568 " [--nictracefile<1-N> <filename>]\n"
569 " [--nicproperty<1-N> name=[value]]\n"
570 " [--nicspeed<1-N> <kbps>]\n"
571 " [--nicbootprio<1-N> <priority>]\n"
572 " [--nicpromisc<1-N> deny|allow-vms|allow-all]\n"
573 " [--nicbandwidthgroup<1-N> none|<name>]\n"
574 " [--bridgeadapter<1-N> none|<devicename>]\n"
575#if defined(VBOX_WITH_NETFLT)
576 " [--hostonlyadapter<1-N> none|<devicename>]\n"
577#endif
578 " [--intnet<1-N> <network name>]\n"
579 " [--nat-network<1-N> <network name>]\n"
580 " [--nicgenericdrv<1-N> <driver>\n"
581 " [--natnet<1-N> <network>|default]\n"
582 " [--natsettings<1-N> [<mtu>],[<socksnd>],\n"
583 " [<sockrcv>],[<tcpsnd>],\n"
584 " [<tcprcv>]]\n"
585 " [--natpf<1-N> [<rulename>],tcp|udp,[<hostip>],\n"
586 " <hostport>,[<guestip>],<guestport>]\n"
587 " [--natpf<1-N> delete <rulename>]\n"
588 " [--nattftpprefix<1-N> <prefix>]\n"
589 " [--nattftpfile<1-N> <file>]\n"
590 " [--nattftpserver<1-N> <ip>]\n"
591 " [--natbindip<1-N> <ip>\n"
592 " [--natdnspassdomain<1-N> on|off]\n"
593 " [--natdnsproxy<1-N> on|off]\n"
594 " [--natdnshostresolver<1-N> on|off]\n"
595 " [--nataliasmode<1-N> default|[log],[proxyonly],\n"
596 " [sameports]]\n"
597 " [--macaddress<1-N> auto|<mac>]\n"
598 " [--mouse ps2|usb|usbtablet|usbmultitouch]\n"
599 " [--keyboard ps2|usb\n"
600 " [--uart<1-N> off|<I/O base> <IRQ>]\n"
601 " [--uartmode<1-N> disconnected|\n"
602 " server <pipe>|\n"
603 " client <pipe>|\n"
604 " tcpserver <port>|\n"
605 " tcpclient <hostname:port>|\n"
606 " file <file>|\n"
607 " <devicename>]\n"
608#if defined(RT_OS_LINUX) || defined(RT_OS_WINDOWS)
609 " [--lpt<1-N> off|<I/O base> <IRQ>]\n"
610 " [--lptmode<1-N> <devicename>]\n"
611#endif
612 " [--guestmemoryballoon <balloonsize in MB>]\n"
613 " [--audio none|null", SEP);
614 if (fWin)
615 {
616#ifdef VBOX_WITH_WINMM
617 RTStrmPrintf(pStrm, "|winmm|dsound");
618#else
619 RTStrmPrintf(pStrm, "|dsound");
620#endif
621 }
622 if (fLinux || fSolaris)
623 {
624 RTStrmPrintf(pStrm, ""
625#ifdef VBOX_WITH_AUDIO_OSS
626 "|oss"
627#endif
628#ifdef VBOX_WITH_AUDIO_ALSA
629 "|alsa"
630#endif
631#ifdef VBOX_WITH_AUDIO_PULSE
632 "|pulse"
633#endif
634 );
635 }
636 if (fFreeBSD)
637 {
638#ifdef VBOX_WITH_AUDIO_OSS
639 /* Get the line break sorted when dumping all option variants. */
640 if (fDumpOpts)
641 {
642 RTStrmPrintf(pStrm, "|\n"
643 " oss");
644 }
645 else
646 RTStrmPrintf(pStrm, "|oss");
647#endif
648#ifdef VBOX_WITH_AUDIO_PULSE
649 RTStrmPrintf(pStrm, "|pulse");
650#endif
651 }
652 if (fDarwin)
653 {
654 RTStrmPrintf(pStrm, "|coreaudio");
655 }
656 RTStrmPrintf(pStrm, "]\n");
657 RTStrmPrintf(pStrm,
658 " [--audioin on|off]\n"
659 " [--audioout on|off]\n"
660 " [--audiocontroller ac97|hda|sb16]\n"
661 " [--audiocodec stac9700|ad1980|stac9221|sb16]\n"
662 " [--clipboard disabled|hosttoguest|guesttohost|\n"
663 " bidirectional]\n"
664 " [--draganddrop disabled|hosttoguest]\n");
665 RTStrmPrintf(pStrm,
666 " [--vrde on|off]\n"
667 " [--vrdeextpack default|<name>\n"
668 " [--vrdeproperty <name=[value]>]\n"
669 " [--vrdeport <hostport>]\n"
670 " [--vrdeaddress <hostip>]\n"
671 " [--vrdeauthtype null|external|guest]\n"
672 " [--vrdeauthlibrary default|<name>\n"
673 " [--vrdemulticon on|off]\n"
674 " [--vrdereusecon on|off]\n"
675 " [--vrdevideochannel on|off]\n"
676 " [--vrdevideochannelquality <percent>]\n");
677 RTStrmPrintf(pStrm,
678 " [--usbohci on|off]\n"
679 " [--usbehci on|off]\n"
680 " [--usbxhci on|off]\n"
681 " [--usbrename <oldname> <newname>]\n"
682 " [--snapshotfolder default|<path>]\n"
683 " [--teleporter on|off]\n"
684 " [--teleporterport <port>]\n"
685 " [--teleporteraddress <address|empty>\n"
686 " [--teleporterpassword <password>]\n"
687 " [--teleporterpasswordfile <file>|stdin]\n"
688 " [--tracing-enabled on|off]\n"
689 " [--tracing-config <config-string>]\n"
690 " [--tracing-allow-vm-access on|off]\n"
691#if 0
692 " [--iocache on|off]\n"
693 " [--iocachesize <I/O cache size in MB>]\n"
694#endif
695#if 0
696 " [--faulttolerance master|standby]\n"
697 " [--faulttoleranceaddress <name>]\n"
698 " [--faulttoleranceport <port>]\n"
699 " [--faulttolerancesyncinterval <msec>]\n"
700 " [--faulttolerancepassword <password>]\n"
701#endif
702#ifdef VBOX_WITH_USB_CARDREADER
703 " [--usbcardreader on|off]\n"
704#endif
705 " [--autostart-enabled on|off]\n"
706 " [--autostart-delay <seconds>]\n"
707#if 0
708 " [--autostop-type disabled|savestate|poweroff|\n"
709 " acpishutdown]\n"
710#endif
711#ifdef VBOX_WITH_VIDEOREC
712 " [--videocap on|off]\n"
713 " [--videocapscreens all|<screen ID> [<screen ID> ...]]\n"
714 " [--videocapfile <filename>]\n"
715 " [--videocapres <width> <height>]\n"
716 " [--videocaprate <rate>]\n"
717 " [--videocapfps <fps>]\n"
718 " [--videocapmaxtime <ms>]\n"
719 " [--videocapmaxsize <MB>]\n"
720 " [--videocapopts <key=value> [,<key=value> ...]]\n"
721#endif
722 " [--defaultfrontend default|<name>]\n"
723 "\n");
724 }
725
726 if (fCategory & USAGE_CLONEVM)
727 RTStrmPrintf(pStrm,
728 "%s clonevm %s <uuid|vmname>\n"
729 " [--snapshot <uuid>|<name>]\n"
730 " [--mode machine|machineandchildren|all]\n"
731 " [--options link|keepallmacs|keepnatmacs|\n"
732 " keepdisknames]\n"
733 " [--name <name>]\n"
734 " [--groups <group>, ...]\n"
735 " [--basefolder <basefolder>]\n"
736 " [--uuid <uuid>]\n"
737 " [--register]\n"
738 "\n", SEP);
739
740 if (fCategory & USAGE_MOVEVM)
741 RTStrmPrintf(pStrm,
742 "%s movevm %s <uuid|vmname>\n"
743 " --type basic\n"
744 " [--folder <path>]\n"
745 "\n", SEP);
746
747 if (fCategory & USAGE_IMPORTAPPLIANCE)
748 RTStrmPrintf(pStrm,
749 "%s import %s <ovfname/ovaname>\n"
750 " [--dry-run|-n]\n"
751 " [--options keepallmacs|keepnatmacs|importtovdi]\n"
752 " [more options]\n"
753 " (run with -n to have options displayed\n"
754 " for a particular OVF)\n\n", SEP);
755
756 if (fCategory & USAGE_EXPORTAPPLIANCE)
757 RTStrmPrintf(pStrm,
758 "%s export %s <machines> --output|-o <name>.<ovf/ova/tar.gz>\n"
759 " [--legacy09|--ovf09|--ovf10|--ovf20|--opc10]\n"
760 " [--manifest]\n"
761 " [--iso]\n"
762 " [--options manifest|iso|nomacs|nomacsbutnat]\n"
763 " [--vsys <number of virtual system>]\n"
764 " [--vmname <name>]\n"
765 " [--product <product name>]\n"
766 " [--producturl <product url>]\n"
767 " [--vendor <vendor name>]\n"
768 " [--vendorurl <vendor url>]\n"
769 " [--version <version info>]\n"
770 " [--description <description info>]\n"
771 " [--eula <license text>]\n"
772 " [--eulafile <filename>]\n"
773 "\n", SEP);
774
775 if (fCategory & USAGE_STARTVM)
776 {
777 RTStrmPrintf(pStrm,
778 "%s startvm %s <uuid|vmname>...\n"
779 " [--type gui", SEP);
780 if (fVBoxSDL)
781 RTStrmPrintf(pStrm, "|sdl");
782 RTStrmPrintf(pStrm, "|headless|separate]\n");
783 RTStrmPrintf(pStrm,
784 " [-E|--putenv <NAME>[=<VALUE>]]\n"
785 "\n");
786 }
787
788 if (fCategory & USAGE_CONTROLVM)
789 {
790 RTStrmPrintf(pStrm,
791 "%s controlvm %s <uuid|vmname>\n"
792 " pause|resume|reset|poweroff|savestate|\n"
793 " acpipowerbutton|acpisleepbutton|\n"
794 " keyboardputscancode <hex> [<hex> ...]|\n"
795 " keyboardputstring <string1> [<string2> ...]|\n"
796 " keyboardputfile <filename>|\n"
797 " setlinkstate<1-N> on|off |\n"
798#if defined(VBOX_WITH_NETFLT)
799 " nic<1-N> null|nat|bridged|intnet|hostonly|generic|\n"
800 " natnetwork [<devicename>] |\n"
801#else /* !VBOX_WITH_NETFLT */
802 " nic<1-N> null|nat|bridged|intnet|generic|natnetwork\n"
803 " [<devicename>] |\n"
804#endif /* !VBOX_WITH_NETFLT */
805 " nictrace<1-N> on|off |\n"
806 " nictracefile<1-N> <filename> |\n"
807 " nicproperty<1-N> name=[value] |\n"
808 " nicpromisc<1-N> deny|allow-vms|allow-all |\n"
809 " natpf<1-N> [<rulename>],tcp|udp,[<hostip>],\n"
810 " <hostport>,[<guestip>],<guestport> |\n"
811 " natpf<1-N> delete <rulename> |\n"
812 " guestmemoryballoon <balloonsize in MB> |\n"
813 " usbattach <uuid>|<address>\n"
814 " [--capturefile <filename>] |\n"
815 " usbdetach <uuid>|<address> |\n"
816 " audioin on|off |\n"
817 " audioout on|off |\n"
818 " clipboard disabled|hosttoguest|guesttohost|\n"
819 " bidirectional |\n"
820 " draganddrop disabled|hosttoguest |\n"
821 " vrde on|off |\n"
822 " vrdeport <port> |\n"
823 " vrdeproperty <name=[value]> |\n"
824 " vrdevideochannelquality <percent> |\n"
825 " setvideomodehint <xres> <yres> <bpp>\n"
826 " [[<display>] [<enabled:yes|no> |\n"
827 " [<xorigin> <yorigin>]]] |\n"
828 " setscreenlayout <display> on|primary <xorigin> <yorigin> <xres> <yres> <bpp> | off\n"
829 " screenshotpng <file> [display] |\n"
830 " videocap on|off |\n"
831 " videocapscreens all|none|<screen>,[<screen>...] |\n"
832 " videocapfile <file>\n"
833 " videocapres <width>x<height>\n"
834 " videocaprate <rate>\n"
835 " videocapfps <fps>\n"
836 " videocapmaxtime <ms>\n"
837 " videocapmaxsize <MB>\n"
838 " setcredentials <username>\n"
839 " --passwordfile <file> | <password>\n"
840 " <domain>\n"
841 " [--allowlocallogon <yes|no>] |\n"
842 " teleport --host <name> --port <port>\n"
843 " [--maxdowntime <msec>]\n"
844 " [--passwordfile <file> |\n"
845 " --password <password>] |\n"
846 " plugcpu <id> |\n"
847 " unplugcpu <id> |\n"
848 " cpuexecutioncap <1-100>\n"
849 " webcam <attach [path [settings]]> | <detach [path]> | <list>\n"
850 " addencpassword <id>\n"
851 " <password file>|-\n"
852 " [--removeonsuspend <yes|no>]\n"
853 " removeencpassword <id>\n"
854 " removeallencpasswords\n"
855 " changeuartmode<1-N> disconnected|\n"
856 " server <pipe>|\n"
857 " client <pipe>|\n"
858 " tcpserver <port>|\n"
859 " tcpclient <hostname:port>|\n"
860 " file <file>|\n"
861 " <devicename>]\n"
862 "\n", SEP);
863 }
864
865 if (fCategory & USAGE_DISCARDSTATE)
866 RTStrmPrintf(pStrm,
867 "%s discardstate %s <uuid|vmname>\n"
868 "\n", SEP);
869
870 if (fCategory & USAGE_ADOPTSTATE)
871 RTStrmPrintf(pStrm,
872 "%s adoptstate %s <uuid|vmname> <state_file>\n"
873 "\n", SEP);
874
875 if (fCategory & USAGE_SNAPSHOT)
876 RTStrmPrintf(pStrm,
877 "%s snapshot %s <uuid|vmname>\n"
878 " take <name> [--description <desc>] [--live]\n"
879 " [--uniquename Number,Timestamp,Space,Force] |\n"
880 " delete <uuid|snapname> |\n"
881 " restore <uuid|snapname> |\n"
882 " restorecurrent |\n"
883 " edit <uuid|snapname>|--current\n"
884 " [--name <name>]\n"
885 " [--description <desc>] |\n"
886 " list [--details|--machinereadable] |\n"
887 " showvminfo <uuid|snapname>\n"
888 "\n", SEP);
889
890 if (fCategory & USAGE_CLOSEMEDIUM)
891 RTStrmPrintf(pStrm,
892 "%s closemedium %s [disk|dvd|floppy] <uuid|filename>\n"
893 " [--delete]\n"
894 "\n", SEP);
895
896 if (fCategory & USAGE_STORAGEATTACH)
897 RTStrmPrintf(pStrm,
898 "%s storageattach %s <uuid|vmname>\n"
899 " --storagectl <name>\n"
900 " [--port <number>]\n"
901 " [--device <number>]\n"
902 " [--type dvddrive|hdd|fdd]\n"
903 " [--medium none|emptydrive|additions|\n"
904 " <uuid|filename>|host:<drive>|iscsi]\n"
905 " [--mtype normal|writethrough|immutable|shareable|\n"
906 " readonly|multiattach]\n"
907 " [--comment <text>]\n"
908 " [--setuuid <uuid>]\n"
909 " [--setparentuuid <uuid>]\n"
910 " [--passthrough on|off]\n"
911 " [--tempeject on|off]\n"
912 " [--nonrotational on|off]\n"
913 " [--discard on|off]\n"
914 " [--hotpluggable on|off]\n"
915 " [--bandwidthgroup <name>]\n"
916 " [--forceunmount]\n"
917 " [--server <name>|<ip>]\n"
918 " [--target <target>]\n"
919 " [--tport <port>]\n"
920 " [--lun <lun>]\n"
921 " [--encodedlun <lun>]\n"
922 " [--username <username>]\n"
923 " [--password <password>]\n"
924 " [--passwordfile <file>]\n"
925 " [--initiator <initiator>]\n"
926 " [--intnet]\n"
927 "\n", SEP);
928
929 if (fCategory & USAGE_STORAGECONTROLLER)
930 RTStrmPrintf(pStrm,
931 "%s storagectl %s <uuid|vmname>\n"
932 " --name <name>\n"
933 " [--add ide|sata|scsi|floppy|sas|usb|pcie]\n"
934 " [--controller LSILogic|LSILogicSAS|BusLogic|\n"
935 " IntelAHCI|PIIX3|PIIX4|ICH6|I82078|\n"
936 " [ USB|NVMe]\n"
937 " [--portcount <1-n>]\n"
938 " [--hostiocache on|off]\n"
939 " [--bootable on|off]\n"
940 " [--rename <name>]\n"
941 " [--remove]\n"
942 "\n", SEP);
943
944 if (fCategory & USAGE_BANDWIDTHCONTROL)
945 RTStrmPrintf(pStrm,
946 "%s bandwidthctl %s <uuid|vmname>\n"
947 " add <name> --type disk|network\n"
948 " --limit <megabytes per second>[k|m|g|K|M|G] |\n"
949 " set <name>\n"
950 " --limit <megabytes per second>[k|m|g|K|M|G] |\n"
951 " remove <name> |\n"
952 " list [--machinereadable]\n"
953 " (limit units: k=kilobit, m=megabit, g=gigabit,\n"
954 " K=kilobyte, M=megabyte, G=gigabyte)\n"
955 "\n", SEP);
956
957 if (fCategory & USAGE_SHOWMEDIUMINFO)
958 RTStrmPrintf(pStrm,
959 "%s showmediuminfo %s [disk|dvd|floppy] <uuid|filename>\n"
960 "\n", SEP);
961
962 if (fCategory & USAGE_CREATEMEDIUM)
963 RTStrmPrintf(pStrm,
964 "%s createmedium %s [disk|dvd|floppy] --filename <filename>\n"
965 " [--size <megabytes>|--sizebyte <bytes>]\n"
966 " [--diffparent <uuid>|<filename>\n"
967 " [--format VDI|VMDK|VHD] (default: VDI)\n"
968 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
969 "\n", SEP);
970
971 if (fCategory & USAGE_MODIFYMEDIUM)
972 RTStrmPrintf(pStrm,
973 "%s modifymedium %s [disk|dvd|floppy] <uuid|filename>\n"
974 " [--type normal|writethrough|immutable|shareable|\n"
975 " readonly|multiattach]\n"
976 " [--autoreset on|off]\n"
977 " [--property <name=[value]>]\n"
978 " [--compact]\n"
979 " [--resize <megabytes>|--resizebyte <bytes>]\n"
980 " [--move <path]\n"
981 " [--description <description string>]"
982 "\n", SEP);
983
984 if (fCategory & USAGE_CLONEMEDIUM)
985 RTStrmPrintf(pStrm,
986 "%s clonemedium %s [disk|dvd|floppy] <uuid|inputfile> <uuid|outputfile>\n"
987 " [--format VDI|VMDK|VHD|RAW|<other>]\n"
988 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
989 " [--existing]\n"
990 "\n", SEP);
991
992 if (fCategory & USAGE_MEDIUMPROPERTY)
993 RTStrmPrintf(pStrm,
994 "%s mediumproperty %s [disk|dvd|floppy] set <uuid|filename>\n"
995 " <property> <value>\n"
996 "\n"
997 " [disk|dvd|floppy] get <uuid|filename>\n"
998 " <property>\n"
999 "\n"
1000 " [disk|dvd|floppy] delete <uuid|filename>\n"
1001 " <property>\n"
1002 "\n", SEP);
1003
1004 if (fCategory & USAGE_ENCRYPTMEDIUM)
1005 RTStrmPrintf(pStrm,
1006 "%s encryptmedium %s <uuid|filename>\n"
1007 " [--newpassword <file>|-]\n"
1008 " [--oldpassword <file>|-]\n"
1009 " [--cipher <cipher identifier>]\n"
1010 " [--newpasswordid <password identifier>]\n"
1011 "\n", SEP);
1012
1013 if (fCategory & USAGE_MEDIUMENCCHKPWD)
1014 RTStrmPrintf(pStrm,
1015 "%s checkmediumpwd %s <uuid|filename>\n"
1016 " <pwd file>|-\n"
1017 "\n", SEP);
1018
1019 if (fCategory & USAGE_CONVERTFROMRAW)
1020 RTStrmPrintf(pStrm,
1021 "%s convertfromraw %s <filename> <outputfile>\n"
1022 " [--format VDI|VMDK|VHD]\n"
1023 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
1024 " [--uuid <uuid>]\n"
1025 "%s convertfromraw %s stdin <outputfile> <bytes>\n"
1026 " [--format VDI|VMDK|VHD]\n"
1027 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
1028 " [--uuid <uuid>]\n"
1029 "\n", SEP, SEP);
1030
1031 if (fCategory & USAGE_GETEXTRADATA)
1032 RTStrmPrintf(pStrm,
1033 "%s getextradata %s global|<uuid|vmname>\n"
1034 " <key>|[enumerate]\n"
1035 "\n", SEP);
1036
1037 if (fCategory & USAGE_SETEXTRADATA)
1038 RTStrmPrintf(pStrm,
1039 "%s setextradata %s global|<uuid|vmname>\n"
1040 " <key>\n"
1041 " [<value>] (no value deletes key)\n"
1042 "\n", SEP);
1043
1044 if (fCategory & USAGE_SETPROPERTY)
1045 RTStrmPrintf(pStrm,
1046 "%s setproperty %s machinefolder default|<folder> |\n"
1047 " hwvirtexclusive on|off |\n"
1048 " vrdeauthlibrary default|<library> |\n"
1049 " websrvauthlibrary default|null|<library> |\n"
1050 " vrdeextpack null|<library> |\n"
1051 " autostartdbpath null|<folder> |\n"
1052 " loghistorycount <value>\n"
1053 " defaultfrontend default|<name>\n"
1054 " logginglevel <log setting>\n"
1055 "\n", SEP);
1056
1057 if (fCategory & USAGE_USBFILTER_ADD)
1058 RTStrmPrintf(pStrm,
1059 "%s usbfilter %s add <index,0-N>\n"
1060 " --target <uuid|vmname>|global\n"
1061 " --name <string>\n"
1062 " --action ignore|hold (global filters only)\n"
1063 " [--active yes|no] (yes)\n"
1064 " [--vendorid <XXXX>] (null)\n"
1065 " [--productid <XXXX>] (null)\n"
1066 " [--revision <IIFF>] (null)\n"
1067 " [--manufacturer <string>] (null)\n"
1068 " [--product <string>] (null)\n"
1069 " [--remote yes|no] (null, VM filters only)\n"
1070 " [--serialnumber <string>] (null)\n"
1071 " [--maskedinterfaces <XXXXXXXX>]\n"
1072 "\n", SEP);
1073
1074 if (fCategory & USAGE_USBFILTER_MODIFY)
1075 RTStrmPrintf(pStrm,
1076 "%s usbfilter %s modify <index,0-N>\n"
1077 " --target <uuid|vmname>|global\n"
1078 " [--name <string>]\n"
1079 " [--action ignore|hold] (global filters only)\n"
1080 " [--active yes|no]\n"
1081 " [--vendorid <XXXX>|\"\"]\n"
1082 " [--productid <XXXX>|\"\"]\n"
1083 " [--revision <IIFF>|\"\"]\n"
1084 " [--manufacturer <string>|\"\"]\n"
1085 " [--product <string>|\"\"]\n"
1086 " [--remote yes|no] (null, VM filters only)\n"
1087 " [--serialnumber <string>|\"\"]\n"
1088 " [--maskedinterfaces <XXXXXXXX>]\n"
1089 "\n", SEP);
1090
1091 if (fCategory & USAGE_USBFILTER_REMOVE)
1092 RTStrmPrintf(pStrm,
1093 "%s usbfilter %s remove <index,0-N>\n"
1094 " --target <uuid|vmname>|global\n"
1095 "\n", SEP);
1096
1097 if (fCategory & USAGE_SHAREDFOLDER_ADD)
1098 RTStrmPrintf(pStrm,
1099 "%s sharedfolder %s add <uuid|vmname>\n"
1100 " --name <name> --hostpath <hostpath>\n"
1101 " [--transient] [--readonly] [--automount]\n"
1102 "\n", SEP);
1103
1104 if (fCategory & USAGE_SHAREDFOLDER_REMOVE)
1105 RTStrmPrintf(pStrm,
1106 "%s sharedfolder %s remove <uuid|vmname>\n"
1107 " --name <name> [--transient]\n"
1108 "\n", SEP);
1109
1110#ifdef VBOX_WITH_GUEST_PROPS
1111 if (fCategory & USAGE_GUESTPROPERTY)
1112 usageGuestProperty(pStrm, SEP);
1113#endif /* VBOX_WITH_GUEST_PROPS defined */
1114
1115#ifdef VBOX_WITH_GUEST_CONTROL
1116 if (fCategory & USAGE_GUESTCONTROL)
1117 usageGuestControl(pStrm, SEP, fSubCategory);
1118#endif /* VBOX_WITH_GUEST_CONTROL defined */
1119
1120 if (fCategory & USAGE_METRICS)
1121 RTStrmPrintf(pStrm,
1122 "%s metrics %s list [*|host|<vmname> [<metric_list>]]\n"
1123 " (comma-separated)\n\n"
1124 "%s metrics %s setup\n"
1125 " [--period <seconds>] (default: 1)\n"
1126 " [--samples <count>] (default: 1)\n"
1127 " [--list]\n"
1128 " [*|host|<vmname> [<metric_list>]]\n\n"
1129 "%s metrics %s query [*|host|<vmname> [<metric_list>]]\n\n"
1130 "%s metrics %s enable\n"
1131 " [--list]\n"
1132 " [*|host|<vmname> [<metric_list>]]\n\n"
1133 "%s metrics %s disable\n"
1134 " [--list]\n"
1135 " [*|host|<vmname> [<metric_list>]]\n\n"
1136 "%s metrics %s collect\n"
1137 " [--period <seconds>] (default: 1)\n"
1138 " [--samples <count>] (default: 1)\n"
1139 " [--list]\n"
1140 " [--detach]\n"
1141 " [*|host|<vmname> [<metric_list>]]\n"
1142 "\n", SEP, SEP, SEP, SEP, SEP, SEP);
1143
1144#if defined(VBOX_WITH_NAT_SERVICE)
1145 if (fCategory & USAGE_NATNETWORK)
1146 {
1147 RTStrmPrintf(pStrm,
1148 "%s natnetwork %s add --netname <name>\n"
1149 " --network <network>\n"
1150 " [--enable|--disable]\n"
1151 " [--dhcp on|off]\n"
1152 " [--port-forward-4 <rule>]\n"
1153 " [--loopback-4 <rule>]\n"
1154 " [--ipv6 on|off]\n"
1155 " [--port-forward-6 <rule>]\n"
1156 " [--loopback-6 <rule>]\n\n"
1157 "%s natnetwork %s remove --netname <name>\n\n"
1158 "%s natnetwork %s modify --netname <name>\n"
1159 " [--network <network>]\n"
1160 " [--enable|--disable]\n"
1161 " [--dhcp on|off]\n"
1162 " [--port-forward-4 <rule>]\n"
1163 " [--loopback-4 <rule>]\n"
1164 " [--ipv6 on|off]\n"
1165 " [--port-forward-6 <rule>]\n"
1166 " [--loopback-6 <rule>]\n\n"
1167 "%s natnetwork %s start --netname <name>\n\n"
1168 "%s natnetwork %s stop --netname <name>\n\n"
1169 "%s natnetwork %s list [<pattern>]\n"
1170 "\n", SEP, SEP, SEP, SEP, SEP, SEP);
1171
1172
1173 }
1174#endif
1175
1176#if defined(VBOX_WITH_NETFLT)
1177 if (fCategory & USAGE_HOSTONLYIFS)
1178 {
1179 RTStrmPrintf(pStrm,
1180 "%s hostonlyif %s ipconfig <name>\n"
1181 " [--dhcp |\n"
1182 " --ip<ipv4> [--netmask<ipv4> (def: 255.255.255.0)] |\n"
1183 " --ipv6<ipv6> [--netmasklengthv6<length> (def: 64)]]\n"
1184# if !defined(RT_OS_SOLARIS) || defined(VBOX_ONLY_DOCS)
1185 " create |\n"
1186 " remove <name>\n"
1187# endif
1188 "\n", SEP);
1189 }
1190#endif
1191
1192 if (fCategory & USAGE_DHCPSERVER)
1193 {
1194 RTStrmPrintf(pStrm,
1195 "%s dhcpserver %s add|modify --netname <network_name> |\n"
1196#if defined(VBOX_WITH_NETFLT)
1197 " --ifname <hostonly_if_name>\n"
1198#endif
1199 " [--ip <ip_address>\n"
1200 " --netmask <network_mask>\n"
1201 " --lowerip <lower_ip>\n"
1202 " --upperip <upper_ip>]\n"
1203 " [--enable | --disable]\n\n"
1204 "%s dhcpserver %s remove --netname <network_name> |\n"
1205#if defined(VBOX_WITH_NETFLT)
1206 " --ifname <hostonly_if_name>\n"
1207#endif
1208 "\n", SEP, SEP);
1209 }
1210
1211 if (fCategory & USAGE_USBDEVSOURCE)
1212 {
1213 RTStrmPrintf(pStrm,
1214 "%s usbdevsource %s add <source name>\n"
1215 " --backend <backend>\n"
1216 " --address <address>\n"
1217 "%s usbdevsource %s remove <source name>\n"
1218 "\n", SEP, SEP);
1219 }
1220
1221#ifndef VBOX_ONLY_DOCS /* Converted to man page, not needed. */
1222 if (fCategory == USAGE_ALL)
1223 {
1224 uint32_t cPendingBlankLines = 0;
1225 for (uint32_t i = 0; i < g_cHelpEntries; i++)
1226 {
1227 PCRTMSGREFENTRY pHelp = g_apHelpEntries[i];
1228 while (cPendingBlankLines-- > 0)
1229 RTStrmPutCh(pStrm, '\n');
1230 RTStrmPrintf(pStrm, " %c%s:\n", RT_C_TO_UPPER(pHelp->pszBrief[0]), pHelp->pszBrief + 1);
1231 cPendingBlankLines = 0;
1232 RTMsgRefEntryPrintStringTable(pStrm, &pHelp->Synopsis, RTMSGREFENTRYSTR_SCOPE_GLOBAL,
1233 &cPendingBlankLines, NULL /*pcLinesWritten*/);
1234 cPendingBlankLines = RT_MAX(cPendingBlankLines, 1);
1235 }
1236 }
1237#endif
1238}
1239
1240/**
1241 * Print a usage synopsis and the syntax error message.
1242 * @returns RTEXITCODE_SYNTAX.
1243 */
1244RTEXITCODE errorSyntax(USAGECATEGORY fCategory, const char *pszFormat, ...)
1245{
1246 va_list args;
1247 showLogo(g_pStdErr); // show logo even if suppressed
1248#ifndef VBOX_ONLY_DOCS
1249 if (g_fInternalMode)
1250 printUsageInternal(fCategory, g_pStdErr);
1251 else
1252 printUsage(fCategory, ~0U, g_pStdErr);
1253#else
1254 RT_NOREF_PV(fCategory);
1255#endif
1256 va_start(args, pszFormat);
1257 RTStrmPrintf(g_pStdErr, "\nSyntax error: %N\n", pszFormat, &args);
1258 va_end(args);
1259 return RTEXITCODE_SYNTAX;
1260}
1261
1262/**
1263 * Print a usage synopsis and the syntax error message.
1264 * @returns RTEXITCODE_SYNTAX.
1265 */
1266RTEXITCODE errorSyntaxEx(USAGECATEGORY fCategory, uint32_t fSubCategory, const char *pszFormat, ...)
1267{
1268 va_list args;
1269 showLogo(g_pStdErr); // show logo even if suppressed
1270#ifndef VBOX_ONLY_DOCS
1271 if (g_fInternalMode)
1272 printUsageInternal(fCategory, g_pStdErr);
1273 else
1274 printUsage(fCategory, fSubCategory, g_pStdErr);
1275#else
1276 RT_NOREF2(fCategory, fSubCategory);
1277#endif
1278 va_start(args, pszFormat);
1279 RTStrmPrintf(g_pStdErr, "\nSyntax error: %N\n", pszFormat, &args);
1280 va_end(args);
1281 return RTEXITCODE_SYNTAX;
1282}
1283
1284/**
1285 * errorSyntax for RTGetOpt users.
1286 *
1287 * @returns RTEXITCODE_SYNTAX.
1288 *
1289 * @param fCategory The usage category of the command.
1290 * @param fSubCategory The usage sub-category of the command.
1291 * @param rc The RTGetOpt return code.
1292 * @param pValueUnion The value union.
1293 */
1294RTEXITCODE errorGetOptEx(USAGECATEGORY fCategory, uint32_t fSubCategory, int rc, union RTGETOPTUNION const *pValueUnion)
1295{
1296 /*
1297 * Check if it is an unhandled standard option.
1298 */
1299#ifndef VBOX_ONLY_DOCS
1300 if (rc == 'V')
1301 {
1302 RTPrintf("%sr%d\n", VBOX_VERSION_STRING, RTBldCfgRevision());
1303 return RTEXITCODE_SUCCESS;
1304 }
1305#endif
1306
1307 if (rc == 'h')
1308 {
1309 showLogo(g_pStdErr);
1310#ifndef VBOX_ONLY_DOCS
1311 if (g_fInternalMode)
1312 printUsageInternal(fCategory, g_pStdOut);
1313 else
1314 printUsage(fCategory, fSubCategory, g_pStdOut);
1315#endif
1316 return RTEXITCODE_SUCCESS;
1317 }
1318
1319 /*
1320 * General failure.
1321 */
1322 showLogo(g_pStdErr); // show logo even if suppressed
1323#ifndef VBOX_ONLY_DOCS
1324 if (g_fInternalMode)
1325 printUsageInternal(fCategory, g_pStdErr);
1326 else
1327 printUsage(fCategory, fSubCategory, g_pStdErr);
1328#else
1329 RT_NOREF2(fCategory, fSubCategory);
1330#endif
1331
1332 if (rc == VINF_GETOPT_NOT_OPTION)
1333 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Invalid parameter '%s'", pValueUnion->psz);
1334 if (rc > 0)
1335 {
1336 if (RT_C_IS_PRINT(rc))
1337 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Invalid option -%c", rc);
1338 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Invalid option case %i", rc);
1339 }
1340 if (rc == VERR_GETOPT_UNKNOWN_OPTION)
1341 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Unknown option: %s", pValueUnion->psz);
1342 if (rc == VERR_GETOPT_INVALID_ARGUMENT_FORMAT)
1343 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Invalid argument format: %s", pValueUnion->psz);
1344 if (pValueUnion->pDef)
1345 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "%s: %Rrs", pValueUnion->pDef->pszLong, rc);
1346 return RTMsgErrorExit(RTEXITCODE_SYNTAX, "%Rrs", rc);
1347}
1348
1349/**
1350 * errorSyntax for RTGetOpt users.
1351 *
1352 * @returns RTEXITCODE_SYNTAX.
1353 *
1354 * @param fUsageCategory The usage category of the command.
1355 * @param rc The RTGetOpt return code.
1356 * @param pValueUnion The value union.
1357 */
1358RTEXITCODE errorGetOpt(USAGECATEGORY fCategory, int rc, union RTGETOPTUNION const *pValueUnion)
1359{
1360 return errorGetOptEx(fCategory, ~0U, rc, pValueUnion);
1361}
1362
1363/**
1364 * Print an error message without the syntax stuff.
1365 *
1366 * @returns RTEXITCODE_SYNTAX.
1367 */
1368RTEXITCODE errorArgument(const char *pszFormat, ...)
1369{
1370 va_list args;
1371 va_start(args, pszFormat);
1372 RTMsgErrorV(pszFormat, args);
1373 va_end(args);
1374 return RTEXITCODE_SYNTAX;
1375}
1376
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