VirtualBox

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

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

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