[Xen-changelog] [xen master] docs: Give advice on dealing with quoting special characters

[patchbot@xxxxxxx]

commit f70cf6132e37e5e035895a06f8452a90d073c329
Author:     George Dunlap <george.dunlap@xxxxxxxxxxxxx>
AuthorDate: Wed Apr 23 14:19:43 2014 +0100
Commit:     Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>
CommitDate: Thu Apr 24 16:22:14 2014 +0100

    docs: Give advice on dealing with quoting special characters
    
    The man page mentions passing config snippets key=val in xl create.
    Unfortunately, the config syntax contain characters which are
    interpreted (and often discarded) by the shell before getting passed
    in, resulting in a parsing error.
    
    For example:
    
    xl create hvm.cfg cpus="0-3"
    
    The shell will eat the quotes and pass 'cpus=0-3' to xl, which won't
    parse properly without the quotes.
    
    Mention this in the man page, and recommend the use of single quotes, as 
well
    as separating multiple arguments with a semicolon, thus:
    
    xl create hvm.cfg 'cpus="0-3"; pci=["1.0","1.1"]'
    
    Signed-off-by: George Dunlap <george.dunlap@xxxxxxxxxxxxx>
    Acked-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
---
 docs/man/xl.pod.1 |   21 ++++++++++++++++++---
 1 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1
index 7c03de6..30bd4bf 100644
--- a/docs/man/xl.pod.1
+++ b/docs/man/xl.pod.1
@@ -152,6 +152,12 @@ It is possible to pass I<key=value> pairs on the command 
line to provide
 options as if they were written in the configuration file; these override
 whatever is in the I<configfile>.
 
+NB: Many config options require characters such as quotes or brackets
+which are interpreted by the shell (and often discarded) before being
+passed to xl, resulting in xl being unable to parse the value
+correctly.  A simple work-around is to put all extra options within a
+single set of quotes, separated by semicolons.  (See below for an example.)
+
 =back
 
 B<EXAMPLES>
@@ -165,6 +171,13 @@ B<EXAMPLES>
 This creates a domain with the file /etc/xen/DebianLenny, and returns as
 soon as it is run.
 
+=item I<with extra parameters>
+
+  xl create hvm.cfg 'cpus="0-3"; pci=["01:05.1","01:05.2"]'
+
+This creates a domain with the file hvm.cfg, but additionally pins it to
+cpus 0-3, and passes through two PCI devices.
+
 =back
 
 =item B<config-update> B<domid> [I<configfile>] [I<OPTIONS>]
@@ -186,9 +199,11 @@ Use the given configuration file.
 
 =item B<key=value>
 
-It is possible to pass I<key=value> pairs on the command line to provide
-options as if they were written in the configuration file; these override
-whatever is in the I<configfile>.
+It is possible to pass I<key=value> pairs on the command line to
+provide options as if they were written in the configuration file;
+these override whatever is in the I<configfile>.  Please see the note
+under I<create> on handling special characters when passing
+I<key=value> pairs on the command line.
 
 =back
 
--
generated by git-patchbot for /home/xen/git/xen.git#master

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog