VirtualBox

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

Last change on this file since 68860 was 68860, checked in by vboxsync, 8 years ago

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