VBoxManageHelp.cpp@ 56192

Last change on this file since 56192 was 56192, checked in by vboxsync, 10 years ago
Extract the necessary bits for the VBoxManage Commands Overview section from the refentry file(s).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 51.3 KB

Line
1	/* $Id: VBoxManageHelp.cpp 56192 2015-06-01 15:46:50Z vboxsync $ */
2	/** @file
3	* VBoxManage - help and other message output.
4	*/
5
6	/*
7	* Copyright (C) 2006-2015 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/err.h>
27	#include <iprt/getopt.h>
28	#include <iprt/stream.h>
29
30	#include "VBoxManage.h"
31
32
33
34	void showLogo(PRTSTREAM pStrm)
35	{
36	static bool s_fShown; /* show only once */
37
38	if (!s_fShown)
39	{
40	RTStrmPrintf(pStrm, VBOX_PRODUCT " Command Line Management Interface Version "
41	VBOX_VERSION_STRING "\n"
42	"(C) 2005-" VBOX_C_YEAR " " VBOX_VENDOR "\n"
43	"All rights reserved.\n"
44	"\n");
45	s_fShown = true;
46	}
47	}
48
49	void printUsage(USAGECATEGORY fCategory, uint32_t fSubCategory, PRTSTREAM pStrm)
50	{
51	bool fDumpOpts = false;
52	#ifdef RT_OS_LINUX
53	bool fLinux = true;
54	#else
55	bool fLinux = false;
56	#endif
57	#ifdef RT_OS_WINDOWS
58	bool fWin = true;
59	#else
60	bool fWin = false;
61	#endif
62	#ifdef RT_OS_SOLARIS
63	bool fSolaris = true;
64	#else
65	bool fSolaris = false;
66	#endif
67	#ifdef RT_OS_FREEBSD
68	bool fFreeBSD = true;
69	#else
70	bool fFreeBSD = false;
71	#endif
72	#ifdef RT_OS_DARWIN
73	bool fDarwin = true;
74	#else
75	bool fDarwin = false;
76	#endif
77	#ifdef VBOX_WITH_VBOXSDL
78	bool fVBoxSDL = true;
79	#else
80	bool fVBoxSDL = false;
81	#endif
82
83	if (fCategory == USAGE_DUMPOPTS)
84	{
85	fDumpOpts = true;
86	fLinux = true;
87	fWin = true;
88	fSolaris = true;
89	fFreeBSD = true;
90	fDarwin = true;
91	fVBoxSDL = true;
92	fCategory = USAGE_ALL;
93	}
94
95	RTStrmPrintf(pStrm,
96	"Usage:\n"
97	"\n");
98
99	if (fCategory == USAGE_ALL)
100	RTStrmPrintf(pStrm,
101	" VBoxManage [<general option>] <command>\n"
102	" \n \n"
103	"General Options:\n \n"
104	" [-v\|--version] print version number and exit\n"
105	" [-q\|--nologo] suppress the logo\n"
106	" [--settingspw <pw>] provide the settings password\n"
107	" [--settingspwfile <file>] provide a file containing the settings password\n"
108	" \n \n"
109	"Commands:\n \n");
110
111	const char *pcszSep1 = " ";
112	const char *pcszSep2 = " ";
113	if (fCategory != USAGE_ALL)
114	{
115	pcszSep1 = "VBoxManage";
116	pcszSep2 = "";
117	}
118
119	#define SEP pcszSep1, pcszSep2
120
121	if (fCategory & USAGE_LIST)
122	RTStrmPrintf(pStrm,
123	"%s list [--long\|-l]%s vms\|runningvms\|ostypes\|hostdvds\|hostfloppies\|\n"
124	#if defined(VBOX_WITH_NETFLT)
125	" intnets\|bridgedifs\|hostonlyifs\|natnets\|dhcpservers\|\n"
126	#else
127	" intnets\|bridgedifs\|natnets\|dhcpservers\|hostinfo\|\n"
128	#endif
129	" hostinfo\|hostcpuids\|hddbackends\|hdds\|dvds\|floppies\|\n"
130	" usbhost\|usbfilters\|systemproperties\|extpacks\|\n"
131	" groups\|webcams\|screenshotformats\n"
132	"\n", SEP);
133
134	if (fCategory & USAGE_SHOWVMINFO)
135	RTStrmPrintf(pStrm,
136	"%s showvminfo %s <uuid\|vmname> [--details]\n"
137	" [--machinereadable]\n"
138	"%s showvminfo %s <uuid\|vmname> --log <idx>\n"
139	"\n", SEP, SEP);
140
141	if (fCategory & USAGE_REGISTERVM)
142	RTStrmPrintf(pStrm,
143	"%s registervm %s <filename>\n"
144	"\n", SEP);
145
146	if (fCategory & USAGE_UNREGISTERVM)
147	RTStrmPrintf(pStrm,
148	"%s unregistervm %s <uuid\|vmname> [--delete]\n"
149	"\n", SEP);
150
151	if (fCategory & USAGE_CREATEVM)
152	RTStrmPrintf(pStrm,
153	"%s createvm %s --name <name>\n"
154	" [--groups <group>, ...]\n"
155	" [--ostype <ostype>]\n"
156	" [--register]\n"
157	" [--basefolder <path>]\n"
158	" [--uuid <uuid>]\n"
159	"\n", SEP);
160
161	if (fCategory & USAGE_MODIFYVM)
162	{
163	RTStrmPrintf(pStrm,
164	"%s modifyvm %s <uuid\|vmname>\n"
165	" [--name <name>]\n"
166	" [--groups <group>, ...]\n"
167	" [--description <desc>]\n"
168	" [--ostype <ostype>]\n"
169	" [--iconfile <filename>]\n"
170	" [--memory <memorysize in MB>]\n"
171	" [--pagefusion on\|off]\n"
172	" [--vram <vramsize in MB>]\n"
173	" [--acpi on\|off]\n"
174	#ifdef VBOX_WITH_PCI_PASSTHROUGH
175	" [--pciattach 03:04.0]\n"
176	" [--pciattach 03:04.0@02:01.0]\n"
177	" [--pcidetach 03:04.0]\n"
178	#endif
179	" [--ioapic on\|off]\n"
180	" [--hpet on\|off]\n"
181	" [--triplefaultreset on\|off]\n"
182	" [--paravirtprovider none\|default\|legacy\|minimal\|\n"
183	" hyperv\|kvm]\n"
184	" [--hwvirtex on\|off]\n"
185	" [--nestedpaging on\|off]\n"
186	" [--largepages on\|off]\n"
187	" [--vtxvpid on\|off]\n"
188	" [--vtxux on\|off]\n"
189	" [--pae on\|off]\n"
190	" [--longmode on\|off]\n"
191	" [--cpuid-portability-level <0..3>\n"
192	" [--cpuidset <leaf> <eax> <ebx> <ecx> <edx>]\n"
193	" [--cpuidremove <leaf>]\n"
194	" [--cpuidremoveall]\n"
195	" [--hardwareuuid <uuid>]\n"
196	" [--cpus <number>]\n"
197	" [--cpuhotplug on\|off]\n"
198	" [--plugcpu <id>]\n"
199	" [--unplugcpu <id>]\n"
200	" [--cpuexecutioncap <1-100>]\n"
201	" [--rtcuseutc on\|off]\n"
202	#ifdef VBOX_WITH_VMSVGA
203	" [--graphicscontroller none\|vboxvga\|vmsvga]\n"
204	#else
205	" [--graphicscontroller none\|vboxvga]\n"
206	#endif
207	" [--monitorcount <number>]\n"
208	" [--accelerate3d on\|off]\n"
209	#ifdef VBOX_WITH_VIDEOHWACCEL
210	" [--accelerate2dvideo on\|off]\n"
211	#endif
212	" [--firmware bios\|efi\|efi32\|efi64]\n"
213	" [--chipset ich9\|piix3]\n"
214	" [--bioslogofadein on\|off]\n"
215	" [--bioslogofadeout on\|off]\n"
216	" [--bioslogodisplaytime <msec>]\n"
217	" [--bioslogoimagepath <imagepath>]\n"
218	" [--biosbootmenu disabled\|menuonly\|messageandmenu]\n"
219	" [--biossystemtimeoffset <msec>]\n"
220	" [--biospxedebug on\|off]\n"
221	" [--boot<1-4> none\|floppy\|dvd\|disk\|net>]\n"
222	" [--nic<1-N> none\|null\|nat\|bridged\|intnet"
223	#if defined(VBOX_WITH_NETFLT)
224	"\|hostonly"
225	#endif
226	"\|\n"
227	" generic\|natnetwork"
228	"]\n"
229	" [--nictype<1-N> Am79C970A\|Am79C973"
230	#ifdef VBOX_WITH_E1000
231	"\|\n 82540EM\|82543GC\|82545EM"
232	#endif
233	#ifdef VBOX_WITH_VIRTIO
234	"\|\n virtio"
235	#endif /* VBOX_WITH_VIRTIO */
236	"]\n"
237	" [--cableconnected<1-N> on\|off]\n"
238	" [--nictrace<1-N> on\|off]\n"
239	" [--nictracefile<1-N> <filename>]\n"
240	" [--nicproperty<1-N> name=[value]]\n"
241	" [--nicspeed<1-N> <kbps>]\n"
242	" [--nicbootprio<1-N> <priority>]\n"
243	" [--nicpromisc<1-N> deny\|allow-vms\|allow-all]\n"
244	" [--nicbandwidthgroup<1-N> none\|<name>]\n"
245	" [--bridgeadapter<1-N> none\|<devicename>]\n"
246	#if defined(VBOX_WITH_NETFLT)
247	" [--hostonlyadapter<1-N> none\|<devicename>]\n"
248	#endif
249	" [--intnet<1-N> <network name>]\n"
250	" [--nat-network<1-N> <network name>]\n"
251	" [--nicgenericdrv<1-N> <driver>\n"
252	" [--natnet<1-N> <network>\|default]\n"
253	" [--natsettings<1-N> [<mtu>],[<socksnd>],\n"
254	" [<sockrcv>],[<tcpsnd>],\n"
255	" [<tcprcv>]]\n"
256	" [--natpf<1-N> [<rulename>],tcp\|udp,[<hostip>],\n"
257	" <hostport>,[<guestip>],<guestport>]\n"
258	" [--natpf<1-N> delete <rulename>]\n"
259	" [--nattftpprefix<1-N> <prefix>]\n"
260	" [--nattftpfile<1-N> <file>]\n"
261	" [--nattftpserver<1-N> <ip>]\n"
262	" [--natbindip<1-N> <ip>\n"
263	" [--natdnspassdomain<1-N> on\|off]\n"
264	" [--natdnsproxy<1-N> on\|off]\n"
265	" [--natdnshostresolver<1-N> on\|off]\n"
266	" [--nataliasmode<1-N> default\|[log],[proxyonly],\n"
267	" [sameports]]\n"
268	" [--macaddress<1-N> auto\|<mac>]\n"
269	" [--mouse ps2\|usb\|usbtablet\|usbmultitouch]\n"
270	" [--keyboard ps2\|usb\n"
271	" [--uart<1-N> off\|<I/O base> <IRQ>]\n"
272	" [--uartmode<1-N> disconnected\|\n"
273	" server <pipe>\|\n"
274	" client <pipe>\|\n"
275	" tcpserver <port>\|\n"
276	" tcpclient <hostname:port>\|\n"
277	" file <file>\|\n"
278	" <devicename>]\n"
279	#if defined(RT_OS_LINUX) \|\| defined(RT_OS_WINDOWS)
280	" [--lpt<1-N> off\|<I/O base> <IRQ>]\n"
281	" [--lptmode<1-N> <devicename>]\n"
282	#endif
283	" [--guestmemoryballoon <balloonsize in MB>]\n"
284	" [--audio none\|null", SEP);
285	if (fWin)
286	{
287	#ifdef VBOX_WITH_WINMM
288	RTStrmPrintf(pStrm, "\|winmm\|dsound");
289	#else
290	RTStrmPrintf(pStrm, "\|dsound");
291	#endif
292	}
293	if (fSolaris)
294	{
295	RTStrmPrintf(pStrm, "\|solaudio"
296	#ifdef VBOX_WITH_SOLARIS_OSS
297	"\|oss"
298	#endif
299	);
300	}
301	if (fLinux)
302	{
303	RTStrmPrintf(pStrm, "\|oss"
304	#ifdef VBOX_WITH_ALSA
305	"\|alsa"
306	#endif
307	#ifdef VBOX_WITH_PULSE
308	"\|pulse"
309	#endif
310	);
311	}
312	if (fFreeBSD)
313	{
314	/* Get the line break sorted when dumping all option variants. */
315	if (fDumpOpts)
316	{
317	RTStrmPrintf(pStrm, "\|\n"
318	" oss");
319	}
320	else
321	RTStrmPrintf(pStrm, "\|oss");
322	#ifdef VBOX_WITH_PULSE
323	RTStrmPrintf(pStrm, "\|pulse");
324	#endif
325	}
326	if (fDarwin)
327	{
328	RTStrmPrintf(pStrm, "\|coreaudio");
329	}
330	RTStrmPrintf(pStrm, "]\n");
331	RTStrmPrintf(pStrm,
332	" [--audiocontroller ac97\|hda\|sb16]\n"
333	" [--clipboard disabled\|hosttoguest\|guesttohost\|\n"
334	" bidirectional]\n"
335	" [--draganddrop disabled\|hosttoguest]\n");
336	RTStrmPrintf(pStrm,
337	" [--vrde on\|off]\n"
338	" [--vrdeextpack default\|<name>\n"
339	" [--vrdeproperty <name=[value]>]\n"
340	" [--vrdeport <hostport>]\n"
341	" [--vrdeaddress <hostip>]\n"
342	" [--vrdeauthtype null\|external\|guest]\n"
343	" [--vrdeauthlibrary default\|<name>\n"
344	" [--vrdemulticon on\|off]\n"
345	" [--vrdereusecon on\|off]\n"
346	" [--vrdevideochannel on\|off]\n"
347	" [--vrdevideochannelquality <percent>]\n");
348	RTStrmPrintf(pStrm,
349	" [--usb on\|off]\n"
350	" [--usbehci on\|off]\n"
351	" [--usbxhci on\|off]\n"
352	" [--snapshotfolder default\|<path>]\n"
353	" [--teleporter on\|off]\n"
354	" [--teleporterport <port>]\n"
355	" [--teleporteraddress <address\|empty>\n"
356	" [--teleporterpassword <password>]\n"
357	" [--teleporterpasswordfile <file>\|stdin]\n"
358	" [--tracing-enabled on\|off]\n"
359	" [--tracing-config <config-string>]\n"
360	" [--tracing-allow-vm-access on\|off]\n"
361	#if 0
362	" [--iocache on\|off]\n"
363	" [--iocachesize <I/O cache size in MB>]\n"
364	#endif
365	#if 0
366	" [--faulttolerance master\|standby]\n"
367	" [--faulttoleranceaddress <name>]\n"
368	" [--faulttoleranceport <port>]\n"
369	" [--faulttolerancesyncinterval <msec>]\n"
370	" [--faulttolerancepassword <password>]\n"
371	#endif
372	#ifdef VBOX_WITH_USB_CARDREADER
373	" [--usbcardreader on\|off]\n"
374	#endif
375	" [--autostart-enabled on\|off]\n"
376	" [--autostart-delay <seconds>]\n"
377	#if 0
378	" [--autostop-type disabled\|savestate\|poweroff\|\n"
379	" acpishutdown]\n"
380	#endif
381	#ifdef VBOX_WITH_VPX
382	" [--videocap on\|off]\n"
383	" [--videocapscreens all\|<screen ID> [<screen ID> ...]]\n"
384	" [--videocapfile <filename>]\n"
385	" [--videocapres <width> <height>]\n"
386	" [--videocaprate <rate>]\n"
387	" [--videocapfps <fps>]\n"
388	" [--videocapmaxtime <time>]\n"
389	" [--videocapmaxsize <MB>]\n"
390	" [--videocapopts <key=value> [<key=value> ...]]\n"
391	#endif
392	" [--defaultfrontend default\|<name>]\n"
393	"\n");
394	}
395
396	if (fCategory & USAGE_CLONEVM)
397	RTStrmPrintf(pStrm,
398	"%s clonevm %s <uuid\|vmname>\n"
399	" [--snapshot <uuid>\|<name>]\n"
400	" [--mode machine\|machineandchildren\|all]\n"
401	" [--options link\|keepallmacs\|keepnatmacs\|\n"
402	" keepdisknames]\n"
403	" [--name <name>]\n"
404	" [--groups <group>, ...]\n"
405	" [--basefolder <basefolder>]\n"
406	" [--uuid <uuid>]\n"
407	" [--register]\n"
408	"\n", SEP);
409
410	if (fCategory & USAGE_IMPORTAPPLIANCE)
411	RTStrmPrintf(pStrm,
412	"%s import %s <ovfname/ovaname>\n"
413	" [--dry-run\|-n]\n"
414	" [--options keepallmacs\|keepnatmacs\|importtovdi]\n"
415	" [more options]\n"
416	" (run with -n to have options displayed\n"
417	" for a particular OVF)\n\n", SEP);
418
419	if (fCategory & USAGE_EXPORTAPPLIANCE)
420	RTStrmPrintf(pStrm,
421	"%s export %s <machines> --output\|-o <name>.<ovf/ova>\n"
422	" [--legacy09\|--ovf09\|--ovf10\|--ovf20]\n"
423	" [--manifest]\n"
424	" [--iso]\n"
425	" [--options manifest\|iso\|nomacs\|nomacsbutnat]\n"
426	" [--vsys <number of virtual system>]\n"
427	" [--product <product name>]\n"
428	" [--producturl <product url>]\n"
429	" [--vendor <vendor name>]\n"
430	" [--vendorurl <vendor url>]\n"
431	" [--version <version info>]\n"
432	" [--description <description info>]\n"
433	" [--eula <license text>]\n"
434	" [--eulafile <filename>]\n"
435	"\n", SEP);
436
437	if (fCategory & USAGE_STARTVM)
438	{
439	RTStrmPrintf(pStrm,
440	"%s startvm %s <uuid\|vmname>...\n"
441	" [--type gui", SEP);
442	if (fVBoxSDL)
443	RTStrmPrintf(pStrm, "\|sdl");
444	RTStrmPrintf(pStrm, "\|headless\|separate]\n");
445	RTStrmPrintf(pStrm,
446	"\n");
447	}
448
449	if (fCategory & USAGE_CONTROLVM)
450	{
451	RTStrmPrintf(pStrm,
452	"%s controlvm %s <uuid\|vmname>\n"
453	" pause\|resume\|reset\|poweroff\|savestate\|\n"
454	" acpipowerbutton\|acpisleepbutton\|\n"
455	" keyboardputscancode <hex> [<hex> ...]\|\n"
456	" setlinkstate<1-N> on\|off \|\n"
457	#if defined(VBOX_WITH_NETFLT)
458	" nic<1-N> null\|nat\|bridged\|intnet\|hostonly\|generic\|\n"
459	" natnetwork [<devicename>] \|\n"
460	#else /* !VBOX_WITH_NETFLT */
461	" nic<1-N> null\|nat\|bridged\|intnet\|generic\|natnetwork\n"
462	" [<devicename>] \|\n"
463	#endif /* !VBOX_WITH_NETFLT */
464	" nictrace<1-N> on\|off \|\n"
465	" nictracefile<1-N> <filename> \|\n"
466	" nicproperty<1-N> name=[value] \|\n"
467	" nicpromisc<1-N> deny\|allow-vms\|allow-all \|\n"
468	" natpf<1-N> [<rulename>],tcp\|udp,[<hostip>],\n"
469	" <hostport>,[<guestip>],<guestport> \|\n"
470	" natpf<1-N> delete <rulename> \|\n"
471	" guestmemoryballoon <balloonsize in MB> \|\n"
472	" usbattach <uuid>\|<address>\n"
473	" [--capturefile <filename>] \|\n"
474	" usbdetach <uuid>\|<address> \|\n"
475	" clipboard disabled\|hosttoguest\|guesttohost\|\n"
476	" bidirectional \|\n"
477	" draganddrop disabled\|hosttoguest \|\n"
478	" vrde on\|off \|\n"
479	" vrdeport <port> \|\n"
480	" vrdeproperty <name=[value]> \|\n"
481	" vrdevideochannelquality <percent> \|\n"
482	" setvideomodehint <xres> <yres> <bpp>\n"
483	" [[<display>] [<enabled:yes\|no> \|\n"
484	" [<xorigin> <yorigin>]]] \|\n"
485	" screenshotpng <file> [display] \|\n"
486	" vcpenabled on\|off \|\n"
487	" vcpscreens all\|none\|<screen>,[<screen>...] \|\n"
488	" setcredentials <username>\n"
489	" --passwordfile <file> \| <password>\n"
490	" <domain>\n"
491	" [--allowlocallogon <yes\|no>] \|\n"
492	" teleport --host <name> --port <port>\n"
493	" [--maxdowntime <msec>]\n"
494	" [--passwordfile <file> \|\n"
495	" --password <password>] \|\n"
496	" plugcpu <id> \|\n"
497	" unplugcpu <id> \|\n"
498	" cpuexecutioncap <1-100>\n"
499	" webcam <attach [path [settings]]> \| <detach [path]> \| <list>\n"
500	" addencpassword <id>\n"
501	" <password file>\|-\n"
502	" [--removeonsuspend <yes\|no>]\n"
503	" removeencpassword <id>\n"
504	" removeallencpasswords\n"
505	"\n", SEP);
506	}
507
508	if (fCategory & USAGE_DISCARDSTATE)
509	RTStrmPrintf(pStrm,
510	"%s discardstate %s <uuid\|vmname>\n"
511	"\n", SEP);
512
513	if (fCategory & USAGE_ADOPTSTATE)
514	RTStrmPrintf(pStrm,
515	"%s adoptstate %s <uuid\|vmname> <state_file>\n"
516	"\n", SEP);
517
518	if (fCategory & USAGE_SNAPSHOT)
519	RTStrmPrintf(pStrm,
520	"%s snapshot %s <uuid\|vmname>\n"
521	" take <name> [--description <desc>] [--live]\n"
522	" [--uniquename Number,Timestamp,Space,Force] \|\n"
523	" delete <uuid\|snapname> \|\n"
524	" restore <uuid\|snapname> \|\n"
525	" restorecurrent \|\n"
526	" edit <uuid\|snapname>\|--current\n"
527	" [--name <name>]\n"
528	" [--description <desc>] \|\n"
529	" list [--details\|--machinereadable]\n"
530	" showvminfo <uuid\|snapname>\n"
531	"\n", SEP);
532
533	if (fCategory & USAGE_CLOSEMEDIUM)
534	RTStrmPrintf(pStrm,
535	"%s closemedium %s [disk\|dvd\|floppy] <uuid\|filename>\n"
536	" [--delete]\n"
537	"\n", SEP);
538
539	if (fCategory & USAGE_STORAGEATTACH)
540	RTStrmPrintf(pStrm,
541	"%s storageattach %s <uuid\|vmname>\n"
542	" --storagectl <name>\n"
543	" [--port <number>]\n"
544	" [--device <number>]\n"
545	" [--type dvddrive\|hdd\|fdd]\n"
546	" [--medium none\|emptydrive\|additions\|\n"
547	" <uuid\|filename>\|host:<drive>\|iscsi]\n"
548	" [--mtype normal\|writethrough\|immutable\|shareable\|\n"
549	" readonly\|multiattach]\n"
550	" [--comment <text>]\n"
551	" [--setuuid <uuid>]\n"
552	" [--setparentuuid <uuid>]\n"
553	" [--passthrough on\|off]\n"
554	" [--tempeject on\|off]\n"
555	" [--nonrotational on\|off]\n"
556	" [--discard on\|off]\n"
557	" [--hotpluggable on\|off]\n"
558	" [--bandwidthgroup <name>]\n"
559	" [--forceunmount]\n"
560	" [--server <name>\|<ip>]\n"
561	" [--target <target>]\n"
562	" [--tport <port>]\n"
563	" [--lun <lun>]\n"
564	" [--encodedlun <lun>]\n"
565	" [--username <username>]\n"
566	" [--password <password>]\n"
567	" [--initiator <initiator>]\n"
568	" [--intnet]\n"
569	"\n", SEP);
570
571	if (fCategory & USAGE_STORAGECONTROLLER)
572	RTStrmPrintf(pStrm,
573	"%s storagectl %s <uuid\|vmname>\n"
574	" --name <name>\n"
575	" [--add ide\|sata\|scsi\|floppy\|sas]\n"
576	" [--controller LSILogic\|LSILogicSAS\|BusLogic\|\n"
577	" IntelAHCI\|PIIX3\|PIIX4\|ICH6\|I82078]\n"
578	" [--portcount <1-n>]\n"
579	" [--hostiocache on\|off]\n"
580	" [--bootable on\|off]\n"
581	" [--remove]\n"
582	"\n", SEP);
583
584	if (fCategory & USAGE_BANDWIDTHCONTROL)
585	RTStrmPrintf(pStrm,
586	"%s bandwidthctl %s <uuid\|vmname>\n"
587	" add <name> --type disk\|network\n"
588	" --limit <megabytes per second>[k\|m\|g\|K\|M\|G] \|\n"
589	" set <name>\n"
590	" --limit <megabytes per second>[k\|m\|g\|K\|M\|G] \|\n"
591	" remove <name> \|\n"
592	" list [--machinereadable]\n"
593	" (limit units: k=kilobit, m=megabit, g=gigabit,\n"
594	" K=kilobyte, M=megabyte, G=gigabyte)\n"
595	"\n", SEP);
596
597	if (fCategory & USAGE_SHOWMEDIUMINFO)
598	RTStrmPrintf(pStrm,
599	"%s showmediuminfo %s [disk\|dvd\|floppy] <uuid\|filename>\n"
600	"\n", SEP);
601
602	if (fCategory & USAGE_CREATEMEDIUM)
603	RTStrmPrintf(pStrm,
604	"%s createmedium %s [disk\|dvd\|floppy] --filename <filename>\n"
605	" [--size <megabytes>\|--sizebyte <bytes>]\n"
606	" [--diffparent <uuid>\|<filename>\n"
607	" [--format VDI\|VMDK\|VHD] (default: VDI)\n"
608	" [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
609	"\n", SEP);
610
611	if (fCategory & USAGE_MODIFYMEDIUM)
612	RTStrmPrintf(pStrm,
613	"%s modifymedium %s [disk\|dvd\|floppy] <uuid\|filename>\n"
614	" [--type normal\|writethrough\|immutable\|shareable\|\n"
615	" readonly\|multiattach]\n"
616	" [--autoreset on\|off]\n"
617	" [--property <name=[value]>]\n"
618	" [--compact]\n"
619	" [--resize <megabytes>\|--resizebyte <bytes>]\n"
620	"\n", SEP);
621
622	if (fCategory & USAGE_CLONEMEDIUM)
623	RTStrmPrintf(pStrm,
624	"%s clonemedium %s [disk\|dvd\|floppy] <uuid\|inputfile> <uuid\|outputfile>\n"
625	" [--format VDI\|VMDK\|VHD\|RAW\|<other>]\n"
626	" [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
627	" [--existing]\n"
628	"\n", SEP);
629
630	if (fCategory & USAGE_MEDIUMPROPERTY)
631	RTStrmPrintf(pStrm,
632	"%s mediumproperty %s [disk\|dvd\|floppy] set <uuid\|filename>\n"
633	" <property> <value>\n"
634	"\n"
635	" [disk\|dvd\|floppy] get <uuid\|filename>\n"
636	" <property>\n"
637	"\n"
638	" [disk\|dvd\|floppy] delete <uuid\|filename>\n"
639	" <property>\n"
640	"\n", SEP);
641
642	if (fCategory & USAGE_ENCRYPTMEDIUM)
643	RTStrmPrintf(pStrm,
644	"%s encryptmedium %s <uuid\|filename>\n"
645	" [--newpassword <file>\|-]\n"
646	" [--oldpassword <file>\|-]\n"
647	" [--cipher <cipher identifier>]\n"
648	" [--newpasswordid <password identifier>]\n"
649	"\n", SEP);
650
651	if (fCategory & USAGE_MEDIUMENCCHKPWD)
652	RTStrmPrintf(pStrm,
653	"%s checkmediumpwd %s <uuid\|filename>\n"
654	" <pwd file>\|-\n"
655	"\n", SEP);
656
657	if (fCategory & USAGE_CONVERTFROMRAW)
658	RTStrmPrintf(pStrm,
659	"%s convertfromraw %s <filename> <outputfile>\n"
660	" [--format VDI\|VMDK\|VHD]\n"
661	" [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
662	" [--uuid <uuid>]\n"
663	"%s convertfromraw %s stdin <outputfile> <bytes>\n"
664	" [--format VDI\|VMDK\|VHD]\n"
665	" [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
666	" [--uuid <uuid>]\n"
667	"\n", SEP, SEP);
668
669	if (fCategory & USAGE_GETEXTRADATA)
670	RTStrmPrintf(pStrm,
671	"%s getextradata %s global\|<uuid\|vmname>\n"
672	" <key>\|enumerate\n"
673	"\n", SEP);
674
675	if (fCategory & USAGE_SETEXTRADATA)
676	RTStrmPrintf(pStrm,
677	"%s setextradata %s global\|<uuid\|vmname>\n"
678	" <key>\n"
679	" [<value>] (no value deletes key)\n"
680	"\n", SEP);
681
682	if (fCategory & USAGE_SETPROPERTY)
683	RTStrmPrintf(pStrm,
684	"%s setproperty %s machinefolder default\|<folder> \|\n"
685	" hwvirtexclusive on\|off \|\n"
686	" vrdeauthlibrary default\|<library> \|\n"
687	" websrvauthlibrary default\|null\|<library> \|\n"
688	" vrdeextpack null\|<library> \|\n"
689	" autostartdbpath null\|<folder> \|\n"
690	" loghistorycount <value>\n"
691	" defaultfrontend default\|<name>\n"
692	" logginglevel <log setting>\n"
693	"\n", SEP);
694
695	if (fCategory & USAGE_USBFILTER_ADD)
696	RTStrmPrintf(pStrm,
697	"%s usbfilter %s add <index,0-N>\n"
698	" --target <uuid\|vmname>\|global\n"
699	" --name <string>\n"
700	" --action ignore\|hold (global filters only)\n"
701	" [--active yes\|no] (yes)\n"
702	" [--vendorid <XXXX>] (null)\n"
703	" [--productid <XXXX>] (null)\n"
704	" [--revision <IIFF>] (null)\n"
705	" [--manufacturer <string>] (null)\n"
706	" [--product <string>] (null)\n"
707	" [--remote yes\|no] (null, VM filters only)\n"
708	" [--serialnumber <string>] (null)\n"
709	" [--maskedinterfaces <XXXXXXXX>]\n"
710	"\n", SEP);
711
712	if (fCategory & USAGE_USBFILTER_MODIFY)
713	RTStrmPrintf(pStrm,
714	"%s usbfilter %s modify <index,0-N>\n"
715	" --target <uuid\|vmname>\|global\n"
716	" [--name <string>]\n"
717	" [--action ignore\|hold] (global filters only)\n"
718	" [--active yes\|no]\n"
719	" [--vendorid <XXXX>\|\"\"]\n"
720	" [--productid <XXXX>\|\"\"]\n"
721	" [--revision <IIFF>\|\"\"]\n"
722	" [--manufacturer <string>\|\"\"]\n"
723	" [--product <string>\|\"\"]\n"
724	" [--remote yes\|no] (null, VM filters only)\n"
725	" [--serialnumber <string>\|\"\"]\n"
726	" [--maskedinterfaces <XXXXXXXX>]\n"
727	"\n", SEP);
728
729	if (fCategory & USAGE_USBFILTER_REMOVE)
730	RTStrmPrintf(pStrm,
731	"%s usbfilter %s remove <index,0-N>\n"
732	" --target <uuid\|vmname>\|global\n"
733	"\n", SEP);
734
735	if (fCategory & USAGE_SHAREDFOLDER_ADD)
736	RTStrmPrintf(pStrm,
737	"%s sharedfolder %s add <uuid\|vmname>\n"
738	" --name <name> --hostpath <hostpath>\n"
739	" [--transient] [--readonly] [--automount]\n"
740	"\n", SEP);
741
742	if (fCategory & USAGE_SHAREDFOLDER_REMOVE)
743	RTStrmPrintf(pStrm,
744	"%s sharedfolder %s remove <uuid\|vmname>\n"
745	" --name <name> [--transient]\n"
746	"\n", SEP);
747
748	#ifdef VBOX_WITH_GUEST_PROPS
749	if (fCategory & USAGE_GUESTPROPERTY)
750	usageGuestProperty(pStrm, SEP);
751	#endif /* VBOX_WITH_GUEST_PROPS defined */
752
753	#ifdef VBOX_WITH_GUEST_CONTROL
754	if (fCategory & USAGE_GUESTCONTROL)
755	usageGuestControl(pStrm, SEP, fSubCategory);
756	#endif /* VBOX_WITH_GUEST_CONTROL defined */
757
758	if (fCategory & USAGE_DEBUGVM)
759	{
760	RTStrmPrintf(pStrm,
761	"%s debugvm %s <uuid\|vmname>\n"
762	" dumpguestcore --filename <name> \|\n"
763	" info <item> [args] \|\n"
764	" injectnmi \|\n"
765	" log [--release\|--debug] <settings> ...\|\n"
766	" logdest [--release\|--debug] <settings> ...\|\n"
767	" logflags [--release\|--debug] <settings> ...\|\n"
768	" osdetect \|\n"
769	" osinfo \|\n"
770	" osdmesg [--lines\|-n <N>] \|\n"
771	" getregisters [--cpu <id>] <reg>\|all ... \|\n"
772	" setregisters [--cpu <id>] <reg>=<value> ... \|\n"
773	" show [--human-readable\|--sh-export\|--sh-eval\|\n"
774	" --cmd-set] \n"
775	" <logdbg-settings\|logrel-settings>\n"
776	" [[opt] what ...] \|\n"
777	" statistics [--reset] [--pattern <pattern>]\n"
778	" [--descriptions]\n"
779	"\n", SEP);
780	}
781	if (fCategory & USAGE_METRICS)
782	RTStrmPrintf(pStrm,
783	"%s metrics %s list [*\|host\|<vmname> [<metric_list>]]\n"
784	" (comma-separated)\n\n"
785	"%s metrics %s setup\n"
786	" [--period <seconds>] (default: 1)\n"
787	" [--samples <count>] (default: 1)\n"
788	" [--list]\n"
789	" [*\|host\|<vmname> [<metric_list>]]\n\n"
790	"%s metrics %s query [*\|host\|<vmname> [<metric_list>]]\n\n"
791	"%s metrics %s enable\n"
792	" [--list]\n"
793	" [*\|host\|<vmname> [<metric_list>]]\n\n"
794	"%s metrics %s disable\n"
795	" [--list]\n"
796	" [*\|host\|<vmname> [<metric_list>]]\n\n"
797	"%s metrics %s collect\n"
798	" [--period <seconds>] (default: 1)\n"
799	" [--samples <count>] (default: 1)\n"
800	" [--list]\n"
801	" [--detach]\n"
802	" [*\|host\|<vmname> [<metric_list>]]\n"
803	"\n", SEP, SEP, SEP, SEP, SEP, SEP);
804
805	#if defined(VBOX_WITH_NAT_SERVICE)
806	if (fCategory & USAGE_NATNETWORK)
807	{
808	RTStrmPrintf(pStrm,
809	"%s natnetwork %s add --netname <name>\n"
810	" --network <network>\n"
811	" [--enable\|--disable]\n"
812	" [--dhcp on\|off]\n"
813	" [--port-forward-4 <rule>]\n"
814	" [--loopback-4 <rule>]\n"
815	" [--ipv6 on\|off]\n"
816	" [--port-forward-6 <rule>]\n"
817	" [--loopback-6 <rule>]\n\n"
818	"%s natnetwork %s remove --netname <name>\n\n"
819	"%s natnetwork %s modify --netname <name>\n"
820	" [--network <network>]\n"
821	" [--enable\|--disable]\n"
822	" [--dhcp on\|off]\n"
823	" [--port-forward-4 <rule>]\n"
824	" [--loopback-4 <rule>]\n"
825	" [--ipv6 on\|off]\n"
826	" [--port-forward-6 <rule>]\n"
827	" [--loopback-6 <rule>]\n\n"
828	"%s natnetwork %s start --netname <name>\n\n"
829	"%s natnetwork %s stop --netname <name>\n"
830	"\n", SEP, SEP, SEP, SEP, SEP);
831
832
833	}
834	#endif
835
836	#if defined(VBOX_WITH_NETFLT)
837	if (fCategory & USAGE_HOSTONLYIFS)
838	{
839	RTStrmPrintf(pStrm,
840	"%s hostonlyif %s ipconfig <name>\n"
841	" [--dhcp \|\n"
842	" --ip<ipv4> [--netmask<ipv4> (def: 255.255.255.0)] \|\n"
843	" --ipv6<ipv6> [--netmasklengthv6<length> (def: 64)]]\n"
844	# if !defined(RT_OS_SOLARIS)
845	" create \|\n"
846	" remove <name>\n"
847	# endif
848	"\n", SEP);
849	}
850	#endif
851
852	if (fCategory & USAGE_DHCPSERVER)
853	{
854	RTStrmPrintf(pStrm,
855	"%s dhcpserver %s add\|modify --netname <network_name> \|\n"
856	#if defined(VBOX_WITH_NETFLT)
857	" --ifname <hostonly_if_name>\n"
858	#endif
859	" [--ip <ip_address>\n"
860	" --netmask <network_mask>\n"
861	" --lowerip <lower_ip>\n"
862	" --upperip <upper_ip>]\n"
863	" [--enable \| --disable]\n\n"
864	"%s dhcpserver %s remove --netname <network_name> \|\n"
865	#if defined(VBOX_WITH_NETFLT)
866	" --ifname <hostonly_if_name>\n"
867	#endif
868	"\n", SEP, SEP);
869	}
870	#ifndef VBOX_ONLY_DOCS /* Converted to man page, not needed. */
871	if (fCategory & USAGE_EXTPACK)
872	{
873	RTStrmPrintf(pStrm,
874	"%s extpack %s install [--replace] <tarball> \|\n"
875	" uninstall [--force] <name> \|\n"
876	" cleanup\n"
877	"\n", SEP);
878	}
879	#endif
880	}
881
882	/**
883	* Print a usage synopsis and the syntax error message.
884	* @returns RTEXITCODE_SYNTAX.
885	*/
886	RTEXITCODE errorSyntax(USAGECATEGORY fCategory, const char *pszFormat, ...)
887	{
888	va_list args;
889	showLogo(g_pStdErr); // show logo even if suppressed
890	#ifndef VBOX_ONLY_DOCS
891	if (g_fInternalMode)
892	printUsageInternal(fCategory, g_pStdErr);
893	else
894	printUsage(fCategory, ~0U, g_pStdErr);
895	#endif /* !VBOX_ONLY_DOCS */
896	va_start(args, pszFormat);
897	RTStrmPrintf(g_pStdErr, "\nSyntax error: %N\n", pszFormat, &args);
898	va_end(args);
899	return RTEXITCODE_SYNTAX;
900	}
901
902	/**
903	* Print a usage synopsis and the syntax error message.
904	* @returns RTEXITCODE_SYNTAX.
905	*/
906	RTEXITCODE errorSyntaxEx(USAGECATEGORY fCategory, uint32_t fSubCategory, const char *pszFormat, ...)
907	{
908	va_list args;
909	showLogo(g_pStdErr); // show logo even if suppressed
910	#ifndef VBOX_ONLY_DOCS
911	if (g_fInternalMode)
912	printUsageInternal(fCategory, g_pStdErr);
913	else
914	printUsage(fCategory, fSubCategory, g_pStdErr);
915	#endif /* !VBOX_ONLY_DOCS */
916	va_start(args, pszFormat);
917	RTStrmPrintf(g_pStdErr, "\nSyntax error: %N\n", pszFormat, &args);
918	va_end(args);
919	return RTEXITCODE_SYNTAX;
920	}
921
922	/**
923	* errorSyntax for RTGetOpt users.
924	*
925	* @returns RTEXITCODE_SYNTAX.
926	*
927	* @param fCategory The usage category of the command.
928	* @param fSubCategory The usage sub-category of the command.
929	* @param rc The RTGetOpt return code.
930	* @param pValueUnion The value union.
931	*/
932	RTEXITCODE errorGetOptEx(USAGECATEGORY fCategory, uint32_t fSubCategory, int rc, union RTGETOPTUNION const *pValueUnion)
933	{
934	/*
935	* Check if it is an unhandled standard option.
936	*/
937	if (rc == 'V')
938	{
939	RTPrintf("%sr%d\n", VBOX_VERSION_STRING, RTBldCfgRevision());
940	return RTEXITCODE_SUCCESS;
941	}
942
943	if (rc == 'h')
944	{
945	showLogo(g_pStdErr);
946	#ifndef VBOX_ONLY_DOCS
947	if (g_fInternalMode)
948	printUsageInternal(fCategory, g_pStdOut);
949	else
950	printUsage(fCategory, fSubCategory, g_pStdOut);
951	#endif
952	return RTEXITCODE_SUCCESS;
953	}
954
955	/*
956	* General failure.
957	*/
958	showLogo(g_pStdErr); // show logo even if suppressed
959	#ifndef VBOX_ONLY_DOCS
960	if (g_fInternalMode)
961	printUsageInternal(fCategory, g_pStdErr);
962	else
963	printUsage(fCategory, fSubCategory, g_pStdErr);
964	#endif /* !VBOX_ONLY_DOCS */
965
966	if (rc == VINF_GETOPT_NOT_OPTION)
967	return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Invalid parameter '%s'", pValueUnion->psz);
968	if (rc > 0)
969	{
970	if (RT_C_IS_PRINT(rc))
971	return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Invalid option -%c", rc);
972	return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Invalid option case %i", rc);
973	}
974	if (rc == VERR_GETOPT_UNKNOWN_OPTION)
975	return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Unknown option: %s", pValueUnion->psz);
976	if (rc == VERR_GETOPT_INVALID_ARGUMENT_FORMAT)
977	return RTMsgErrorExit(RTEXITCODE_SYNTAX, "Invalid argument format: %s", pValueUnion->psz);
978	if (pValueUnion->pDef)
979	return RTMsgErrorExit(RTEXITCODE_SYNTAX, "%s: %Rrs", pValueUnion->pDef->pszLong, rc);
980	return RTMsgErrorExit(RTEXITCODE_SYNTAX, "%Rrs", rc);
981	}
982
983	/**
984	* errorSyntax for RTGetOpt users.
985	*
986	* @returns RTEXITCODE_SYNTAX.
987	*
988	* @param fUsageCategory The usage category of the command.
989	* @param rc The RTGetOpt return code.
990	* @param pValueUnion The value union.
991	*/
992	RTEXITCODE errorGetOpt(USAGECATEGORY fCategory, int rc, union RTGETOPTUNION const *pValueUnion)
993	{
994	return errorGetOptEx(fCategory, ~0U, rc, pValueUnion);
995	}
996
997	/**
998	* Print an error message without the syntax stuff.
999	*
1000	* @returns RTEXITCODE_SYNTAX.
1001	*/
1002	RTEXITCODE errorArgument(const char *pszFormat, ...)
1003	{
1004	va_list args;
1005	va_start(args, pszFormat);
1006	RTMsgErrorV(pszFormat, args);
1007	va_end(args);
1008	return RTEXITCODE_SYNTAX;
1009	}

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: