VirtualBox

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

Last change on this file since 20479 was 20313, checked in by vboxsync, 16 years ago

Frontends/VBoxManage, Main/Machine: implement new session type "headless" which suppresses any output. Based on the contribution by Josh Wright.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 24.0 KB
Line 
1/* $Id: VBoxManageHelp.cpp 20313 2009-06-05 11:00:32Z vboxsync $ */
2/** @file
3 * VBoxManage - help and other message output.
4 */
5
6/*
7 * Copyright (C) 2006-2009 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
18 * Clara, CA 95054 USA or visit http://www.sun.com if you need
19 * additional information or have any questions.
20 */
21
22#include <iprt/stream.h>
23#include <iprt/getopt.h>
24
25#include "VBoxManage.h"
26
27void printUsage(USAGECATEGORY u64Cmd)
28{
29#ifdef RT_OS_LINUX
30 bool fLinux = true;
31#else
32 bool fLinux = false;
33#endif
34#ifdef RT_OS_WINDOWS
35 bool fWin = true;
36#else
37 bool fWin = false;
38#endif
39#ifdef RT_OS_SOLARIS
40 bool fSolaris = true;
41#else
42 bool fSolaris = false;
43#endif
44#ifdef RT_OS_DARWIN
45 bool fDarwin = true;
46#else
47 bool fDarwin = false;
48#endif
49#ifdef VBOX_WITH_VRDP
50 bool fVRDP = true;
51#else
52 bool fVRDP = false;
53#endif
54
55 if (u64Cmd == USAGE_DUMPOPTS)
56 {
57 fLinux = true;
58 fWin = true;
59 fSolaris = true;
60 fDarwin = true;
61 fVRDP = true;
62 u64Cmd = USAGE_ALL;
63 }
64
65 RTPrintf("Usage:\n"
66 "\n");
67
68 if (u64Cmd == USAGE_ALL)
69 {
70 RTPrintf("VBoxManage [-v|--version] print version number and exit\n"
71 "VBoxManage [-q|--nologo] ... suppress the logo\n"
72 "\n");
73 }
74
75 if (u64Cmd & USAGE_LIST)
76 {
77 RTPrintf("VBoxManage list [--long|-l] vms|runningvms|ostypes|hostdvds|hostfloppies|\n"
78#if defined(VBOX_WITH_NETFLT)
79 " bridgedifs|hostonlyifs|dhcpservers|hostinfo|\n"
80#else
81 " bridgedifs|hostinfo|dhcpservers|\n"
82#endif
83 " hddbackends|hdds|dvds|floppies|\n"
84 " usbhost|usbfilters|systemproperties\n"
85 "\n");
86 }
87
88 if (u64Cmd & USAGE_SHOWVMINFO)
89 {
90 RTPrintf("VBoxManage showvminfo <uuid>|<name> [--details] [--statistics]\n"
91 " [--machinereadable]\n"
92 "\n");
93 }
94
95 if (u64Cmd & USAGE_REGISTERVM)
96 {
97 RTPrintf("VBoxManage registervm <filename>\n"
98 "\n");
99 }
100
101 if (u64Cmd & USAGE_UNREGISTERVM)
102 {
103 RTPrintf("VBoxManage unregistervm <uuid>|<name> [--delete]\n"
104 "\n");
105 }
106
107 if (u64Cmd & USAGE_CREATEVM)
108 {
109 RTPrintf("VBoxManage createvm --name <name>\n"
110 " [--ostype <ostype>]\n"
111 " [--register]\n"
112 " [--basefolder <path> | --settingsfile <path>]\n"
113 " [--uuid <uuid>]\n"
114 "\n");
115 }
116
117 if (u64Cmd & USAGE_MODIFYVM)
118 {
119 RTPrintf("VBoxManage modifyvm <uuid|name>\n"
120 " [--name <name>]\n"
121 " [--ostype <ostype>]\n"
122 " [--memory <memorysize in MB>]\n"
123 " [--vram <vramsize in MB>]\n"
124 " [--acpi on|off]\n"
125 " [--ioapic on|off]\n"
126 " [--pae on|off]\n"
127 " [--hwvirtex on|off|default]\n"
128 " [--nestedpaging on|off]\n"
129 " [--vtxvpid on|off]\n"
130 " [--cpus <number>]\n"
131 " [--monitorcount <number>]\n"
132 " [--accelerate3d <on|off>]\n"
133 " [--bioslogofadein on|off]\n"
134 " [--bioslogofadeout on|off]\n"
135 " [--bioslogodisplaytime <msec>]\n"
136 " [--bioslogoimagepath <imagepath>]\n"
137 " [--biosbootmenu disabled|menuonly|messageandmenu]\n"
138 " [--biossystemtimeoffset <msec>]\n"
139 " [--biospxedebug on|off]\n"
140 " [--boot<1-4> none|floppy|dvd|disk|net>]\n"
141 " [--hd<a|b|d> none|<uuid>|<filename>]\n"
142 " [--idecontroller PIIX3|PIIX4]\n"
143#ifdef VBOX_WITH_AHCI
144 " [--sata on|off]\n"
145 " [--sataportcount <1-30>]\n"
146 " [--sataport<1-30> none|<uuid>|<filename>]\n"
147 " [--sataideemulation<1-4> <1-30>]\n"
148#endif
149#ifdef VBOX_WITH_SCSI
150 " [--scsi on|off]\n"
151 " [--scsiport<1-16> none|<uuid>|<filename>]\n"
152 " [--scsitype LsiLogic|BusLogic]\n"
153#endif
154 " [--dvd none|<uuid>|<filename>|host:<drive>]\n"
155 " [--dvdpassthrough on|off]\n"
156 " [--floppy disabled|empty|<uuid>|\n"
157 " <filename>|host:<drive>]\n"
158#if defined(VBOX_WITH_NETFLT)
159 " [--nic<1-N> none|null|nat|bridged|intnet|hostonly]\n"
160#else /* !RT_OS_LINUX && !RT_OS_DARWIN */
161 " [--nic<1-N> none|null|nat|bridged|intnet]\n"
162#endif /* !RT_OS_LINUX && !RT_OS_DARWIN */
163 " [--nictype<1-N> Am79C970A|Am79C973"
164#ifdef VBOX_WITH_E1000
165 "|\n 82540EM|82543GC|82545EM"
166#endif
167 "]\n"
168 " [--cableconnected<1-N> on|off]\n"
169 " [--nictrace<1-N> on|off]\n"
170 " [--nictracefile<1-N> <filename>]\n"
171 " [--nicspeed<1-N> <kbps>]\n"
172 " [--bridgeadapter<1-N> none|<devicename>]\n"
173#if defined(VBOX_WITH_NETFLT)
174 " [--hostonlyadapter<1-N> none|<devicename>]\n"
175#endif
176 " [--intnet<1-N> <network name>]\n"
177 " [--natnet<1-N> <network>|default]\n"
178 " [--macaddress<1-N> auto|<mac>]\n"
179 " [--uart<1-N> off|<I/O base> <IRQ>]\n"
180 " [--uartmode<1-N> disconnected|\n"
181 " server <pipe>|\n"
182 " client <pipe>|\n"
183 " file <file>|\n"
184 " <devicename>]\n"
185#ifdef VBOX_WITH_MEM_BALLOONING
186 " [--guestmemoryballoon <balloonsize in MB>]\n"
187#endif
188 " [--gueststatisticsinterval <seconds>]\n"
189 );
190 RTPrintf(" [--audio none|null");
191 if (fWin)
192 {
193#ifdef VBOX_WITH_WINMM
194 RTPrintf( "|winmm|dsound");
195#else
196 RTPrintf( "|dsound");
197#endif
198 }
199 if (fSolaris)
200 {
201 RTPrintf( "|solaudio");
202 }
203 if (fLinux)
204 {
205 RTPrintf( "|oss"
206#ifdef VBOX_WITH_ALSA
207 "|alsa"
208#endif
209#ifdef VBOX_WITH_PULSE
210 "|pulse"
211#endif
212 );
213 }
214 if (fDarwin)
215 {
216 RTPrintf( "|coreaudio");
217 }
218 RTPrintf( "]\n");
219 RTPrintf(" [--audiocontroller ac97|sb16]\n"
220 " [--clipboard disabled|hosttoguest|guesttohost|\n"
221 " bidirectional]\n");
222 if (fVRDP)
223 {
224 RTPrintf(" [--vrdp on|off]\n"
225 " [--vrdpport default|<port>]\n"
226 " [--vrdpaddress <host>]\n"
227 " [--vrdpauthtype null|external|guest]\n"
228 " [--vrdpmulticon on|off]\n"
229 " [--vrdpreusecon on|off]\n");
230 }
231 RTPrintf(" [--usb on|off]\n"
232 " [--usbehci on|off]\n"
233 " [--snapshotfolder default|<path>]\n");
234 RTPrintf("\n");
235 }
236
237 if (u64Cmd & USAGE_IMPORTAPPLIANCE)
238 {
239 RTPrintf("VBoxManage import <ovf> [--dry-run|-n] [more options]\n"
240 " (run with -n to have options displayed for a particular OVF)\n\n");
241 }
242
243 if (u64Cmd & USAGE_EXPORTAPPLIANCE)
244 {
245 RTPrintf("VBoxManage export <machines> --output|-o <ovf>\n"
246 " [--legacy09]\n"
247 " [--vsys <number of virtual system>]\n"
248 " [--product <product name>]\n"
249 " [--producturl <product url>]\n"
250 " [--vendor <vendor name>]\n"
251 " [--vendorurl <vendor url>]\n"
252 " [--version <version info>]\n"
253 " [--eula <license text>]\n"
254 " [--eulafile <filename>]\n"
255 "\n");
256 }
257
258 if (u64Cmd & USAGE_STARTVM)
259 {
260 RTPrintf("VBoxManage startvm <uuid>|<name>\n");
261 RTPrintf(" [--type gui");
262 if (fVRDP)
263 RTPrintf( "|vrdp");
264 RTPrintf( "|headless]\n");
265 RTPrintf("\n");
266 }
267
268 if (u64Cmd & USAGE_CONTROLVM)
269 {
270 RTPrintf("VBoxManage controlvm <uuid>|<name>\n"
271 " pause|resume|reset|poweroff|savestate|\n"
272 " acpipowerbutton|acpisleepbutton|\n"
273 " keyboardputscancode <hex> [<hex> ...]|\n"
274 " injectnmi|\n"
275 " setlinkstate<1-N> on|off |\n"
276 " usbattach <uuid>|<address> |\n"
277 " usbdetach <uuid>|<address> |\n"
278 " dvdattach none|<uuid>|<filename>|host:<drive> |\n"
279 " floppyattach none|<uuid>|<filename>|host:<drive> |\n");
280 if (fVRDP)
281 {
282 RTPrintf(" vrdp on|off] |\n");
283 }
284 RTPrintf(" setvideomodehint <xres> <yres> <bpp> [display]|\n"
285 " setcredentials <username> <password> <domain>\n"
286 " [--allowlocallogon <yes|no>]\n"
287 "\n");
288 }
289
290 if (u64Cmd & USAGE_DISCARDSTATE)
291 {
292 RTPrintf("VBoxManage discardstate <uuid>|<name>\n"
293 "\n");
294 }
295
296 if (u64Cmd & USAGE_ADOPTSTATE)
297 {
298 RTPrintf("VBoxManage adoptstate <uuid>|<name> <state_file>\n"
299 "\n");
300 }
301
302 if (u64Cmd & USAGE_SNAPSHOT)
303 {
304 RTPrintf("VBoxManage snapshot <uuid>|<name>\n"
305 " take <name> [--description <desc>] |\n"
306 " discard <uuid>|<name> |\n"
307 " discardcurrent --state|--all |\n"
308 " edit <uuid>|<name>|--current\n"
309 " [--name <name>]\n"
310 " [--description <desc>] |\n"
311 " showvminfo <uuid>|<name>\n"
312 "\n");
313 }
314
315 if (u64Cmd & USAGE_OPENMEDIUM)
316 {
317 RTPrintf("VBoxManage openmedium disk|dvd|floppy <filename>\n"
318 " [--type normal|immutable|writethrough] (disk only)\n"
319 "\n");
320 }
321
322 if (u64Cmd & USAGE_CLOSEMEDIUM)
323 {
324 RTPrintf("VBoxManage closemedium disk|dvd|floppy <uuid>|<filename>\n"
325 "\n");
326 }
327
328 if (u64Cmd & USAGE_SHOWHDINFO)
329 {
330 RTPrintf("VBoxManage showhdinfo <uuid>|<filename>\n"
331 "\n");
332 }
333
334 if (u64Cmd & USAGE_CREATEHD)
335 {
336 RTPrintf("VBoxManage createhd --filename <filename>\n"
337 " --size <megabytes>\n"
338 " [--format VDI|VMDK|VHD] (default: VDI)\n"
339 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
340 " [--type normal|writethrough] (default: normal)\n"
341 " [--comment <comment>]\n"
342 " [--remember]\n"
343 "\n");
344 }
345
346 if (u64Cmd & USAGE_MODIFYHD)
347 {
348 RTPrintf("VBoxManage modifyhd <uuid>|<filename>\n"
349 " [--type normal|writethrough|immutable]\n"
350 " [--autoreset on|off]\n"
351 " [--compact]\n"
352 "\n");
353 }
354
355 if (u64Cmd & USAGE_CLONEHD)
356 {
357 RTPrintf("VBoxManage clonehd <uuid>|<filename> <outputfile>\n"
358 " [--format VDI|VMDK|VHD|RAW|<other>]\n"
359 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
360 " [--type normal|writethrough|immutable]\n"
361 " [--remember]\n"
362 "\n");
363 }
364
365 if (u64Cmd & USAGE_CONVERTFROMRAW)
366 {
367 RTPrintf("VBoxManage convertfromraw <filename> <outputfile>\n"
368 " [--format VDI|VMDK|VHD]\n"
369 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
370 "VBoxManage convertfromraw stdin <outputfile> <bytes>\n"
371 " [--format VDI|VMDK|VHD]\n"
372 " [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
373 "\n");
374 }
375
376 if (u64Cmd & USAGE_ADDISCSIDISK)
377 {
378 RTPrintf("VBoxManage addiscsidisk --server <name>|<ip>\n"
379 " --target <target>\n"
380 " [--port <port>]\n"
381 " [--lun <lun>]\n"
382 " [--encodedlun <lun>]\n"
383 " [--username <username>]\n"
384 " [--password <password>]\n"
385 " [--type normal|writethrough|immutable]\n"
386 " [--comment <comment>]\n"
387 " [--intnet]\n"
388 "\n");
389 }
390
391 if (u64Cmd & USAGE_GETEXTRADATA)
392 {
393 RTPrintf("VBoxManage getextradata global|<uuid>|<name>\n"
394 " <key>|enumerate\n"
395 "\n");
396 }
397
398 if (u64Cmd & USAGE_SETEXTRADATA)
399 {
400 RTPrintf("VBoxManage setextradata global|<uuid>|<name>\n"
401 " <key>\n"
402 " [<value>] (no value deletes key)\n"
403 "\n");
404 }
405
406 if (u64Cmd & USAGE_SETPROPERTY)
407 {
408 RTPrintf("VBoxManage setproperty hdfolder default|<folder> |\n"
409 " machinefolder default|<folder> |\n"
410 " vrdpauthlibrary default|<library> |\n"
411 " websrvauthlibrary default|null|<library> |\n"
412 " hwvirtexenabled yes|no\n"
413 " loghistorycount <value>\n"
414 "\n");
415 }
416
417 if (u64Cmd & USAGE_USBFILTER_ADD)
418 {
419 RTPrintf("VBoxManage usbfilter add <index,0-N>\n"
420 " --target <uuid>|<name>|global\n"
421 " --name <string>\n"
422 " --action ignore|hold (global filters only)\n"
423 " [--active yes|no] (yes)\n"
424 " [--vendorid <XXXX>] (null)\n"
425 " [--productid <XXXX>] (null)\n"
426 " [--revision <IIFF>] (null)\n"
427 " [--manufacturer <string>] (null)\n"
428 " [--product <string>] (null)\n"
429 " [--remote yes|no] (null, VM filters only)\n"
430 " [--serialnumber <string>] (null)\n"
431 " [--maskedinterfaces <XXXXXXXX>]\n"
432 "\n");
433 }
434
435 if (u64Cmd & USAGE_USBFILTER_MODIFY)
436 {
437 RTPrintf("VBoxManage usbfilter modify <index,0-N>\n"
438 " --target <uuid>|<name>|global\n"
439 " [--name <string>]\n"
440 " [--action ignore|hold] (global filters only)\n"
441 " [--active yes|no]\n"
442 " [--vendorid <XXXX>|\"\"]\n"
443 " [--productid <XXXX>|\"\"]\n"
444 " [--revision <IIFF>|\"\"]\n"
445 " [--manufacturer <string>|\"\"]\n"
446 " [--product <string>|\"\"]\n"
447 " [--remote yes|no] (null, VM filters only)\n"
448 " [--serialnumber <string>|\"\"]\n"
449 " [--maskedinterfaces <XXXXXXXX>]\n"
450 "\n");
451 }
452
453 if (u64Cmd & USAGE_USBFILTER_REMOVE)
454 {
455 RTPrintf("VBoxManage usbfilter remove <index,0-N>\n"
456 " --target <uuid>|<name>|global\n"
457 "\n");
458 }
459
460 if (u64Cmd & USAGE_SHAREDFOLDER_ADD)
461 {
462 RTPrintf("VBoxManage sharedfolder add <vmname>|<uuid>\n"
463 " --name <name> --hostpath <hostpath>\n"
464 " [--transient] [--readonly]\n"
465 "\n");
466 }
467
468 if (u64Cmd & USAGE_SHAREDFOLDER_REMOVE)
469 {
470 RTPrintf("VBoxManage sharedfolder remove <vmname>|<uuid>\n"
471 " --name <name> [--transient]\n"
472 "\n");
473 }
474
475 if (u64Cmd & USAGE_VM_STATISTICS)
476 {
477 RTPrintf("VBoxManage vmstatistics <vmname>|<uuid> [--reset]\n"
478 " [--pattern <pattern>] [--descriptions]\n"
479 "\n");
480 }
481
482#ifdef VBOX_WITH_GUEST_PROPS
483 if (u64Cmd & USAGE_GUESTPROPERTY)
484 usageGuestProperty();
485#endif /* VBOX_WITH_GUEST_PROPS defined */
486
487 if (u64Cmd & USAGE_METRICS)
488 {
489 RTPrintf("VBoxManage metrics list [*|host|<vmname> [<metric_list>]]\n"
490 " (comma-separated)\n\n"
491 "VBoxManage metrics setup\n"
492 " [--period <seconds>]\n"
493 " [--samples <count>]\n"
494 " [--list]\n"
495 " [*|host|<vmname> [<metric_list>]]\n\n"
496 "VBoxManage metrics query [*|host|<vmname> [<metric_list>]]\n\n"
497 "VBoxManage metrics collect\n"
498 " [--period <seconds>]\n"
499 " [--samples <count>]\n"
500 " [--list]\n"
501 " [--detach]\n"
502 " [*|host|<vmname> [<metric_list>]]\n"
503 "\n");
504 }
505#if defined(VBOX_WITH_NETFLT)
506 if (u64Cmd & USAGE_HOSTONLYIFS)
507 {
508 RTPrintf("VBoxManage hostonlyif ipconfig <name>\n"
509 " [--dhcp |\n"
510 " --ip<ipv4> [--netmask<ipv4> (def: 255.255.255.0)] |\n"
511 " --ipv6<ipv6> [--netmasklengthv6<length> (def: 64)]]\n"
512# if defined(RT_OS_WINDOWS)
513 " create |\n"
514 " remove <name>\n"
515# endif
516 "\n");
517 }
518#endif
519
520 if (u64Cmd & USAGE_DHCPSERVER)
521 {
522 RTPrintf("VBoxManage dhcpserver add|modify --netname <network_name> |\n"
523#if defined(VBOX_WITH_NETFLT)
524 " --ifname <hostonly_if_name>\n"
525#endif
526 " [--ip <ip_address>\n"
527 " --netmask <network_mask>\n"
528 " --lowerip <lower_ip>\n"
529 " --upperip <upper_ip>]\n"
530 " [--enable | --disable]\n"
531 "VBoxManage dhcpserver remove --netname <network_name> |\n"
532#if defined(VBOX_WITH_NETFLT)
533 " --ifname <hostonly_if_name>\n"
534#endif
535 "\n");
536 }
537}
538
539/**
540 * Print a usage synopsis and the syntax error message.
541 */
542int errorSyntax(USAGECATEGORY u64Cmd, const char *pszFormat, ...)
543{
544 va_list args;
545 showLogo(); // show logo even if suppressed
546#ifndef VBOX_ONLY_DOCS
547 if (g_fInternalMode)
548 printUsageInternal(u64Cmd);
549 else
550 printUsage(u64Cmd);
551#endif /* !VBOX_ONLY_DOCS */
552 va_start(args, pszFormat);
553 RTPrintf("\n"
554 "Syntax error: %N\n", pszFormat, &args);
555 va_end(args);
556 return 1;
557}
558
559/**
560 * Print an error message without the syntax stuff.
561 */
562int errorArgument(const char *pszFormat, ...)
563{
564 va_list args;
565 va_start(args, pszFormat);
566 RTPrintf("error: %N\n", pszFormat, &args);
567 va_end(args);
568 return 1;
569}
570
Note: See TracBrowser for help on using the repository browser.

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