Changeset 106001 in vbox for trunk/doc/manual/en_US/man_VBoxManage-guestcontrol.xml

Timestamp:

Sep 10, 2024 11:15:32 AM (6 months ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

164747

Message:

doc/manual/man_VBoxManage-*: Updated a variety of the VBoxManage help
files to improve readability, corrected some typos, and made various
other corrections.

src/VBox/*: Updated some comments and log messages for a variety of
source files to correct the spelling of 'suppress'. A few APIC files
and USB files use 'supress' in variable names or manifest constants but
those were not changed.

File:

• trunk/doc/manual/en_US/man_VBoxManage-guestcontrol.xml (modified) (13 diffs)

trunk/doc/manual/en_US/man_VBoxManage-guestcontrol.xml

@@ -371 +371 @@
       <arg>--source=<replaceable>guest-additions.ISO</replaceable></arg>
       <arg>--wait-start</arg>
-      <arg>-- <arg rep="repeat"><replaceable>argument</replaceable></arg></arg>
+      <arg>--<arg rep="repeat"><replaceable>argument</replaceable></arg></arg>
     </cmdsynopsis>
 
@@ -442 +442 @@
         specify an empty password. On OSes such as Windows, you might
         need to adjust the security policy to permit user accounts with
-        an empty password. In additional, global domain rules might
+        an empty password. In addition, global domain rules might
         apply and therefore cannot be changed.
       </para>
@@ -461 +461 @@
               Specifies the password for the specified user. If you do
               not specify a password on the command line or if the
-              password file is empty, the specified user needs to have
+              password is empty, the specified user needs to have
               an empty password.
             </para></listitem>
@@ -468 +468 @@
           <term><option>--passwordfile=<replaceable>filename</replaceable></option></term>
           <listitem><para>
-              Specifies the absolute path to a file on the guest OS that
+              Specifies the absolute path to a file on the host system that
               contains the password for the specified user. If the
               password file is empty or if you do not specify a password
@@ -478 +478 @@
           <term><option>--username=<replaceable>username</replaceable></option></term>
           <listitem><para>
-              Specifies an existing user on the guest OS that runs the
-              process. If unspecified, the host user runs the process.
+              Specifies an existing user in the guest OS that runs the
+              process. If unspecified, the name of the user on the host
+              invoking the <command>VBoxManage</command> command will be
+              used as the username for the guest OS login.
             </para></listitem>
         </varlistentry>
@@ -487 +489 @@
       <title>Guest Process Restrictions</title>
       <para>
-        By default, you can run up to five guest processes
-        simultaneously. If a new guest process starts and would exceed
-        this limit, the oldest not-running guest process is discarded to
-        run the new process. You cannot retrieve output from a discarded
-        guest process. If all five guest processes are active and
-        running, attempting to start a new guest process fails.
-      </para>
-      <para>
-        You can modify the guest process execution limit in two ways:
-      </para>
-      <itemizedlist>
-        <listitem><para>
-            Use the <command>VBoxManage setproperty</command> command to
-            update the
-            <literal>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</literal>
-            guest property value.
-          </para></listitem>
-        <listitem><para>
-            Use the <command>VBoxService</command> command and specify
-            the
-            <option>--control-procs-max-kept=<replaceable>value</replaceable></option>
-            option.
-          </para></listitem>
-      </itemizedlist>
-      <para>
-        After you change the limit, you must restart the guest OS.
-      </para>
-      <para>
-        You can serve an unlimited number guest processes by specifing a
-        value of <literal>0</literal>, however this action is not
-        recommended.
+        By default, you can run up to 255 guest processes simultaneously.
+        If attempting to start a new guest process would exceed
+        this limit and there are inactive guest processes then the the
+        oldest inactive guest process is discarded to run the new process.
+        You cannot retrieve the output from a discarded guest process. If
+        all 255 guest processes are active and running, attempting to start
+        a new guest process fails.
       </para>
     </refsect2>
     <refsect2 id="vboxmanage-guestcontrol-run">
-      <title>Run a Command on the guest</title>
+      <title>Run a Command in the guest</title>
       <remark role="help-copy-synopsis"/>
       <para>
         The <command>VBoxManage guestcontrol
         <replaceable>vmname</replaceable> run</command> command enables
-        you to execute a program on the guest VM. Standard input,
+        you to execute a program in the guest VM. Standard input,
         standard output, and standard error are redirected from the VM
         to the host system until the program completes.
@@ -532 +510 @@
       <note>
         <para>
-          The Windows OS imposes certain limitations for graphical
-          applications. See <xref linkend="KnownIssues" />.
+          Microsoft Windows imposes certain limitations when running
+          graphical user interface applications launched using
+          <command>VBoxManage guestcontrol run</command>. See
+          <xref linkend="KnownIssues" />.
         </para>
       </note>
@@ -541 +521 @@
           <listitem><para>
               Specifies the absolute path of the executable program to
-              run on the guest VM. For example:
+              run in the guest VM. For example:
               <filename>C:\Windows\System32\calc.exe</filename>.
+            </para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><option>--arg0=<replaceable>alternate-executable-name</replaceable></option></term>
+          <listitem><para>
+              Specifies an alternate name (i.e. arg0 or argv[0]) for the
+              executable being run in the guest.
             </para></listitem>
         </varlistentry>
@@ -584 +571 @@
             </para><para>
               Use the
-              <option>--putenv=<replaceable>NAME</replaceable>=[<replaceable>value</replaceable>]</option>
+              <option>--putenv=<replaceable>NAME</replaceable>=</option>
               option to unset the environment variable specified by
               <replaceable>NAME</replaceable>.
@@ -669 +656 @@
         </varlistentry>
         <varlistentry>
-          <term><option>--[<replaceable>argument</replaceable>...]</option></term>
-          <listitem><para>
-              Specifies the name of the program and any arguments to
-              pass to the program.
+          <term><option>-- [<replaceable>argument</replaceable>...]</option></term>
+          <listitem><para>
+              Specifies one or more arguments to pass to the program
+              being run in the guest.
             </para><para>
               Ensure that any command argument that includes spaces is
@@ -686 +673 @@
         The <command>VBoxManage guestcontrol
         <replaceable>vmname</replaceable> start</command> command
-        enables you to execute a guest program until it completes.
+        enables you to execute a guest program and returns after
+        the command has been successfully started.  The invoked
+        command doesn't wait until all data from stdout or stderr
+        has been read before returning.
       </para>
       <note>
         <para>
-          The Windows OS imposes certain limitations for graphical
-          applications. See <xref linkend="KnownIssues" />.
+          Microsoft Windows imposes certain limitations when running
+          graphical user interface applications launched using
+          <command>VBoxManage guestcontrol start</command>. See
+          <xref linkend="KnownIssues" />.
         </para>
       </note>
@@ -970 +962 @@
           <term><literal><replaceable>guest-file</replaceable> [<replaceable>guest-file</replaceable>...]</literal></term>
           <listitem><para>
-              Specifies an absolute path of one or more file to remove
+              Specifies an absolute path of one or more files to remove
               from the guest VM. You can use wildcards to specify the
               file names. For example,
@@ -1431 +1423 @@
     </para>
   <para>
-    The default behavior of argument 0 is to either use
-    the value from <option>--exe</option>, or, if not set, the first
-    value passed after <option>--</option>.
+    The default value of argument 0 (i.e. arg0 or argv[0]) is the value
+    from the <option>--exe</option> option unless the <option>--arg0</option>
+    option has been supplied.
   </para>
   </refsect1>