No documentation exists for GAs' "VBoxControl"

[Socratis]

As the title plainly says, there is no documentation whatsoever for the "VBoxControl" program that gets installed with the GAs. No mention of the syntax, parameters, logic, effects. None, except the command line syntax help.

In fact, it would be nice to mention what the rest of the programs installed with the GAs also do. Even briefly.

[Frank Mehnert]

See section 4.7 in the user manual. Probably not very extensive documentation but should be sufficient for a start.

[Socratis]

Oh, come on Frank, "probably not very extensive"? Try not-existent. "sufficient for a start"? Only if you mean a start for a proper chapter on the options.

Of course I did take a look at Ch. 4.7, that's exactly why I created the ticket. Here are the available options from VBoxControl:

VBoxControl [-V|--version]           print version number and exit
VBoxControl --nologo ...             suppress the logo

VBoxControl getvideoacceleration
VBoxControl setvideoacceleration     <on|off>
VBoxControl videoflags               <get|set|clear|delete> [hex mask]
VBoxControl listcustommodes
VBoxControl addcustommode            <width> <height> <bpp>
VBoxControl removecustommode         <width> <height> <bpp>
VBoxControl setvideomode             <width> <height> <bpp> <screen>
VBoxControl guestproperty            get <property> [--verbose]
VBoxControl guestproperty            set <property> [<value> [--flags <flags>]]
VBoxControl guestproperty            delete|unset <property>
VBoxControl guestproperty            enumerate [--patterns <patterns>]
VBoxControl guestproperty            wait <patterns>
                                     [--timestamp <last timestamp>]
                                     [--timeout <timeout in ms>
VBoxControl sharedfolder             list [-automount]
VBoxControl writecoredump
VBoxControl writelog [-n|--no-newline] [--] <msg>
VBoxControl takesnapshot
VBoxControl savestate
VBoxControl suspend
VBoxControl poweroff
VBoxControl help                     [command]
VBoxControl version

And here's what is semi-documented (i.e. there is only an example output), and mind you, that's the only VBoxControl reference in the Manual:

VBoxControl guestproperty enumerate

And please don't tell me that some like "VBoxControl takesnapshot" are self-documented (and I'll agree to a degree), but:

• what are the exact "VBoxControl videoflags set" options? In hex please, because there's a "hex mask" option which I have no clue whatsoever what it does!
• what exactly does the "writelog" do? Add a custom message to "VBox.log"?
• if I switch the video acceleration, do I need to restart the guest, or is it an on-the-fly change? Is it the same as enable/disable 3D acceleration from the VM settings?
• are the "VBoxControl addcustommode" options the same as the "VBoxManage setvideomodehint"?
• do the last two command options mean that I'm actually modifying the .vbox of the guest from within the guest? Seriously? That alone should be in big, bold letters, with a huge warning sign!!!

Or if you want me to put the bug in another way (which is actually the same exact bug, in other words):

The command "VBoxControl help [command]" does not work on a guest, it always returns empty.