docs: virsh: clarify behavior of send-key

https://bugzilla.redhat.com/show_bug.cgi?id=860004
(cherry picked from commit 2143ced7f557db6486623c8ce0ca296aeb7b8392)

diff --git a/tools/virsh.pod b/tools/virsh.pod
index c8833e0305a32ffae31be85b1ae0bff147798c47..fcc50c384c307273d49e7115489e9c73c89d4bdf 100644 (file)
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -1119,6 +1119,10 @@ will be held for that many milliseconds.  The default codeset is
 B<linux>, but use of the I<--codeset> option allows other codesets to
 be chosen.
 
+If multiple keycodes are specified, they are all sent simultaneously
+to the guest, and they may be received in random order. If you need
+distinct keypresses, you must use multiple send-key invocations.
+
 =over 4
 
 =item B<linux>
@@ -1183,10 +1187,14 @@ bit of the first byte. No symbolic names are provided.
 =back
 
 B<Examples>
-  # send three strokes 'k', 'e', 'y', using xt codeset
+  # send three strokes 'k', 'e', 'y', using xt codeset. these
+  # are all pressed simultaneously and may be received by the guest
+  # in random order
   virsh send-key dom --codeset xt 37 18 21
+
   # send one stroke 'right-ctrl+C'
   virsh send-key dom KEY_RIGHTCTRL KEY_C
+
   # send a tab, held for 1 second
   virsh send-key --holdtime 1000 0xf