VirtualBox

Changeset 94218 in vbox for trunk/doc/manual


Ignore:
Timestamp:
Mar 14, 2022 9:02:16 AM (3 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
150474
Message:

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

Location:
trunk/doc/manual
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/manual/Config.kmk

    r94217 r94218  
    7070        man_VBoxManage-showmediuminfo.xml \
    7171        man_VBoxManage-createmedium.xml \
     72        man_VBoxManage-modifymedium.xml \
    7273        man_VBoxManage-clonemedium.xml \
    7374        man_VBoxManage-mediumproperty.xml \
  • trunk/doc/manual/en_US/man_VBoxManage-modifymedium.xml

    r87075 r94218  
    2020<refentry id="vboxmanage-modifymedium" lang="en">
    2121  <refentryinfo>
    22     <pubdate>August 2019</pubdate>
     22    <pubdate>$Date$</pubdate>
    2323    <title>VBoxManage modifymedium</title>
    2424  </refentryinfo>
     
    3232    <refname>VBoxManage-modifymedium</refname>
    3333    <refpurpose>change the characteristics of an existing disk image</refpurpose>
    34     <refclass>Oracle VM VirtualBox</refclass>
     34    <refclass>&product-name;</refclass>
    3535  </refnamediv>
    3636
  • trunk/doc/manual/en_US/user_VBoxManage.xml

    r94217 r94218  
    355355  <xi:include href="user_man_VBoxManage-createmedium.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    356356
    357   <sect1 id="vboxmanage-modifymedium">
    358 
    359     <title>VBoxManage modifymedium</title>
    360 
    361     <para>
    362       With the <command>modifymedium</command> command, you can change
    363       the characteristics of a disk image after it has been created.
    364     </para>
    365 
    366 <screen>VBoxManage modifymedium  [disk|dvd|floppy]    &lt;uuid|filename&gt;
    367                          [--type normal|writethrough|immutable|shareable|
    368                                  readonly|multiattach]
    369                          [--autoreset on|off]
    370                          [--property &lt;name=[value]&gt;]
    371                          [--compact]
    372                          [--resize &lt;megabytes&gt;|--resizebyte &lt;bytes&gt;]
    373                          [--move &lt;path&gt;]
    374                          [--setlocation &lt;path&gt;]</screen>
    375 
    376     <note>
    377       <para>
    378         For compatibility with earlier versions of &product-name;, the
    379         <command>modifyvdi</command> and <command>modifyhd</command>
    380         commands are also supported and mapped internally to the
    381         <command>modifymedium</command> command.
    382       </para>
    383     </note>
    384 
    385     <para>
    386       The disk image to modify must be specified either by its UUID, if
    387       the medium is registered, or by its filename. Registered images
    388       can be listed using <command>VBoxManage list hdds</command>, see
    389       <xref linkend="vboxmanage-list" />. A filename must be specified
    390       as a valid path, either as an absolute path or as a relative path
    391       starting from the current directory.
    392     </para>
    393 
    394     <para>
    395       The following options are available:
    396     </para>
    397 
    398     <itemizedlist>
    399 
    400       <listitem>
    401         <para>
    402           With the <computeroutput>--type</computeroutput> argument, you
    403           can change the type of an existing image between the normal,
    404           immutable, write-through and other modes. See
    405           <xref
    406           linkend="hdimagewrites" />.
    407         </para>
    408       </listitem>
    409 
    410       <listitem>
    411         <para>
    412           For immutable hard disks only, the <computeroutput>--autoreset
    413           on|off</computeroutput> option determines whether the disk is
    414           automatically reset on every VM startup. See
    415           <xref linkend="hdimagewrites" />. By default, autoreset is on.
    416         </para>
    417       </listitem>
    418 
    419       <listitem>
    420         <para>
    421           The <computeroutput>--compact</computeroutput> option can be
    422           used to compact disk images. Compacting removes blocks that
    423           only contains zeroes. Using this option will shrink a
    424           dynamically allocated image. It will reduce the
    425           <emphasis>physical</emphasis> size of the image without
    426           affecting the logical size of the virtual disk. Compaction
    427           works both for base images and for differencing images created
    428           as part of a snapshot.
    429         </para>
    430 
    431         <para>
    432           For this operation to be effective, it is required that free
    433           space in the guest system first be zeroed out using a suitable
    434           software tool. For Windows guests, you can use the
    435           <command>sdelete</command> tool provided by Microsoft. Run
    436           <command>sdelete -z</command> in the guest to zero the free
    437           disk space, before compressing the virtual disk image. For
    438           Linux, use the <command>zerofree</command> utility which
    439           supports ext2/ext3 filesystems. For Mac OS X guests, use the
    440           <computeroutput>diskutil secureErase freespace 0
    441           /</computeroutput> command from an elevated Terminal.
    442         </para>
    443 
    444         <para>
    445           Please note that compacting is currently only available for
    446           VDI images. A similar effect can be achieved by zeroing out
    447           free blocks and then cloning the disk to any other dynamically
    448           allocated format. You can use this workaround until compacting
    449           is also supported for disk formats other than VDI.
    450         </para>
    451       </listitem>
    452 
    453       <listitem>
    454         <para>
    455           The <computeroutput>--resize x</computeroutput> option, where
    456           x is the desired new total space in megabytes enables you to
    457           change the capacity of an existing image. This adjusts the
    458           <emphasis>logical</emphasis> size of a virtual disk without
    459           affecting the physical size much.
    460         </para>
    461 
    462         <para>
    463           This option currently works only for VDI and VHD formats, and
    464           only for the dynamically allocated variants. It can only be
    465           used to expand, but not shrink, the capacity. For example, if
    466           you originally created a 10 GB disk which is now full, you can
    467           use the <computeroutput>--resize 15360</computeroutput>
    468           command to change the capacity to 15 GB (15,360 MB) without
    469           having to create a new image and copy all data from within a
    470           virtual machine. Note however that this only changes the drive
    471           capacity. You will typically next need to use a partition
    472           management tool inside the guest to adjust the main partition
    473           to fill the drive.
    474         </para>
    475 
    476         <para>
    477           The <computeroutput>--resizebyte x</computeroutput> option
    478           does almost the same thing, except that x is expressed in
    479           bytes instead of megabytes.
    480         </para>
    481       </listitem>
    482 
    483       <listitem>
    484         <para>
    485           The <computeroutput>--move &lt;path&gt;</computeroutput>
    486           option can be used to relocate a medium to a different
    487           location &lt;path&gt; on the host file system. The path can be
    488           either relative to the current directory or absolute.
    489         </para>
    490       </listitem>
    491 
    492       <listitem>
    493         <para>
    494           The <computeroutput>--setlocation
    495           &lt;path&gt;</computeroutput> option can be used to set the
    496           new location &lt;path&gt; of the medium on the host file
    497           system if the medium has been moved for any reasons. The path
    498           can be either relative to the current directory or absolute.
    499         </para>
    500 
    501         <note>
    502           <para>
    503             The new location is used as is, without any sanity checks.
    504             The user is responsible for setting the correct path.
    505           </para>
    506         </note>
    507       </listitem>
    508 
    509     </itemizedlist>
    510 
    511   </sect1>
     357  <xi:include href="user_man_VBoxManage-modifymedium.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    512358
    513359  <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

    r93478 r94218  
    2020<refentry id="vboxmanage-modifymedium" lang="en">
    2121  <refentryinfo>
    22     <pubdate>August 2019</pubdate>
     22    <pubdate>$Date$</pubdate>
    2323    <title>VBoxManage modifymedium</title>
    2424  </refentryinfo>
     
    3232    <refname>VBoxManage-modifymedium</refname>
    3333    <refpurpose>изменяет характеристики существующего образа диска</refpurpose>
    34     <refclass>Oracle VM VirtualBox</refclass>
     34    <refclass>&product-name;</refclass>
    3535  </refnamediv>
    3636
Note: See TracChangeset for help on using the changeset viewer.

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