/* $Id: VBoxManageHelp.cpp 27927 2010-04-01 09:19:12Z vboxsync $ */ /** @file * VBoxManage - help and other message output. */ /* * Copyright (C) 2006-2009 Sun Microsystems, Inc. * * This file is part of VirtualBox Open Source Edition (OSE), as * available from http://www.virtualbox.org. This file is free software; * you can redistribute it and/or modify it under the terms of the GNU * General Public License (GPL) as published by the Free Software * Foundation, in version 2 as it comes in the "COPYING" file of the * VirtualBox OSE distribution. VirtualBox OSE is distributed in the * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. * * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa * Clara, CA 95054 USA or visit http://www.sun.com if you need * additional information or have any questions. */ /******************************************************************************* * Header Files * *******************************************************************************/ #include #include #include #include #include #include "VBoxManage.h" void showLogo(void) { static bool s_fShown; /* show only once */ if (!s_fShown) { RTPrintf(VBOX_PRODUCT" Command Line Management Interface Version " VBOX_VERSION_STRING "\n" "(C) 2005-" VBOX_C_YEAR " " VBOX_VENDOR "\n" "All rights reserved.\n" "\n"); s_fShown = true; } } void printUsage(USAGECATEGORY u64Cmd) { #ifdef RT_OS_LINUX bool fLinux = true; #else bool fLinux = false; #endif #ifdef RT_OS_WINDOWS bool fWin = true; #else bool fWin = false; #endif #ifdef RT_OS_SOLARIS bool fSolaris = true; #else bool fSolaris = false; #endif #ifdef RT_OS_FREEBSD bool fFreeBSD = true; #else bool fFreeBSD = false; #endif #ifdef RT_OS_DARWIN bool fDarwin = true; #else bool fDarwin = false; #endif #ifdef VBOX_WITH_VRDP bool fVRDP = true; #else bool fVRDP = false; #endif #ifdef VBOX_WITH_VBOXSDL bool fVBoxSDL = true; #else bool fVBoxSDL = false; #endif if (u64Cmd == USAGE_DUMPOPTS) { fLinux = true; fWin = true; fSolaris = true; fFreeBSD = true; fDarwin = true; fVRDP = true; fVBoxSDL = true; u64Cmd = USAGE_ALL; } RTPrintf("Usage:\n" "\n"); if (u64Cmd == USAGE_ALL) { RTPrintf("VBoxManage [-v|--version] print version number and exit\n" "VBoxManage [-q|--nologo] ... suppress the logo\n" "\n"); } if (u64Cmd & USAGE_LIST) { RTPrintf("VBoxManage list [--long|-l] vms|runningvms|ostypes|hostdvds|hostfloppies|\n" #if defined(VBOX_WITH_NETFLT) " bridgedifs|hostonlyifs|dhcpservers|hostinfo|\n" #else " bridgedifs|dhcpservers|hostinfo|\n" #endif " hostcpuids|hddbackends|hdds|dvds|floppies|\n" " usbhost|usbfilters|systemproperties\n" " natrules<1-N> \n" "\n"); } if (u64Cmd & USAGE_SHOWVMINFO) { RTPrintf("VBoxManage showvminfo | [--details] [--statistics]\n" " [--machinereadable]\n" "\n"); } if (u64Cmd & USAGE_REGISTERVM) { RTPrintf("VBoxManage registervm \n" "\n"); } if (u64Cmd & USAGE_UNREGISTERVM) { RTPrintf("VBoxManage unregistervm | [--delete]\n" "\n"); } if (u64Cmd & USAGE_CREATEVM) { RTPrintf("VBoxManage createvm --name \n" " [--ostype ]\n" " [--register]\n" " [--basefolder | --settingsfile ]\n" " [--uuid ]\n" "\n"); } if (u64Cmd & USAGE_MODIFYVM) { RTPrintf("VBoxManage modifyvm \n" " [--name ]\n" " [--ostype ]\n" " [--memory ]\n" " [--vram ]\n" " [--acpi on|off]\n" " [--ioapic on|off]\n" " [--pae on|off]\n" " [--hpet on|off]\n" " [--hwvirtex on|off]\n" " [--nestedpaging on|off]\n" " [--largepages on|off]\n" " [--vtxvpid on|off]\n" " [--synthcpu on|off]\n" " [--cpuidset ]\n" " [--cpuidremove ]\n" " [--cpuidremoveall]\n" " [--hardwareuuid ]\n" " [--cpus ]\n" " [--rtcuseutc]\n" " [--monitorcount ]\n" " [--accelerate3d on|off]\n" #ifdef VBOX_WITH_VIDEOHWACCEL " [--accelerate2dvideo on|off]\n" #endif " [--firmware bios|efi|efi32|efi64]\n" " [--bioslogofadein on|off]\n" " [--bioslogofadeout on|off]\n" " [--bioslogodisplaytime ]\n" " [--bioslogoimagepath ]\n" " [--biosbootmenu disabled|menuonly|messageandmenu]\n" " [--biossystemtimeoffset ]\n" " [--biospxedebug on|off]\n" " [--boot<1-4> none|floppy|dvd|disk|net>]\n" #if defined(VBOX_WITH_NETFLT) " [--nic<1-N> none|null|nat|bridged|intnet|hostonly]\n" #else /* !RT_OS_LINUX && !RT_OS_DARWIN */ " [--nic<1-N> none|null|nat|bridged|intnet]\n" #endif /* !RT_OS_LINUX && !RT_OS_DARWIN */ " [--nictype<1-N> Am79C970A|Am79C973" #ifdef VBOX_WITH_E1000 "|\n 82540EM|82543GC|82545EM" #endif #ifdef VBOX_WITH_VIRTIO "|\n virtio" #endif /* VBOX_WITH_VIRTIO */ "]\n" " [--cableconnected<1-N> on|off]\n" " [--nictrace<1-N> on|off]\n" " [--nictracefile<1-N> ]\n" " [--nicspeed<1-N> ]\n" " [--bridgeadapter<1-N> none|]\n" #if defined(VBOX_WITH_NETFLT) " [--hostonlyadapter<1-N> none|]\n" #endif " [--intnet<1-N> ]\n" " [--natnet<1-N> |default]\n" " [--natsettings<1-N> \"[],[],[],\n" " [],[]\"]\n" " [--natpf<1-N> \"[],tcp|udp,\n" " [],,\n" " [],\"]\n" " [--natpf<1-N> delete ]\n" " [--nattftpprefix<1-N> ]\n" " [--nattftpfile<1-N> ]\n" " [--nattftpserver<1-N> ]\n" " [--natdnspassdomain<1-N> on|off]\n" " [--natdnsproxy<1-N> on|off]\n" " [--natdnshostresolver<1-N> on|off]\n" " [--macaddress<1-N> auto|]\n" " [--mouse ps2|usb|usbtablet\n" " [--keyboard ps2|usb\n" " [--uart<1-N> off| ]\n" " [--uartmode<1-N> disconnected|\n" " server |\n" " client |\n" " file |\n" " ]\n" " [--guestmemoryballoon ]\n" " [--gueststatisticsinterval ]\n" ); RTPrintf(" [--audio none|null"); if (fWin) { #ifdef VBOX_WITH_WINMM RTPrintf( "|winmm|dsound"); #else RTPrintf( "|dsound"); #endif } if (fSolaris) { RTPrintf( "|solaudio" #ifdef VBOX_WITH_SOLARIS_OSS "|oss" #endif ); } if (fLinux) { RTPrintf( "|oss" #ifdef VBOX_WITH_ALSA "|alsa" #endif #ifdef VBOX_WITH_PULSE "|pulse" #endif ); } if (fFreeBSD) { RTPrintf( "|oss" #ifdef VBOX_WITH_PULSE "|pulse" #endif ); } if (fDarwin) { RTPrintf( "|coreaudio"); } RTPrintf( "]\n"); RTPrintf(" [--audiocontroller ac97|sb16]\n" " [--clipboard disabled|hosttoguest|guesttohost|\n" " bidirectional]\n"); if (fVRDP) { RTPrintf(" [--vrdp on|off]\n" " [--vrdpport default|]\n" " [--vrdpaddress ]\n" " [--vrdpauthtype null|external|guest]\n" " [--vrdpmulticon on|off]\n" " [--vrdpreusecon on|off]\n"); } RTPrintf(" [--usb on|off]\n" " [--usbehci on|off]\n" " [--snapshotfolder default|]\n" " [--teleporter on|off]\n" " [--teleporterport ]\n" " [--teleporteraddress \n" " [--teleporterpassword ]\n" #if 0 " [--iomgr simple|async]\n" " [--iobackend buffered|unbuffered]\n" " [--iocache on|off]\n" " [--iocachesize ]\n" " [--iobandwidthmax ]\n" #endif ); RTPrintf("\n"); } if (u64Cmd & USAGE_IMPORTAPPLIANCE) { RTPrintf("VBoxManage import [--dry-run|-n] [more options]\n" " (run with -n to have options displayed\n" " for a particular OVF)\n\n"); } if (u64Cmd & USAGE_EXPORTAPPLIANCE) { RTPrintf("VBoxManage export --output|-o \n" " [--legacy09]\n" " [--vsys ]\n" " [--product ]\n" " [--producturl ]\n" " [--vendor ]\n" " [--vendorurl ]\n" " [--version ]\n" " [--eula ]\n" " [--eulafile ]\n" "\n"); } if (u64Cmd & USAGE_STARTVM) { RTPrintf("VBoxManage startvm |\n"); RTPrintf(" [--type gui"); if (fVBoxSDL) RTPrintf( "|sdl"); if (fVRDP) RTPrintf( "|vrdp"); RTPrintf( "|headless]\n"); RTPrintf("\n"); } if (u64Cmd & USAGE_CONTROLVM) { RTPrintf("VBoxManage controlvm |\n" " pause|resume|reset|poweroff|savestate|\n" " acpipowerbutton|acpisleepbutton|\n" " keyboardputscancode [ ...]|\n" " injectnmi|\n" " setlinkstate<1-N> on|off |\n" #ifdef VBOX_DYNAMIC_NET_ATTACH #if defined(VBOX_WITH_NETFLT) " nic<1-N> null|nat|bridged|intnet|hostonly\n" " [] |\n" #else /* !RT_OS_LINUX && !RT_OS_DARWIN */ " nic<1-N> null|nat|bridged|intnet\n" " [] |\n" #endif /* !RT_OS_LINUX && !RT_OS_DARWIN */ " nictrace<1-N> on|off\n" " nictracefile<1-N> \n" #endif /* VBOX_DYNAMIC_NET_ATTACH */ " guestmemoryballoon ]\n" " gueststatisticsinterval ]\n" " usbattach |
|\n" " usbdetach |
|\n"); if (fVRDP) { RTPrintf(" vrdp on|off |\n"); RTPrintf(" vrdpport default| |\n"); } RTPrintf(" setvideomodehint [display] |\n" " setcredentials \n" " [--allowlocallogon ] |\n" " teleport --host --port \n" " [--maxdowntime ] [--password password]\n" "\n"); } if (u64Cmd & USAGE_DISCARDSTATE) { RTPrintf("VBoxManage discardstate |\n" "\n"); } if (u64Cmd & USAGE_ADOPTSTATE) { RTPrintf("VBoxManage adoptstate | \n" "\n"); } if (u64Cmd & USAGE_SNAPSHOT) { RTPrintf("VBoxManage snapshot |\n" " take [--description ] [--pause] |\n" " delete | |\n" " restore | |\n" " restorecurrent |\n" " edit ||--current\n" " [--name ]\n" " [--description ] |\n" " showvminfo |\n" "\n"); } if (u64Cmd & USAGE_OPENMEDIUM) { RTPrintf("VBoxManage openmedium disk|dvd|floppy \n" " [--type normal|immutable|writethrough] (disk only)\n" " [--uuid ]\n" " [--parentuuid ] (disk only)\n" "\n"); } if (u64Cmd & USAGE_CLOSEMEDIUM) { RTPrintf("VBoxManage closemedium disk|dvd|floppy |\n" " [--delete]\n" "\n"); } if (u64Cmd & USAGE_STORAGEATTACH) { RTPrintf("VBoxManage storageattach \n" " --storagectl \n" " --port \n" " --device \n" " [--type dvddrive|hdd|fdd\n" " --medium none|emptydrive|uuid|filename|host:]\n" " [--passthrough on|off]\n" " [--forceunmount]\n" "\n"); } if (u64Cmd & USAGE_STORAGECONTROLLER) { RTPrintf("VBoxManage storagectl \n" " --name \n" " [--add ide|sata|scsi|floppy|sas]\n" " [--controller LSILogic|LSILogicSAS|BusLogic|IntelAHCI|\n" " PIIX3|PIIX4|ICH6|I82078]\n" " [--sataideemulation<1-4> <1-30>]\n" " [--sataportcount <1-30>]\n" " [--remove]\n" "\n"); } if (u64Cmd & USAGE_SHOWHDINFO) { RTPrintf("VBoxManage showhdinfo |\n" "\n"); } if (u64Cmd & USAGE_CREATEHD) { RTPrintf("VBoxManage createhd --filename \n" " --size \n" " [--format VDI|VMDK|VHD] (default: VDI)\n" " [--variant Standard,Fixed,Split2G,Stream,ESX]\n" " [--type normal|writethrough] (default: normal)\n" " [--comment ]\n" " [--remember]\n" "\n"); } if (u64Cmd & USAGE_MODIFYHD) { RTPrintf("VBoxManage modifyhd |\n" " [--type normal|writethrough|immutable]\n" " [--autoreset on|off]\n" " [--compact]\n" "\n"); } if (u64Cmd & USAGE_CLONEHD) { RTPrintf("VBoxManage clonehd | \n" " [--format VDI|VMDK|VHD|RAW|]\n" " [--variant Standard,Fixed,Split2G,Stream,ESX]\n" " [--type normal|writethrough|immutable]\n" " [--remember] [--existing]\n" "\n"); } if (u64Cmd & USAGE_CONVERTFROMRAW) { RTPrintf("VBoxManage convertfromraw \n" " [--format VDI|VMDK|VHD]\n" " [--variant Standard,Fixed,Split2G,Stream,ESX]\n" "VBoxManage convertfromraw stdin \n" " [--format VDI|VMDK|VHD]\n" " [--variant Standard,Fixed,Split2G,Stream,ESX]\n" "\n"); } if (u64Cmd & USAGE_ADDISCSIDISK) { RTPrintf("VBoxManage addiscsidisk --server |\n" " --target \n" " [--port ]\n" " [--lun ]\n" " [--encodedlun ]\n" " [--username ]\n" " [--password ]\n" " [--type normal|writethrough|immutable]\n" " [--intnet]\n" "\n"); } if (u64Cmd & USAGE_GETEXTRADATA) { RTPrintf("VBoxManage getextradata global||\n" " |enumerate\n" "\n"); } if (u64Cmd & USAGE_SETEXTRADATA) { RTPrintf("VBoxManage setextradata global||\n" " \n" " [] (no value deletes key)\n" "\n"); } if (u64Cmd & USAGE_SETPROPERTY) { RTPrintf("VBoxManage setproperty hdfolder default| |\n" " machinefolder default| |\n" " vrdpauthlibrary default| |\n" " websrvauthlibrary default|null| |\n" " loghistorycount \n" "\n"); } if (u64Cmd & USAGE_USBFILTER_ADD) { RTPrintf("VBoxManage usbfilter add \n" " --target ||global\n" " --name \n" " --action ignore|hold (global filters only)\n" " [--active yes|no] (yes)\n" " [--vendorid ] (null)\n" " [--productid ] (null)\n" " [--revision ] (null)\n" " [--manufacturer ] (null)\n" " [--product ] (null)\n" " [--remote yes|no] (null, VM filters only)\n" " [--serialnumber ] (null)\n" " [--maskedinterfaces ]\n" "\n"); } if (u64Cmd & USAGE_USBFILTER_MODIFY) { RTPrintf("VBoxManage usbfilter modify \n" " --target ||global\n" " [--name ]\n" " [--action ignore|hold] (global filters only)\n" " [--active yes|no]\n" " [--vendorid |\"\"]\n" " [--productid |\"\"]\n" " [--revision |\"\"]\n" " [--manufacturer |\"\"]\n" " [--product |\"\"]\n" " [--remote yes|no] (null, VM filters only)\n" " [--serialnumber |\"\"]\n" " [--maskedinterfaces ]\n" "\n"); } if (u64Cmd & USAGE_USBFILTER_REMOVE) { RTPrintf("VBoxManage usbfilter remove \n" " --target ||global\n" "\n"); } if (u64Cmd & USAGE_SHAREDFOLDER_ADD) { RTPrintf("VBoxManage sharedfolder add |\n" " --name --hostpath \n" " [--transient] [--readonly]\n" "\n"); } if (u64Cmd & USAGE_SHAREDFOLDER_REMOVE) { RTPrintf("VBoxManage sharedfolder remove |\n" " --name [--transient]\n" "\n"); } if (u64Cmd & USAGE_VM_STATISTICS) { RTPrintf("VBoxManage vmstatistics | [--reset]\n" " [--pattern ] [--descriptions]\n" "\n"); } #ifdef VBOX_WITH_GUEST_PROPS if (u64Cmd & USAGE_GUESTPROPERTY) usageGuestProperty(); #endif /* VBOX_WITH_GUEST_PROPS defined */ #ifdef VBOX_WITH_GUEST_CONTROL if (u64Cmd & USAGE_GUESTCONTROL) usageGuestControl(); #endif /* VBOX_WITH_GUEST_CONTROL defined */ if (u64Cmd & USAGE_METRICS) { RTPrintf("VBoxManage metrics list [*|host| []]\n" " (comma-separated)\n\n" "VBoxManage metrics setup\n" " [--period ]\n" " [--samples ]\n" " [--list]\n" " [*|host| []]\n\n" "VBoxManage metrics query [*|host| []]\n\n" "VBoxManage metrics enable\n" " [--list]\n" " [*|host| []]\n\n" "VBoxManage metrics disable\n" " [--list]\n" " [*|host| []]\n\n" "VBoxManage metrics collect\n" " [--period ]\n" " [--samples ]\n" " [--list]\n" " [--detach]\n" " [*|host| []]\n" "\n"); } #if defined(VBOX_WITH_NETFLT) if (u64Cmd & USAGE_HOSTONLYIFS) { RTPrintf("VBoxManage hostonlyif ipconfig \n" " [--dhcp |\n" " --ip [--netmask (def: 255.255.255.0)] |\n" " --ipv6 [--netmasklengthv6 (def: 64)]]\n" # if defined(RT_OS_WINDOWS) " create |\n" " remove \n" # endif "\n"); } #endif if (u64Cmd & USAGE_DHCPSERVER) { RTPrintf("VBoxManage dhcpserver add|modify --netname |\n" #if defined(VBOX_WITH_NETFLT) " --ifname \n" #endif " [--ip \n" " --netmask \n" " --lowerip \n" " --upperip ]\n" " [--enable | --disable]\n\n" "VBoxManage dhcpserver remove --netname |\n" #if defined(VBOX_WITH_NETFLT) " --ifname \n" #endif "\n"); } } /** * Print a usage synopsis and the syntax error message. */ int errorSyntax(USAGECATEGORY u64Cmd, const char *pszFormat, ...) { va_list args; showLogo(); // show logo even if suppressed #ifndef VBOX_ONLY_DOCS if (g_fInternalMode) printUsageInternal(u64Cmd); else printUsage(u64Cmd); #endif /* !VBOX_ONLY_DOCS */ va_start(args, pszFormat); RTPrintf("\n" "Syntax error: %N\n", pszFormat, &args); va_end(args); return 1; } /** * errorSyntax for RTGetOpt users. * * @returns 1. * * @param fUsageCategory The usage category of the command. * @param rc The RTGetOpt return code. * @param pValueUnion The value union. */ int errorGetOpt(USAGECATEGORY fUsageCategory, int rc, union RTGETOPTUNION const *pValueUnion) { showLogo(); // show logo even if suppressed #ifndef VBOX_ONLY_DOCS if (g_fInternalMode) printUsageInternal(fUsageCategory); else printUsage(fUsageCategory); #endif /* !VBOX_ONLY_DOCS */ if (rc == VINF_GETOPT_NOT_OPTION) return RTPrintf("error: Invalid parameter '%s'\n", pValueUnion->psz); if (rc > 0) { if (RT_C_IS_PRINT(rc)) return RTPrintf("error: Invalid option -%c\n", rc); return RTPrintf("error: Invalid option case %i\n", rc); } if (rc == VERR_GETOPT_UNKNOWN_OPTION) return RTPrintf("error: unknown option: %s\n", pValueUnion->psz); if (pValueUnion->pDef) return RTPrintf("error: %s: %Rrs\n", pValueUnion->pDef->pszLong, rc); return RTPrintf("error: %Rrs\n", rc); } /** * Print an error message without the syntax stuff. */ int errorArgument(const char *pszFormat, ...) { va_list args; va_start(args, pszFormat); RTPrintf("error: %N\n", pszFormat, &args); va_end(args); return 1; }