man: add examples from previous man pages

21 files changed, 440 insertions, 1 deletions

diff --git a/man/lvchange.8.end b/man/lvchange.8.end
new file mode 100644
index 000000000..5046d5d3c
--- /dev/null
+++ b/man/lvchange.8.end
@@ -0,0 +1,6 @@
+.EXAMPLES
+
+Change LV permission to read-only:
+.sp
+.B lvchange \-pr vg00/lvol1
+
diff --git a/man/lvconvert.8.end b/man/lvconvert.8.end
new file mode 100644
index 000000000..133af0d7a
--- /dev/null
+++ b/man/lvconvert.8.end
@@ -0,0 +1,95 @@
+.SH EXAMPLES
+
+Convert a linear LV to a two-way mirror LV:
+.br
+.B lvconvert \-\-type mirror \-\-mirrors 1 vg/lvol1
+
+Convert a linear LV to a two-way RAID1 LV:
+.br
+.B lvconvert \-\-type raid1 \-\-mirrors 1 vg/lvol1
+
+Convert a mirror LV to use an in\-memory log:
+.br
+.B lvconvert \-\-mirrorlog core vg/lvol1
+
+Convert a mirror LV to use a disk log:
+.br
+.B lvconvert \-\-mirrorlog disk vg/lvol1
+
+Convert a mirror or raid1 LV to a linear LV:
+.br
+.B lvconvert --type linear vg/lvol1
+
+Convert a mirror LV to a raid1 LV with the same number of images:
+.br
+.B lvconvert \-\-type raid1 vg/lvol1
+
+Convert a linear LV to a two-way mirror LV, allocating new extents from specific
+PV ranges:
+.br
+.B lvconvert \-\-mirrors 1 vg/lvol1 /dev/sda:0\-15 /dev/sdb:0\-15
+
+Convert a mirror LV to a linear LV, freeing physical extents from a specific PV:
+.br
+.B lvconvert \-\-type linear vg/lvol1 /dev/sda
+
+Split one image from a mirror or raid1 LV, making it a new LV:
+.br
+.B lvconvert \-\-splitmirrors 1 \-\-name lv_split vg/lvol1
+
+Split one image from a raid1 LV, and track changes made to the raid1 LV
+while the split image remains detached:
+.br
+.B lvconvert \-\-splitmirrors 1 \-\-trackchanges vg/lvol1
+
+Merge an image (that was previously created with \-\-splitmirrors and
+\-\-trackchanges) back into the original raid1 LV:
+.br
+.B lvconvert \-\-mergemirrors vg/lvol1_rimage_1
+
+Replace PV /dev/sdb1 with PV /dev/sdf1 in a raid1/4/5/6/10 LV:
+.br
+.B lvconvert \-\-replace /dev/sdb1 vg/lvol1 /dev/sdf1
+
+Replace 3 PVs /dev/sd[b-d]1 with PVs /dev/sd[f-h]1 in a raid1 LV:
+.br
+.B lvconvert \-\-replace /dev/sdb1 \-\-replace /dev/sdc1 \-\-replace /dev/sdd1
+.RS
+.B vg/lvol1 /dev/sd[fgh]1
+.RE
+
+Replace the maximum of 2 PVs /dev/sd[bc]1 with PVs /dev/sd[gh]1 in a raid6 LV:
+.br
+.B lvconvert \-\-replace /dev/sdb1 \-\-replace /dev/sdc1 vg/lvol1 /dev/sd[gh]1
+
+Convert an LV into a thin LV in the specified thin pool.  The existing LV
+is used as an external read\-only origin for the new thin LV.
+.br
+.B lvconvert \-\-type thin \-\-thinpool vg/tpool1 vg/lvol1
+
+Convert an LV into a thin LV in the specified thin pool.  The existing LV
+is used as an external read\-only origin for the new thin LV, and is
+renamed "external":
+.br
+.B lvconvert \-\-type thin \-\-thinpool vg/tpool1
+.RS
+.B \-\-originname external vg/lvol1
+.RE
+
+Convert an LV to a cache pool LV using another specified LV for cache pool
+metadata:
+.br
+.B lvconvert \-\-type cache-pool \-\-poolmetadata vg/poolmeta1 vg/lvol1
+
+Convert an LV to a cache LV using the specified cache pool and chunk size:
+.br
+.B lvconvert \-\-type cache \-\-cachepool vg/cpool1 \-c 128 vg/lvol1
+
+Detach and keep the cache pool from a cache LV:
+.br
+.B lvconvert \-\-splitcache vg/lvol1
+
+Detach and remove the cache pool from a cache LV:
+.br
+.B lvconvert \-\-uncache vg/lvol1
+
diff --git a/man/lvcreate.8.end b/man/lvcreate.8.end
new file mode 100644
index 000000000..74ae599cb
--- /dev/null
+++ b/man/lvcreate.8.end
@@ -0,0 +1,98 @@
+.SH EXAMPLES
+
+Create a striped LV with 3 stripes, a stripe size of 8KiB and a size of 100MiB.
+The LV name is chosen by lvcreate.
+.br
+.B lvcreate \-i 3 \-I 8 \-L 100m vg00
+
+Create a raid1 LV with two images, and a useable size of 500 MiB. This
+operation requires two devices, one for each mirror image. RAID metadata
+(superblock and bitmap) is also included on the two devices.
+.br
+.B lvcreate \-\-type raid1 \-m1 \-L 500m \-n mylv vg00
+
+Create a mirror LV with two images, and a useable size of 500 MiB.
+This operation requires three devices: two for mirror images and
+one for a disk log.
+.br
+.B lvcreate \-\-type mirror \-m1 \-L 500m \-n mylv vg00
+
+Create a mirror LV with 2 images, and a useable size of 500 MiB.
+This operation requires 2 devices because the log is in memory.
+.br
+.B lvcreate \-\-type mirror \-m1 \-\-mirrorlog core \-L 500m \-n mylv vg00
+
+Create a copy\-on\-write snapshot of an LV:
+.br
+.B lvcreate \-\-snapshot \-\-size 100m \-\-name mysnap vg00/mylv
+
+Create a copy\-on\-write snapshot with a size sufficient
+for overwriting 20% of the size of the original LV.
+.br
+.B lvcreate \-s \-l 20%ORIGIN \-n mysnap vg00/mylv
+
+Create a sparse LV with 1TiB of virtual space, and actual space just under
+100MiB.
+.br
+.B lvcreate \-\-snapshot \-\-virtualsize 1t \-\-size 100m \-\-name mylv vg00
+
+Create a linear LV with a usable size of 64MiB on specific physical extents.
+.br
+.B lvcreate \-L 64m \-n mylv vg00 /dev/sda:0\-7 /dev/sdb:0\-7
+
+Create a RAID5 LV with a usable size of 5GiB, 3 stripes, a stripe size of
+64KiB, using a total of 4 devices (including one for parity).
+.br
+.B lvcreate \-\-type raid5 \-L 5G \-i 3 \-I 64 \-n mylv vg00
+
+Create a RAID5 LV using all of the free space in the VG and spanning all the
+PVs in the VG (note that the command will fail if there are more than 8 PVs in
+the VG, in which case \fB\-i 7\fP must be used to get to the current maximum of
+8 devices including parity for RaidLVs).
+.br
+.B lvcreate \-\-config allocation/raid_stripe_all_devices=1
+.RS
+.B \-\-type raid5 \-l 100%FREE \-n mylv vg00
+.RE
+
+Create RAID10 LV with a usable size of 5GiB, using 2 stripes, each on
+a two-image mirror. (Note that the \fB-i\fP and \fB-m\fP arguments behave
+differently:
+\fB-i\fP specifies the total number of stripes,
+but \fB-m\fP specifies the number of images in addition
+to the first image).
+.br
+.B lvcreate \-\-type raid10 \-L 5G \-i 2 \-m 1 \-n mylv vg00
+
+Create a 1TiB thin LV, first creating a new thin pool for it, where
+the thin pool has 100MiB of space, uses 2 stripes, has a 64KiB stripe
+size, and 256KiB chunk size.
+.br
+.B lvcreate \-\-type thin \-\-name mylv \-\-thinpool mypool
+.RS
+.B \-V 1t \-L 100m \-i 2 \-I 64 \-c 256 vg00
+.RE
+
+Create a thin snapshot of a thin LV (the size option must not be
+used, otherwise a copy-on-write snapshot would be created).
+.br
+.B lvcreate \-\-snapshot \-\-name mysnap vg00/thinvol
+
+Create a thin snapshot of the read-only inactive LV named "origin"
+which becomes an external origin for the thin snapshot LV.
+.br
+.B lvcreate \-\-snapshot \-\-name mysnap \-\-thinpool mypool vg00/origin
+
+Create a cache pool from a fast physical device. The cache pool can
+then be used to cache an LV.
+.br
+.B lvcreate \-\-type cache-pool \-L 1G \-n my_cpool vg00 /dev/fast1
+
+Create a cache LV, first creating a new origin LV on a slow physical device,
+then combining the new origin LV with an existing cache pool.
+.br
+.B lvcreate \-\-type cache \-\-cachepool my_cpool
+.RS
+.B \-L 100G \-n mylv vg00 /dev/slow1
+.RE
+
diff --git a/man/lvextend.8.end b/man/lvextend.8.end
new file mode 100644
index 000000000..6d197de81
--- /dev/null
+++ b/man/lvextend.8.end
@@ -0,0 +1,16 @@
+.SH EXAMPLES
+
+Extend the size of an LV by 54MiB, using a specific PV.
+.br
+.B lvextend \-L +54 vg01/lvol10 /dev/sdk3
+
+Extend the size of an LV by the amount of free
+space on PV /dev/sdk3. This is equivalent to specifying
+"\-l +100%PVS" on the command line.
+.br
+.B lvextend vg01/lvol01 /dev/sdk3
+
+Extend an LV by 16MiB using specific physical extents.
+.br
+.B lvextend \-L+16m vg01/lvol01 /dev/sda:8\-9 /dev/sdb:8\-9
+
diff --git a/man/lvm-lvpoll.8.end b/man/lvm-lvpoll.8.end
new file mode 100644
index 000000000..440f1e168
--- /dev/null
+++ b/man/lvm-lvpoll.8.end
@@ -0,0 +1,34 @@
+.SH NOTES
+
+.IP \[bu] 3
+To find the name of the pvmove LV that was created by an original
+\fBpvmove /dev/name\fP command, use the command:
+.br
+\fBlvs -a -S move_pv=/dev/name\fP.
+
+.SH EXAMPLES
+
+Continue polling a pvmove operation:
+.br
+.B lvm lvpoll --polloperation pvmove vg00/pvmove0
+
+Abort a pvmove operation:
+.br
+.B lvm lvpoll --polloperation pvmove --abort vg00/pvmove0
+
+Continue polling a mirror conversion:
+.br
+.B lvm lvpoll --polloperation convert vg00/lvmirror
+
+Continue mirror repair:
+.br
+.B lvm lvpoll --polloperation convert vg/damaged_mirror --handlemissingpvs
+
+Continue snapshot merge:
+.br
+.B lvm lvpoll --polloperation merge vg/snapshot_old
+
+Continue thin snapshot merge:
+.br
+.B lvm lvpoll --polloperation merge_thin vg/thin_snapshot
+
diff --git a/man/lvreduce.8.end b/man/lvreduce.8.end
new file mode 100644
index 000000000..59fde52f0
--- /dev/null
+++ b/man/lvreduce.8.end
@@ -0,0 +1,5 @@
+.SH EXAMPLES
+
+Reduce the size of an LV by 3 logical extents:
+.br
+.B lvreduce \-l \-3 vg00/lvol1
diff --git a/man/lvremove.8.end b/man/lvremove.8.end
new file mode 100644
index 000000000..5c70ed644
--- /dev/null
+++ b/man/lvremove.8.end
@@ -0,0 +1,11 @@
+.SH EXAMPLES
+
+Remove an active LV without asking for confirmation.
+.br
+.B lvremove \-f vg00/lvol1
+
+Remove all LVs the specified VG.
+.br
+.B lvremove vg00
+
+
diff --git a/man/lvrename.8.end b/man/lvrename.8.end
new file mode 100644
index 000000000..3409b8a8c
--- /dev/null
+++ b/man/lvrename.8.end
@@ -0,0 +1,10 @@
+.SH EXAMPLES
+
+Rename "lvold" to "lvnew":
+.br
+.B lvrename /dev/vg02/lvold vg02/lvnew
+
+An alternate syntax to rename "lvold" to "lvnew":
+.br
+.B lvrename vg02 lvold lvnew
+
diff --git a/man/lvresize.8.end b/man/lvresize.8.end
new file mode 100644
index 000000000..a336d6216
--- /dev/null
+++ b/man/lvresize.8.end
@@ -0,0 +1,6 @@
+.SH EXAMPLES
+
+Extend an LV by 16MB using specific physical extents:
+.br
+.B lvresize \-L+16M vg1/lv1 /dev/sda:0\-1 /dev/sdb:0\-1
+
diff --git a/man/pvchange.8.end b/man/pvchange.8.end
new file mode 100644
index 000000000..a524d071d
--- /dev/null
+++ b/man/pvchange.8.end
@@ -0,0 +1,6 @@
+.SH EXAMPLES
+
+Disallow the allocation of physical extents on a PV (e.g. because of
+disk errors, or because it will be removed after freeing it).
+.br
+.B pvchange \-x n /dev/sdk1
diff --git a/man/pvck.8.end b/man/pvck.8.end
new file mode 100644
index 000000000..67af2389a
--- /dev/null
+++ b/man/pvck.8.end
@@ -0,0 +1,8 @@
+.SH EXAMPLES
+
+If the partition table is corrupted or lost on /dev/sda, and you suspect
+there was an LVM partition at approximately 100 MiB, then this
+area of the disk can be scanned using the \fB\-\-labelsector\fP
+parameter with a value of 204800 (100 * 1024 * 1024 / 512 = 204800).
+.br
+.B pvck \-\-labelsector 204800 /dev/sda
diff --git a/man/pvcreate.8.end b/man/pvcreate.8.end
new file mode 100644
index 000000000..b1b0f3e53
--- /dev/null
+++ b/man/pvcreate.8.end
@@ -0,0 +1,13 @@
+.SH EXAMPLES
+
+Initialize a partition and a full device.
+.br
+.B pvcreate /dev/sdc4 /dev/sde
+
+If a device is a 4KiB sector drive that compensates for windows
+partitioning (sector 7 is the lowest aligned logical block, the 4KiB
+sectors start at LBA -1, and consequently sector 63 is aligned on a 4KiB
+boundary) manually account for this when initializing for use by LVM.
+.br
+.B pvcreate \-\-dataalignmentoffset 7s /dev/sdb
+
diff --git a/man/pvmove.8.end b/man/pvmove.8.end
index c3eaea19a..94c2f2305 100644
--- a/man/pvmove.8.end
+++ b/man/pvmove.8.end
@@ -45,3 +45,49 @@ LVs are removed, leaving behind the segments on the destination PV.  If an
 abort is issued during the move, all LVs being moved will remain on the
 source PV.
 
+.SH EXAMPLES
+
+Move all physical extents that are used by simple LVs on the specified PV to
+free physical extents elsewhere in the VG.
+.br
+.B pvmove /dev/sdb1
+
+Use a specific destination PV when moving physical extents.
+.br
+.B pvmove /dev/sdb1 /dev/sdc1
+
+Move extents belonging to a single LV.
+.br
+.B pvmove \-n lvol1 /dev/sdb1 /dev/sdc1
+
+Rather than moving the contents of an entire device, it is possible to
+move a range of physical extents, for example numbers 1000 to 1999
+inclusive on the specified PV.
+.br
+.B pvmove /dev/sdb1:1000\-1999
+
+A range of physical extents to move can be specified as start+length. For
+example, starting from PE 1000. (Counting starts from 0, so this refers to the
+1001st to the 2000th PE inclusive.)
+.br
+.B pvmove /dev/sdb1:1000+1000
+
+Move a range of physical extents to a specific PV (which must have
+sufficient free extents).
+.br
+.B pvmove /dev/sdb1:1000\-1999 /dev/sdc1
+
+Move a range of physical extents to specific new extents on a new PV.
+.br
+.B pvmove /dev/sdb1:1000\-1999 /dev/sdc1:0\-999
+
+If the source and destination are on the same disk, the
+\fBanywhere\fP allocation policy is needed.
+.br
+.B pvmove \-\-alloc anywhere /dev/sdb1:1000\-1999 /dev/sdb1:0\-999
+
+The part of a specific LV present within in a range of physical
+extents can also be picked out and moved.
+.br
+.B pvmove \-n lvol1 /dev/sdb1:1000\-1999 /dev/sdc1
+
diff --git a/man/pvresize.8.end b/man/pvresize.8.end
new file mode 100644
index 000000000..c3ed7020d
--- /dev/null
+++ b/man/pvresize.8.end
@@ -0,0 +1,17 @@
+.SH NOTES
+
+.IP \[bu] 3
+pvresize will refuse to shrink a PV if it has allocated extents beyond the
+new end.
+
+.SH EXAMPLES
+
+Expand a PV after enlarging the partition.
+.br
+.B pvresize /dev/sda1
+
+Shrink a PV prior to shrinking the partition (ensure that the PV size is
+appropriate for the intended new partition size).
+.br
+.B pvresize \-\-setphysicalvolumesize 40G /dev/sda1
+
diff --git a/man/vgcfgrestore.8.end b/man/vgcfgrestore.8.end
new file mode 100644
index 000000000..95eed8019
--- /dev/null
+++ b/man/vgcfgrestore.8.end
@@ -0,0 +1,11 @@
+.SH NOTES
+
+.IP \[bu] 3
+To replace PVs, \fBvgdisplay \-\-partial \-\-verbose\fP will show the
+UUIDs and sizes of any PVs that are no longer present. If a PV in the VG
+is lost and you wish to substitute another of the same size, use
+\fBpvcreate \-\-restorefile filename \-\-uuid uuid\fP (plus additional
+arguments as appropriate) to initialise it with the same UUID as the
+missing PV. Repeat for all other missing PVs in the VG.  Then use
+\fBvgcfgrestore \-\-file filename\fP to restore the volume group's
+metadata.
diff --git a/man/vgchange.8.end b/man/vgchange.8.end
new file mode 100644
index 000000000..86b98ce71
--- /dev/null
+++ b/man/vgchange.8.end
@@ -0,0 +1,10 @@
+.EXAMPLES
+
+Activate all LVs in all VGs on all existing devices.
+.br
+.B vgchange \-a y
+
+Change the maximum number of LVs for an inactive VG.
+.br
+.B vgchange \-l 128 vg00
+
diff --git a/man/vgcreate.8.end b/man/vgcreate.8.end
new file mode 100644
index 000000000..c9f5b5f67
--- /dev/null
+++ b/man/vgcreate.8.end
@@ -0,0 +1,6 @@
+.EXAMPLES
+
+Create a VG with two PVs, using the default physical extent size.
+.br
+.B vgcreate myvg /dev/sdk1 /dev/sdl1
+
diff --git a/man/vgextend.8.end b/man/vgextend.8.end
new file mode 100644
index 000000000..a0887a2d3
--- /dev/null
+++ b/man/vgextend.8.end
@@ -0,0 +1,13 @@
+.SH NOTES
+
+If the specified PVs have not yet been initialized with pvcreate,
+vgextend will initialize them. In this case the PV options apply,
+e.g. \-\-labelsector, \-\-metadatasize, \-\-metadataignore,
+\-\-pvmetadatacopies, \-\-dataalignment, \-\-dataalignmentoffset.
+
+.SH EXAMPLES
+
+Add two PVs to a VG.
+.br
+.B vgextend vg00 /dev/sda4 /dev/sdn1
+
diff --git a/man/vgimportclone.8.end b/man/vgimportclone.8.end
index 45d244fc5..f914553d9 100644
--- a/man/vgimportclone.8.end
+++ b/man/vgimportclone.8.end
@@ -1,9 +1,20 @@
 .SH NOTES
-.
+
+.IP \[bu] 3
 vgimportclone can be used to import a VG from duplicated PVs (e.g. created
 by a hardware snapshot of the PV devices).
 
+.IP \[bu] 3
 A duplicated VG cannot used until it is made to coexist with the original
 VG.  vgimportclone renames the VG associated with the specified PVs and
 changes the associated VG and PV UUIDs.
 
+.SH EXAMPLES
+
+An original VG "vg00" has PVs "/dev/sda" and "/dev/sdb".
+The corresponding PVs from a hardware snapshot are "/dev/sdc" and "/dev/sdd".
+Rename the VG associated with "/dev/sdc" and "/dev/sdd" from "vg00" to "vg00_snap"
+(and change associated UUIDs).
+.br
+.B vgimportclone \-\-basevgname vg00_snap /dev/sdc /dev/sdd
+
diff --git a/man/vgmerge.8.end b/man/vgmerge.8.end
new file mode 100644
index 000000000..9787c6a82
--- /dev/null
+++ b/man/vgmerge.8.end
@@ -0,0 +1,7 @@
+.SH EXAMPLES
+
+Merge an inactive VG named "vg00" into the active or inactive VG named
+"databases", giving verbose runtime information.
+.br
+.B vgmerge \-v databases vg00
+
diff --git a/man/vgrename.8.end b/man/vgrename.8.end
new file mode 100644
index 000000000..98eeb532a
--- /dev/null
+++ b/man/vgrename.8.end
@@ -0,0 +1,10 @@
+.SH EXAMPLES
+
+Rename VG "vg02" to "myvg":
+.br
+.B vgrename "vg02" "myvg"
+
+Rename the VG with the specified UUID to "myvg".
+.br
+.B vgrename Zvlifi\-Ep3t\-e0Ng\-U42h\-o0ye\-KHu1\-nl7Ns4 myvg
+