Changeset 94218 in vbox for trunk

Timestamp:

Mar 14, 2022 9:02:16 AM (3 years ago)

Author:

vboxsync

Message:

doc/manual,FE/VBoxManage: Convert modifymedium command to refentry documentation, ​bugref:9186

Location:

trunk

Files:

• doc/manual/Config.kmk (modified) (1 diff)
• doc/manual/en_US/man_VBoxManage-modifymedium.xml (modified) (2 diffs)
• doc/manual/en_US/user_VBoxManage.xml (modified) (1 diff)
• doc/manual/ru_RU/man_VBoxManage-modifymedium.xml (modified) (2 diffs)
• src/VBox/Frontends/VBoxManage/VBoxManage.cpp (modified) (1 diff)
• src/VBox/Frontends/VBoxManage/VBoxManage.h (modified) (1 diff)
• src/VBox/Frontends/VBoxManage/VBoxManageDisk.cpp (modified) (7 diffs)
• src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp (modified) (1 diff)

trunk/doc/manual/Config.kmk

@@ -70 +70 @@
         man_VBoxManage-showmediuminfo.xml \
         man_VBoxManage-createmedium.xml \
+        man_VBoxManage-modifymedium.xml \
         man_VBoxManage-clonemedium.xml \
         man_VBoxManage-mediumproperty.xml \

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

@@ -20 +20 @@
 <refentry id="vboxmanage-modifymedium" lang="en">
   <refentryinfo>
-    <pubdate>August 2019</pubdate>
+    <pubdate>$Date$</pubdate>
     <title>VBoxManage modifymedium</title>
   </refentryinfo>
@@ -32 +32 @@
     <refname>VBoxManage-modifymedium</refname>
     <refpurpose>change the characteristics of an existing disk image</refpurpose>
-    <refclass>Oracle VM VirtualBox</refclass>
+    <refclass>&product-name;</refclass>
   </refnamediv>
 

trunk/doc/manual/en_US/user_VBoxManage.xml

@@ -355 +355 @@
   <xi:include href="user_man_VBoxManage-createmedium.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <sect1 id="vboxmanage-modifymedium">
-
-    <title>VBoxManage modifymedium</title>
-
-    <para>
-      With the <command>modifymedium</command> command, you can change
-      the characteristics of a disk image after it has been created.
-    </para>
-
-<screen>VBoxManage modifymedium  [disk|dvd|floppy]    &lt;uuid|filename&gt;
-                         [--type normal|writethrough|immutable|shareable|
-                                 readonly|multiattach]
-                         [--autoreset on|off]
-                         [--property &lt;name=[value]&gt;]
-                         [--compact]
-                         [--resize &lt;megabytes&gt;|--resizebyte &lt;bytes&gt;]
-                         [--move &lt;path&gt;]
-                         [--setlocation &lt;path&gt;]</screen>
-
-    <note>
-      <para>
-        For compatibility with earlier versions of &product-name;, the
-        <command>modifyvdi</command> and <command>modifyhd</command>
-        commands are also supported and mapped internally to the
-        <command>modifymedium</command> command.
-      </para>
-    </note>
-
-    <para>
-      The disk image to modify must be specified either by its UUID, if
-      the medium is registered, or by its filename. Registered images
-      can be listed using <command>VBoxManage list hdds</command>, see
-      <xref linkend="vboxmanage-list" />. A filename must be specified
-      as a valid path, either as an absolute path or as a relative path
-      starting from the current directory.
-    </para>
-
-    <para>
-      The following options are available:
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-        <para>
-          With the <computeroutput>--type</computeroutput> argument, you
-          can change the type of an existing image between the normal,
-          immutable, write-through and other modes. See
-          <xref
-          linkend="hdimagewrites" />.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          For immutable hard disks only, the <computeroutput>--autoreset
-          on|off</computeroutput> option determines whether the disk is
-          automatically reset on every VM startup. See
-          <xref linkend="hdimagewrites" />. By default, autoreset is on.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          The <computeroutput>--compact</computeroutput> option can be
-          used to compact disk images. Compacting removes blocks that
-          only contains zeroes. Using this option will shrink a
-          dynamically allocated image. It will reduce the
-          <emphasis>physical</emphasis> size of the image without
-          affecting the logical size of the virtual disk. Compaction
-          works both for base images and for differencing images created
-          as part of a snapshot.
-        </para>
-
-        <para>
-          For this operation to be effective, it is required that free
-          space in the guest system first be zeroed out using a suitable
-          software tool. For Windows guests, you can use the
-          <command>sdelete</command> tool provided by Microsoft. Run
-          <command>sdelete -z</command> in the guest to zero the free
-          disk space, before compressing the virtual disk image. For
-          Linux, use the <command>zerofree</command> utility which
-          supports ext2/ext3 filesystems. For Mac OS X guests, use the
-          <computeroutput>diskutil secureErase freespace 0
-          /</computeroutput> command from an elevated Terminal.
-        </para>
-
-        <para>
-          Please note that compacting is currently only available for
-          VDI images. A similar effect can be achieved by zeroing out
-          free blocks and then cloning the disk to any other dynamically
-          allocated format. You can use this workaround until compacting
-          is also supported for disk formats other than VDI.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          The <computeroutput>--resize x</computeroutput> option, where
-          x is the desired new total space in megabytes enables you to
-          change the capacity of an existing image. This adjusts the
-          <emphasis>logical</emphasis> size of a virtual disk without
-          affecting the physical size much.
-        </para>
-
-        <para>
-          This option currently works only for VDI and VHD formats, and
-          only for the dynamically allocated variants. It can only be
-          used to expand, but not shrink, the capacity. For example, if
-          you originally created a 10 GB disk which is now full, you can
-          use the <computeroutput>--resize 15360</computeroutput>
-          command to change the capacity to 15 GB (15,360 MB) without
-          having to create a new image and copy all data from within a
-          virtual machine. Note however that this only changes the drive
-          capacity. You will typically next need to use a partition
-          management tool inside the guest to adjust the main partition
-          to fill the drive.
-        </para>
-
-        <para>
-          The <computeroutput>--resizebyte x</computeroutput> option
-          does almost the same thing, except that x is expressed in
-          bytes instead of megabytes.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          The <computeroutput>--move &lt;path&gt;</computeroutput>
-          option can be used to relocate a medium to a different
-          location &lt;path&gt; on the host file system. The path can be
-          either relative to the current directory or absolute.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          The <computeroutput>--setlocation
-          &lt;path&gt;</computeroutput> option can be used to set the
-          new location &lt;path&gt; of the medium on the host file
-          system if the medium has been moved for any reasons. The path
-          can be either relative to the current directory or absolute.
-        </para>
-
-        <note>
-          <para>
-            The new location is used as is, without any sanity checks.
-            The user is responsible for setting the correct path.
-          </para>
-        </note>
-      </listitem>
-
-    </itemizedlist>
-
-  </sect1>
+  <xi:include href="user_man_VBoxManage-modifymedium.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
   <xi:include href="user_man_VBoxManage-clonemedium.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />

trunk/doc/manual/ru_RU/man_VBoxManage-modifymedium.xml

@@ -20 +20 @@
 <refentry id="vboxmanage-modifymedium" lang="en">
   <refentryinfo>
-    <pubdate>August 2019</pubdate>
+    <pubdate>$Date$</pubdate>
     <title>VBoxManage modifymedium</title>
   </refentryinfo>
@@ -32 +32 @@
     <refname>VBoxManage-modifymedium</refname>
     <refpurpose>изменяет характеристики существующего образа диска</refpurpose>
-    <refclass>Oracle VM VirtualBox</refclass>
+    <refclass>&product-name;</refclass>
   </refnamediv>
 

trunk/src/VBox/Frontends/VBoxManage/VBoxManage.cpp

@@ -203 +203 @@
     { "createhd",           USAGE_S_NEWCMD, HELP_CMD_CREATEMEDIUM, handleCreateMedium,         0 }, /* backward compatibility */
     { "createvdi",          USAGE_S_NEWCMD, HELP_CMD_CREATEMEDIUM, handleCreateMedium,         0 }, /* backward compatibility */
-    { "modifymedium",       USAGE_MODIFYMEDIUM,     VBMG_CMD_TODO, handleModifyMedium,         0 },
-    { "modifyhd",           USAGE_MODIFYMEDIUM,     VBMG_CMD_TODO, handleModifyMedium,         0 }, /* backward compatibility */
-    { "modifyvdi",          USAGE_MODIFYMEDIUM,     VBMG_CMD_TODO, handleModifyMedium,         0 }, /* backward compatibility */
+    { "modifymedium",       USAGE_S_NEWCMD, HELP_CMD_MODIFYMEDIUM, handleModifyMedium,         0 },
+    { "modifyhd",           USAGE_S_NEWCMD, HELP_CMD_MODIFYMEDIUM, handleModifyMedium,         0 }, /* backward compatibility */
+    { "modifyvdi",          USAGE_S_NEWCMD, HELP_CMD_MODIFYMEDIUM, handleModifyMedium,         0 }, /* backward compatibility */
     { "clonemedium",        USAGE_S_NEWCMD,  HELP_CMD_CLONEMEDIUM, handleCloneMedium,          0 },
     { "clonehd",            USAGE_S_NEWCMD,  HELP_CMD_CLONEMEDIUM, handleCloneMedium,          0 }, /* backward compatibility */

trunk/src/VBox/Frontends/VBoxManage/VBoxManage.h

@@ -98 +98 @@
 {
     USAGE_INVALID = 0,
-    USAGE_MODIFYMEDIUM,
     USAGE_CREATEHOSTIF,
     USAGE_REMOVEHOSTIF,

trunk/src/VBox/Frontends/VBoxManage/VBoxManageDisk.cpp

@@ -699 +699 @@
             case 'H':   // disk
                 if (cmd != CMD_NONE)
-                    return errorSyntax(USAGE_MODIFYMEDIUM, Disk::tr("Only one command can be specified: '%s'"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("Only one command can be specified: '%s'"), ValueUnion.psz);
                 cmd = CMD_DISK;
                 break;
@@ -705 +705 @@
             case 'D':   // DVD
                 if (cmd != CMD_NONE)
-                    return errorSyntax(USAGE_MODIFYMEDIUM, Disk::tr("Only one command can be specified: '%s'"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("Only one command can be specified: '%s'"), ValueUnion.psz);
                 cmd = CMD_DVD;
                 break;
@@ -711 +711 @@
             case 'L':   // floppy
                 if (cmd != CMD_NONE)
-                    return errorSyntax(USAGE_MODIFYMEDIUM, Disk::tr("Only one command can be specified: '%s'"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("Only one command can be specified: '%s'"), ValueUnion.psz);
                 cmd = CMD_FLOPPY;
                 break;
@@ -799 +799 @@
                     pszFilenameOrUuid = ValueUnion.psz;
                 else
-                    return errorSyntax(USAGE_MODIFYMEDIUM, Disk::tr("Invalid parameter '%s'"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("Invalid parameter '%s'"), ValueUnion.psz);
                 break;
 
@@ -806 +806 @@
                 {
                     if (RT_C_IS_PRINT(c))
-                        return errorSyntax(USAGE_MODIFYMEDIUM, Disk::tr("Invalid option -%c"), c);
+                        return errorSyntax(Disk::tr("Invalid option -%c"), c);
                     else
-                        return errorSyntax(USAGE_MODIFYMEDIUM, Disk::tr("Invalid option case %i"), c);
+                        return errorSyntax(Disk::tr("Invalid option case %i"), c);
                 }
                 else if (c == VERR_GETOPT_UNKNOWN_OPTION)
-                    return errorSyntax(USAGE_MODIFYMEDIUM, Disk::tr("unknown option: %s\n"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("unknown option: %s\n"), ValueUnion.psz);
                 else if (ValueUnion.pDef)
-                    return errorSyntax(USAGE_MODIFYMEDIUM, "%s: %Rrs", ValueUnion.pDef->pszLong, c);
+                    return errorSyntax("%s: %Rrs", ValueUnion.pDef->pszLong, c);
                 else
-                    return errorSyntax(USAGE_MODIFYMEDIUM, Disk::tr("error: %Rrs"), c);
+                    return errorSyntax(Disk::tr("error: %Rrs"), c);
         }
     }
@@ -823 +823 @@
 
     if (!pszFilenameOrUuid)
-        return errorSyntax(USAGE_MODIFYMEDIUM, Disk::tr("Medium name or UUID required"));
+        return errorSyntax(Disk::tr("Medium name or UUID required"));
 
     if (!fModifyMediumType
@@ -834 +834 @@
         && !fModifyDescription
         )
-        return errorSyntax(USAGE_MODIFYMEDIUM, Disk::tr("No operation specified"));
+        return errorSyntax(Disk::tr("No operation specified"));
 
     /* Always open the medium if necessary, there is no other way. */

trunk/src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp

@@ -584 +584 @@
                      "\n");
 
-    const char *pcszSep1 = " ";
-    const char *pcszSep2 = "         ";
-    if (enmCommand != USAGE_S_ALL)
-    {
-        pcszSep1 = "VBoxManage";
-        pcszSep2 = "";
-    }
-
-#define SEP pcszSep1, pcszSep2
-
-    if (enmCommand == USAGE_MODIFYMEDIUM || enmCommand == USAGE_S_ALL)
-        RTStrmPrintf(pStrm,
-                           "%s modifymedium %s    [disk|dvd|floppy] <uuid|filename>\n"
-                     "                            [--type normal|writethrough|immutable|shareable|\n"
-                     "                                    readonly|multiattach]\n"
-                     "                            [--autoreset on|off]\n"
-                     "                            [--property <name=[value]>]\n"
-                     "                            [--compact]\n"
-                     "                            [--resize <megabytes>|--resizebyte <bytes>]\n"
-                     "                            [--move <path>]\n"
-                     "                            [--setlocation <path>]\n"
-                     "                            [--description <description string>]"
-                     "\n", SEP);
-
 #ifndef VBOX_ONLY_DOCS /* Converted to man page, not needed. */
     if (enmCommand == USAGE_S_ALL)